Why Does Claude Pick the Wrong Tool? Fixing Tool Selection

July 24, 2026 · Claude Certified Architect (CCA) Prep (part 14)

▶ Watch on YouTube & subscribe to The Stack Underflow

Two tools, one job — that’s the setup that breaks agents in production more often than any missing schema field ever does. You register search_web and search_docs, both correctly typed, both returning clean JSON, and Claude still reaches for the wrong one half the time. The instinct is to blame the model. The actual bug is almost always sitting in plain text, three lines up from the schema, in a field most people write last and think about least.

The one-sentence version: Claude selects a tool by reading its description at call time — the description is the API the model sees, and vague or overlapping descriptions are indistinguishable to a model choosing between them.

This is practice question 1 of 10 in the Domain 2 set — Tool Design & MCP Integration, roughly 18% of the Claude Certified Architect exam. Pause, pick an answer, then read on for the mechanism.

The question

Your agent keeps choosing search_web when it should use search_docs (and vice-versa). The schemas are fine. Most likely root cause?

• A) Model too small
• B) Vague, overlapping tool DESCRIPTIONS
• C) Temperature too low
• D) Missing API keys

Pause the video (or this page) and pick your answer before you keep scrolling.

The answer

B — vague, overlapping tool descriptions. The schemas were never the problem. The model is not confused about how to call either tool — it’s confused about which one applies, and the only place that decision gets made is the description text attached to each tool definition.

Here’s the mechanism. When Claude decides whether to call a tool, and if so which one, it is not inspecting your backend code, your database, or your MCP server’s internals. It sees a list of tool names, each with a natural-language description and a JSON schema for arguments. That list is the entire universe of information it has for making the selection. If two descriptions both read something like “gets data” or “gets data from source,” they are, from the model’s perspective, functionally identical — there is nothing in the text to differentiate when one applies over the other.

BEFORE — two tools, indistinguishable descriptions

  ┌─────────────────────┐        ┌─────────────────────┐
  │ search_web           │        │ search_docs           │
  │ "Gets data."          │        │ "Gets data from       │
  │                        │        │  source."              │
  └─────────────────────┘        └─────────────────────┘
              ▲                              ▲
              └───────────── ? ──────────────┘
                    selector arrow wavers
                 (both descriptions look the same)

AFTER — descriptions written for the model, not the teammate

  ┌────────────────────────────────────┐   ┌────────────────────────────────────┐
  │ search_web                          │   │ search_docs                          │
  │ "Search the PUBLIC web. Use for     │   │ "Search INTERNAL documentation.      │
  │  current events, news, or anything  │   │  Use when the question is about      │
  │  outside internal docs."            │   │  this product, its APIs, or          │
  │                                      │   │  internal policy — not the web."     │
  └────────────────────────────────────┘   └────────────────────────────────────┘
              ▲                                          ▲
              └──────────── selector snaps ──────────────┘
                  correctly, every time — the boundary
                  between "when to use" is now explicit

The fix is not a bigger model, a different sampling temperature, or a config check for missing keys — it’s rewriting both descriptions so each states what it does and, critically, when to use it versus the alternative. Once search_web’s description explicitly excludes internal docs and search_docs’s description explicitly excludes the public web, the selection boundary that was fuzzy becomes a clean line. Nothing about the schema, the arguments, or the underlying implementation needs to change at all.

Why the other options fail

• A) Model too small — tool selection based on textual description matching is not primarily a raw-capability problem. Even frontier models will pick the wrong tool if two descriptions are semantically identical; swapping to a larger model masks the symptom occasionally (more world knowledge might let it guess right more often) without fixing the actual cause, and the failure returns as soon as the question gets slightly ambiguous again.
• C) Temperature too low — temperature controls how much randomness is injected into token sampling for generated text. Lower temperature makes output more deterministic, not less accurate at tool selection. If anything, a low temperature with a bad description means Claude will confidently and consistently pick the same wrong tool every time — deterministic, but deterministically wrong.
• D) Missing API keys — this would produce a runtime failure when the tool is invoked — an auth error, a 401, a connection failure — not a selection error where the model reaches for the wrong tool name in the first place. Missing credentials are an execution-time problem; picking the wrong tool is a decision-time problem, and those two failures show up at completely different points in the trace.

The concept behind it

Generalize this past search_web versus search_docs: the tool description is the entire interface contract the model operates against. You did not write it for a code reviewer, a teammate skimming a pull request, or future-you six months from now — you wrote it, whether you meant to or not, for an LLM deciding in real time whether this specific tool is the right response to this specific user request. Treat it with the same rigor you’d give a public API’s documentation, because functionally, that’s exactly what it is.

A description that reliably drives correct selection covers four things:

The “when to use it” line is the one people skip most often, and it’s the one that fixes exactly this failure mode. Two tools can both have perfectly accurate “what it does” text and still collide, because “what it does” doesn’t tell the model anything about the other tool it’s being asked to choose between. Explicit exclusion language — “use for X, not Y” — is doing real selection work, not just padding.

This also scales past two tools. As tool counts grow, overlapping or vague descriptions compound: with 5 tools, one ambiguous pair is a minor annoyance; with 40 tools loaded into the same context, several ambiguous clusters stack up and both selection accuracy and latency degrade together — a related but distinct D2 failure mode covered in the tools-per-agent scoping question. The description problem and the tool-count problem are different root causes that produce a similar symptom (wrong tool picked), which is exactly why this question isolates the description as the variable held constant against “schemas are fine.”

One more generalization worth internalizing: this is a case where the fix costs nothing structurally. No schema migration, no new endpoint, no infrastructure change — just better prose in a field you already control. That asymmetry (cheap fix, expensive-looking symptom) is a strong signal, on the actual exam and in real debugging, that the answer lives in the description before you reach for anything heavier.

FAQ

Does the order of tools in the request matter as much as the description text? Order can have minor effects on some models in some configurations, but it is not the mechanism being tested here and it is not a reliable lever to pull. If your two tools are already well-differentiated by description, reordering them will not meaningfully change selection accuracy. Fix the description first; only chase ordering effects after that.

If I rewrite the descriptions and selection is still wrong, what’s next? Check whether the tools are genuinely overlapping in capability rather than just poorly described — if search_web and search_docs can both legitimately answer the same query some of the time, no amount of description tuning eliminates ambiguity that’s real, not textual. At that point the fix is a design change (merge them, or add a router step) rather than another wording pass.

Is this the same issue as a tool having too many parameters? No — parameter count and typing affect whether Claude calls a tool correctly once it has already been selected. This question is about which tool gets picked in the first place. Both matter, but they’re different failure points in the same pipeline, covered separately in this series.

Do longer descriptions always perform better? No. A long description padded with irrelevant detail dilutes the signal the model needs (what/when/args/example) just as much as one that’s too short. The goal is precision and clear boundaries, not word count.

Not affiliated with, authorized, or endorsed by Anthropic. “Claude” and “Claude Certified Architect” are trademarks of Anthropic. These are original practice questions for study, not real exam content — verify current exam details on Anthropic’s official pages.

Where this fits in the CCA series

This is Q1 of the Domain 2 practice set — start with the Claude Certified Architect (CCA) Exam Guide for all five domains on one diagram, and if you haven’t seen the mechanism itself yet, MCP Explained on One Diagram covers what a tool actually is before you worry about how to describe it well.

The rest of Domain 2 builds directly on this idea. Once the description is right, the next failure point is the schema itself — see The Model Sends ‘Next Tuesday,’ Not a Date for constraining inputs, and The Param the Model Keeps Skipping for when “optional” quietly means “ignored.” If your tool count is climbing past a handful and selection is degrading again even with good descriptions, that’s a different root cause — see 40 Tools, Wrong Picks, High Latency. And for the deeper version of “how do I write one of these well,” go straight to ‘Gets Data’ Is Too Vague: How to Write Tool Descriptions That Work.

Browse all tutorials for the full series.