What you will be able to do
- Diagnose misrouting between tools with similar descriptions and fix it by stating when to use each one
- Rename and namespace tools so no two of them appear to do the same job
- Judge when to merge related operations into one tool and when to split a catch-all tool into purpose-specific tools
- Check a system prompt for wording that pulls Claude toward the wrong tool
1.How overlapping descriptions send calls to the wrong tool
Imagine an agent with two tools, analyze_content and analyze_document, both described roughly as 'analyzes the provided content and returns insights.' Each description might pass review on its own. Side by side, they give Claude nothing to choose between, so calls go to whichever tool happens to look closer. (This pair is the exam guide's example; Anthropic's docs describe the same failure in general terms.) Anthropic's agent guidance flags exactly this: making tools obvious 'is especially important when using many similar tools.'
The troubleshooting guide treats misrouting as a known symptom with a known cause:
| Symptom | Likely cause | Fix |
|---|---|---|
| Claude calls tool A when you wanted tool B | Description ambiguity | Sharpen descriptions; differentiate by WHEN to use each tool, not only WHAT it does |
| Claude never calls your tool | Tool name collision or overly-generic schema | Check for duplicate names; add input_examples to make the intended use concrete |
The key point in that first row is 'not only WHAT'. Two analysis tools can honestly both say 'analyzes content'. What tells them apart is the situation each one is for: which input it expects, what it returns, and which other tool to use instead. If every description answers 'use me when…, use the other tool when…', two tools can no longer look interchangeable.
Checkpoint 1 of 5· Match them up
Match each symptom to the likely cause given in the troubleshooting guide
Tap a term, then the definition that fits it.
Misrouting comes from ambiguous descriptions. A tool that is never called usually has a colliding name or a schema too generic to match anything. Wrong parameter types mean Claude is guessing at an ambiguous schema.
“Differentiate tools by WHEN to use them, not only WHAT they do.”Source: platform.claude.com
2.Renaming tools so their names don't overlap
Better descriptions are one fix. Sometimes the name itself is the problem. Anthropic's guidance asks directly how you can change parameter names or descriptions to make things more obvious. A name like analyze_content fits almost any input, so it pulls in requests meant for other tools. Renaming it to extract_web_results and rewriting its description to cover only web search results (the exam guide's fix) narrows the tool to one job. The reader, and Claude, can see from the name alone that a PDF does not belong there.
When tools span several services, the Define tools guide recommends meaningful namespacing: prefix each name with its service, for example github_list_prs or slack_send_message. This keeps selection unambiguous as the tool library grows, and the guide says it matters most when using tool search. A name match tells Claude which family a tool belongs to. The description still has to say when to use it.
Checkpoint 2 of 5· Check yourself
An agent has both analyze_content (meant for web search results) and analyze_document (meant for uploaded files). Calls keep landing on the wrong one. Which change most directly removes the overlap?
A specific name and a description scoped to one input type remove the overlap where it starts. A blanket preference in the system prompt only moves the misrouting the other way.
“How can you change parameter names or descriptions to make things more obvious?”Source: www.anthropic.com
3.When to merge tools and when to split them
The Define tools guide recommends consolidating related operations. Rather than separate create_pr, review_pr and merge_pr tools, it suggests one tool with an action parameter. Anthropic's tool-writing post adds that more tools don't always lead to better outcomes, and warns against tools that merely wrap existing software functionality or API endpoints.
The same goal can point the other way. A generic analyze_document that can extract figures, write summaries or fact-check a claim has one vague description covering three different jobs, each with its own input and output. The exam guide's fix is to split it into extract_data_points, summarize_content and verify_claim_against_source. This specific split comes from the exam guide; the sources don't discuss it. The sources do supply the test to apply. Tool use is a contract in which you set what shape the inputs and outputs take, and a good definition has clear boundaries from other tools. A PR tool's actions all act on one resource, so one description can cover them. The three analysis jobs need different inputs (a claim plus a source, for example) and return different things, so no single description can state one clear 'when to use me'.
Checkpoint 3 of 5· Check yourself
Which design best follows the guidance on merging versus splitting tools?
Related operations on one resource belong together behind an action parameter. Jobs with different input and output contracts need separate tools whose boundaries can be described clearly. Wrapping every endpoint is the anti-pattern the post warns about.
“Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.”Source: platform.claude.com
4.When the system prompt overrides good descriptions
Even well-written descriptions are only part of what Claude reads. The API builds one system prompt from your tool definitions, your tool configuration and your own system prompt. Your instructions and your tool descriptions therefore sit in the same context. The overview docs say the boundary between calling a tool and answering directly 'is steerable through your system prompt'. A light instruction such as 'Use the tools to investigate before responding.' increases tool use, and a stronger one pushes it further. The tool-choice cookbook adds that Claude can be over-eager to call tools, and that a detailed prompt helps it decide when to call one and when not to.
This steering is not limited to the call-or-answer decision. Suppose the system prompt says 'If in doubt, use the search tool.' Claude may now link the word 'search' with search_web and pick it over lookup_internal_docs, even though the descriptions place internal questions with lookup_internal_docs. The sources don't analyse this keyword effect directly. It follows from the prompt and the descriptions sharing one context, with the prompt steering tool use.
In practice: when a tool is misrouted, review the system prompt as well as the descriptions. Look for instructions that name a tool or a trigger word ('search', 'analyze', 'look up') and ask whether that word also fits a neighbouring tool. Rewrite such instructions in terms of situations rather than keywords, and leave the 'when to use' detail to the descriptions.
Checkpoint 4 of 5· Check yourself
After "Always analyze the document first" is added to a system prompt, Claude starts calling analyze_document for web results that extract_web_results is clearly described as handling. What is the best first fix?
The system prompt sits in the same context as the descriptions and steers tool use, so a keyword instruction can outweigh a well-scoped description. Fix the instruction itself. Forcing one tool would break every request that genuinely involves a document.
“This boundary is steerable through your system prompt.”Source: platform.claude.com
Checkpoint 5 of 5· Exam question
A single tool, `analyze_document`, extracts data points, produces summaries, and verifies claims against a source. Users report it inconsistently performs only one of these behaviors for ambiguous requests. Which redesign best addresses this?
Correct answer: C — Split the tool into `extract_data_points`, `summarize_content`, and `verify_claim_against_source`, each with a narrow contract.
- A. Incorrect. Forcing three calls per request wastes invocations on tasks that need only one behavior and does not resolve the ambiguity about which behavior was intended.
- B. Incorrect. Merging with unrelated tools increases the surface area of a single tool's responsibilities, worsening overlapping-purpose confusion rather than resolving it.
- C. Correct. Splitting a generic multi-purpose tool into purpose-specific tools with defined input/output contracts removes the ambiguity about which behavior a call should trigger.
- D. Incorrect. Adding a mode parameter without updating the description still leaves the model guessing at the tool's overall purpose and when each mode applies.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.To stop misrouting, make each description explain more precisely what its tool does.Why is that wrong?
Similar tools can honestly describe similar actions. The prescribed fix for calls going to the wrong tool is to differentiate them by when each should be used.
Covered in How overlapping descriptions send calls to the wrong tool
2.Exposing one tool per API endpoint gives the agent the best coverage.Why is that wrong?
Anthropic warns that more tools don't always help, and that tools which simply wrap existing endpoints are a common mistake. Group related operations and give separate jobs clear boundaries.
Covered in When to merge tools and when to split them
3.Once the tool descriptions are well written, the system prompt can't cause misrouting.Why is that wrong?
The API puts tool definitions and your system prompt into one constructed prompt, and the system prompt steers tool use. A keyword-heavy instruction can therefore outweigh a good description.
Covered in When the system prompt overrides good descriptions
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Differentiate tools by WHEN to use them, not only WHAT they do.”
↩︎ How overlapping descriptions send calls to the wrong tool“Differentiate tools by WHEN to use them, not only WHAT they do.”
↩︎ Exam trap 1 - 2.https://www.anthropic.com/engineering/building-effective-agentsSecondary source
“This is especially important when using many similar tools.”
↩︎ How overlapping descriptions send calls to the wrong tool“How can you change parameter names or descriptions to make things more obvious?”
↩︎ Renaming tools so their names don't overlap - 3.
“This makes tool selection unambiguous as your library grows, and is especially important when using tool search.”
↩︎ Renaming tools so their names don't overlap“prefix names with the service (for example, github_list_prs, slack_send_message)”
↩︎ Renaming tools so their names don't overlap“Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.”
↩︎ When to merge tools and when to split them“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”
↩︎ When the system prompt overrides good descriptions“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”
↩︎ Exam trap 3“Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.”
↩︎ Checkpoint - 4.https://www.anthropic.com/engineering/writing-tools-for-agentsSecondary source
“tools that merely wrap existing software functionality or API endpoints”
↩︎ When to merge tools and when to split them“More tools don’t always lead to better outcomes.”
↩︎ Exam trap 2 - 5.
“You specify what operations are available and what shape their inputs and outputs take; Claude determines when and how to call them.”
↩︎ When to merge tools and when to split them - 6.
“This boundary is steerable through your system prompt.”
↩︎ When the system prompt overrides good descriptions - 7.https://platform.claude.com/cookbook/tool-use-tool-choiceSecondary source
“Writing a detailed prompt helps Claude determine when to call a tool and when not to.”
↩︎ When the system prompt overrides good descriptions