What you’ll be able to do
- Know that tool descriptions are the primary selection mechanism, not metadata
- Write descriptions carrying purpose, inputs, examples, edge cases, and boundaries
- Tell description-level misrouting apart from toolkit overload
- Spot system-prompt wording that silently overrides good descriptions
What you need to know
Descriptions are the mechanism, not the documentation
When Claude receives a set of tools, the only thing it has to choose between them is what you wrote: the name, the description, and the input schema. There is no other signal. No usage history, no hidden ranking, no semantic index of what each tool "really" does.
That means a description like "Retrieves patient information" isn't an under-documented tool. It's an under-specified one. The model is being asked to distinguish it from "Retrieves appointment details" using two nearly identical sentences, and it will sometimes get that wrong — not randomly, but predictably, whenever a query touches both concepts.
The five elements of a production-grade description
A description that holds up in production carries five things. Most teams write the first and stop.
- Purpose — what this tool does, stated so it can't be confused with a neighbour
- Expected inputs — accepted identifiers, formats, required vs optional
- Example queries — concrete phrasings it handles, which anchor the model's matching
- Edge cases and limits — what it does not do, and what happens outside normal ranges
- Explicit boundaries — when to use this one instead of the similar tool next to it
Element five is the one that does the heavy lifting and the one most often missing. A boundary statement gives the model a negative instruction it can act on, which is far stronger than hoping two positive descriptions happen not to overlap.
Minimal vs production-grade, side by side
get_appointment: “Looks up scheduled visits by patient MRN or appointment ID (format: APT-NNNNN). Returns date, time, provider, location, and status. Use this for any question about WHEN a visit is, or whether one exists. Do NOT use to verify patient identity — use get_patient for that.”
Read what changed. Each description now names its accepted identifier formats, says what comes back, gives the model a WHO-versus-WHEN distinction it can actually apply, and closes with an explicit redirect to its neighbour.
The misrouting problem — and why three fixes are wrong
This is one of the most reliably tested scenarios on the exam, and it's usually presented with four plausible options. Knowing why the three wrong ones are wrong matters as much as knowing the right one.
- Expand the descriptions — correct. Lowest effort, highest leverage, addresses the actual cause.
- Add few-shot examples — wrong. Spends tokens on every request to paper over descriptions that still don't differentiate. Treating the symptom.
- Build a routing classifier — wrong. Bypasses the model's own language understanding and adds a component you now have to maintain and debug. Over-engineered as a first move.
- Consolidate the two tools into one — wrong as a first step. Legitimate architecture in the long run, but it's a refactor with real cost, and the exam consistently prefers the cheap fix that solves the stated problem.
That preference generalizes well beyond this question. Better descriptions before routing layers. Scoped access before broad access. An existing community MCP server before a custom build. When two options both solve the problem, the exam wants the one with less machinery.
Splitting overly broad tools
A different flavour of the same disease: one tool whose responsibilities are too wide for any description to pin down.
summarize_history: “Produces a concise summary of the patient’s relevant clinical history”
check_contraindication: “Checks whether a proposed medication conflicts with recorded allergies or current prescriptions”
Each result does one narrow job with a defined input and output. “Analyses and returns results” could never have been written clearly, because it wasn’t one job.
Renaming as an interface-level fix
Sometimes the names alone are the collision. analyze_content and analyze_document will confuse the model no matter how carefully you write the bodies. Renaming one to extract_web_results and giving it a web-specific description resolves the overlap without touching a line of implementation — the cheapest fix in the entire category.
System prompt interactions — the subtle one
Here's the failure mode that survives a careful description rewrite. Keyword-sensitive wording in your system prompt can create tool associations that override the descriptions entirely.
If the system prompt says "always verify patient details before proceeding," the model may route anything patient-adjacent to get_patient — including scheduling queries — because that instruction is doing the selecting, not your carefully written boundary statement.
So after you fix descriptions, reread the system prompt for conflicts. The exam tests this, and it's easy to miss because your descriptions genuinely are correct at that point.
Key concept
Tool descriptions are the primary mechanism Claude uses for tool selection. When misrouting comes from weak descriptions, improving them is the first fix — not few-shot examples, not a routing classifier, not consolidation.
Read the condition on that, because both halves get tested. Descriptions are the fix when the agent has a workable number of tools and simply can't tell two apart. They are not the fix when the toolkit itself is the problem — past roughly 4-5 tools per agent, selection degrades on decision complexity alone, and rewriting 22 descriptions leaves that untouched. Diagnose which one you're looking at before reaching for a remedy. Lesson 8.3 covers the overload threshold.
Practice scenario
Work it through, then open this
Over-engineered as a first move. Read the condition: six tools and one confusable pair is a description problem. Rewrite both with purpose, accepted inputs, example queries, and an explicit “do NOT use for X — use Y” boundary, then re-run the same queries. Also reread the system prompt: keyword-sensitive wording there can override even good descriptions.
Build exercise — Fix your own tool misrouting
30 min
-
Pick the two tools in your toolkit with the most similar descriptions.
- Why: This is exactly where misrouting hides, and it’s usually easy to spot once you look.
- You should see: Two descriptions that could plausibly apply to the same incoming query.
-
Run 5 queries that should clearly route to one or the other, and log what actually got called each time.
- Why: Quantify the problem before you fix it — you need a before number to know if the fix worked.
- You should see: At least one misroute out of the five.
-
Rewrite both descriptions with purpose, expected inputs, example queries, and an explicit “do NOT use for X — use Y” boundary. Re-run the same 5 queries.
- Why: This is the lowest-effort, highest-leverage fix — before reaching for a routing classifier or merging the tools.
- You should see: All 5 queries routing correctly on the second pass.
Exam traps
Choosing few-shot examples to fix description-level misrouting
They add token cost on every call without making the two tools distinguishable. The model is confused because the descriptions do not differentiate — fix the descriptions.
Reaching for a routing classifier as the first step
Over-engineered as an opening move. It bypasses the language understanding you are already paying for and adds infrastructure to maintain.
Consolidating two similar tools immediately
A valid long-term architecture, but it is a refactor. The exam favours the low-effort, high-leverage fix first.
Rewriting descriptions but never rereading the system prompt
Keyword-sensitive instructions there can silently override even excellent descriptions, creating tool associations you did not intend.
Rewriting descriptions when the real problem is tool count
Past roughly 4-5 tools, selection degrades on decision complexity. No amount of description polish fixes that — split across subagents or narrow the toolkit.