When a model calls the wrong tool, the instinct is to blame the model. Usually the tool set earned it. The model selects tools by reading exactly two things — the name and the description — and most tool sets are written as if those fields were documentation for a colleague who can ask follow-up questions. They are not. They are the prompt, and tool selection is a prompting problem.

This is the last piece of the structured-outputs stack this cluster covers; the pillar, how to get reliable JSON out of LLMs, maps the whole territory, and function calling patterns that work covers the loop shapes these tools plug into.

Names: verb first, boring on purpose

A tool name should read as an action the model can take: search_orders, get_order_detail, create_draft_reply, escalate_to_human. Verb plus object, snake_case, no abbreviations you would have to explain in the description anyway.

The anti-patterns are all nouns and vagueness. orders — is that search, fetch, or create? data_api — of what? helper — the model will call it for everything or nothing. Models weight names heavily at selection time because names are short and appear in the model's own output when it makes the call; a name that encodes the action correctly is doing selection work before the description is even read.

Two smaller conventions that pay off: keep sibling tools parallel (get_order / get_customer / get_invoice, not get_order / fetch_customer / invoice_lookup), and reserve exactly one verb per operation class. If search_ means "text query, many results" in one tool, it should mean that in all of them.

Descriptions: lead with when, not what

The most common description mistake is describing what the tool does and never saying when to call it. The model already gets a hint of what from the name and the parameter schema; the decision it has to make is whether this tool, now. So the first sentence of every description should be the selection criterion:

Bad:  "Searches the product catalog."
Good: "Use this when the user asks about a product by name, keyword, or
       category and you do not have a product ID. Searches the catalog
       and returns up to 10 matches with IDs, names, and prices. Do NOT
       use this when you already have a product ID; use get_product
       instead. Results only include in-stock items."

That second version follows the shape Anthropic's tool-use documentation explicitly recommends: for complex tools, a detailed description of at least 3-4 sentences — what it does, when to use it, what the parameters mean, what it does not cover — rather than a single line. As of 2026-07 this advice generalizes across providers in our experience: GPT-4o and Gemini 2.5 also select more accurately when the when-to-use boundary is spelled out. One line is fine for tools with no plausible neighbor (get_current_time); anything that shares territory with another tool needs the longer treatment.

Notice the negative instruction and the cross-reference ("do NOT use this when... use get_product instead"). Naming the sibling tool at the boundary is the cheapest disambiguation technique available, because it turns a fuzzy similarity judgment into an explicit rule.

Overlap is the enemy

Selection accuracy degrades fastest when two tools are both plausible for the same request. Every overlapping pair is a coin flip you have inserted into your own system, and no description polish fully removes it.

The structural fixes, in order of preference:

  • Merge. If search_products and lookup_product both take a query string, they are one tool with a well-designed parameter set. Fewer, more capable tools beat many near-duplicates.
  • Redraw the boundary. Make the distinction categorical, not tonal: one tool takes IDs, the other takes free text; one reads, the other writes; one is internal data, the other is web search. A boundary the model can test mechanically ("do I have an ID?") beats one it has to feel out ("is this more of a lookup or a search?").
  • State the boundary in both descriptions. Each side names the other and says which requests belong to it.

A quick audit that catches most problems before shipping: for each of your ten most common user requests, ask whether exactly one tool is plausible. Any request with two answers is a bug in the tool set, not in the model. When wrong selections do slip through to execution, the validation side of the stack catches the damage — that handoff is the subject of retry loops for validation failures.

Flat beats deep: 5-10 tools, not a tree of 40

It is tempting to expose your whole API surface: forty endpoints, forty tools, maybe organized into namespaces. Resist. Every tool definition is tokens in every request, and every additional plausible option dilutes selection accuracy. A flat set of roughly 5 to 10 well-differentiated tools is the sweet spot as of 2026-07, and the trend in provider guidance has been consistently in this direction.

If your domain really has forty operations:

  • Parameterize. manage_calendar(operation: "create" | "update" | "delete" | "list", ...) replaces four tools with one, and the enum is schema-enforced — the same machinery described in json mode vs schema mode guarantees the operation value is one of yours.
  • Route, then narrow. First call: a small forced-choice classification into an area ("orders", "billing", "account"). Second call: only that area's tools in the request. Tool sets are per-request configuration; nothing obliges you to send the full registry every time.
  • Cut. In real logs, a long tail of tools is never called correctly, or never called at all. Removing them improves selection for the tools that matter.

Test selection like the output it is

Tool choice is model output, so evaluate it like any other: a fixture set of 30-50 realistic requests, each labeled with the expected tool (or expected no-tool), run against every prompt or tool-set change. Selection accuracy is one number, it is cheap to compute since you do not need to execute the tools, and it catches regressions that eyeballing never will. When a request is misrouted, the fix is almost always in this article: a name, a boundary sentence, or a merge.

The takeaway

Write tool names as verb-first actions, open every description with the when-to-use criterion, spell out boundaries with negative instructions and sibling references (3-4 sentences for anything complex, per Anthropic's own guidance), eliminate overlap structurally rather than adjectivally, and keep the set flat at 5-10 tools with routing or parameters absorbing the rest. The model can only select between the options as written — as of 2026-07, well-written tool sets are the difference between selection accuracy you can ship and selection accuracy you have to apologize for.