The Model Called the Wrong Tool: Why It Happens and How to Fix It

Figures on this page were verified 18 October 2026 against the providers' own documentation. Pricing, context windows and rate limits change without notice, so confirm any number against the provider before you rely on it. Tell us if something here is out of date.

When the model picks the wrong tool, the cause is almost always that your tools look alike to it, not that it misunderstood the user. Models select tools by matching the request against each tool’s name and description at generation time, with no visibility into your implementation. If two tools could plausibly answer the same question, the model is guessing between them exactly as a developer reading only your docstrings would.

Why this is a schema problem, not a model problem

Both providers build tool selection from the same inputs: the tool name, its description, and the shape of input_schema or parameters. Nothing about your tool’s actual behaviour reaches the model unless it is written down. search_orders and get_order_status look interchangeable to a model deciding between them in a single forward pass, even if their implementations are nothing alike.

Anthropic’s own guidance is blunt about this: aim for at least three to four sentences per tool description, covering what it does, when to use it, when not to, and what each parameter means. A one-line description is the single most common cause of wrong-tool selection, and it is also the easiest to fix without touching any code.

The three patterns that cause misselection

1. Overlapping descriptions. Two tools both say some variant of “get information about an order.” The model has no signal to prefer one.
2. A vague tool buried among specific ones. A catch-all run_query tool will absorb requests that belong to narrower tools, because its description technically covers everything.
3. Too many tools in one call. Selection gets harder as the tool count grows, because the model has to discriminate between more near-duplicates at once. We have not measured a specific threshold, so treat any round number you read elsewhere as a rule of thumb.

Fix 1: write descriptions that rule things out, not just in

A good description states what the tool does and what it explicitly does not do. That negative space is what separates two similar tools.

{
  "name": "get_order_status",
  "description": "Returns the current shipping status and estimated delivery date for a single existing order, given its order ID. Use this when the user asks where an order is or when it will arrive. Does NOT create, cancel, or modify orders, and does not return pricing or product details -- use search_orders for that."
}

Writing “does NOT” is not defensive filler. It is the single sentence that stops the model reaching for this tool when search_orders was the right call.

Fix 2: consolidate near-duplicate tools

If two tools are rarely both correct for the same request, that is a sign they should be one tool with a parameter, not two tools competing for selection. Anthropic’s own tool-design guidance recommends consolidating related operations into fewer, more capable tools rather than one tool per action.

// Instead of three competing tools:
//   create_pr, review_pr, merge_pr
// one tool with an explicit action parameter:
{
  "name": "github_pull_request",
  "description": "Create, review, or merge a GitHub pull request. Set 'action' to the operation you need.",
  "input_schema": {
    "type": "object",
    "properties": {
      "action": {"type": "string", "enum": ["create", "review", "merge"]},
      "repo": {"type": "string"},
      "pr_number": {"type": "integer", "description": "Required for review and merge, omit for create."}
    },
    "required": ["action", "repo"]
  }
}

This removes the selection problem entirely. There is one tool to pick, and the model only has to get the action parameter right, which is a far easier decision than discriminating between three similarly-described tools.

Fix 3: namespace tools from different services

Once a tool library spans multiple services, bare verbs collide. list_prs could belong to GitHub, GitLab, or an internal tracker. Prefix every tool name with its service, which makes selection unambiguous as the library grows, and Anthropic notes it matters most when you use a tool search tool to manage a large catalogue.

Verify it, do not guess

Tool-selection regressions are invisible until you log which tool fired for which request. Capture name from every tool_use or function_call block against the user’s original message, and keep a small evaluation set of prompts where you know the correct tool. A two-line description change can flip selection on prompts you never tested by hand, so re-run the set after any description edit rather than trusting the one example that prompted the change.

Related errors

If the right tool was chosen but the arguments were wrong or unparseable, see tool call arguments that will not parse. If no tool was called at all when one should have been, see the model ignored the tool and answered in prose. The full map is in the LLM API error reference.

Frequently asked questions

Why does the model pick the wrong tool?

It chooses by matching the request against each tool name and description, with no view of your implementation. When two descriptions overlap it is guessing between them, and a one-line description is the most common cause.

How should I describe two similar tools?

State what each tool does and what it does not do. A sentence such as "Does NOT cancel or modify orders, use search_orders for that" is what separates two similar tools.

Does adding more tools make selection worse?

Selection gets harder as the tool count grows, because the model has more near-duplicates to discriminate between. Consolidate related operations into one tool with an action parameter, and prefix names with the service when tools span several.