The tool picker
Claude keeps calling the wrong tool. The tempting answers build something: a routing layer that reads the message first, one merged tool, or a brand-new tool. The exam's answer is usually smaller. Claude chooses a tool by reading its description, so fix the descriptions first.
D2 Tool Design & MCPExam guide 2.1 and 2.3About 15 minutes
Start here: the labelled drawers
A new helper starts in a busy kitchen. You ask for the big whisk. There are three drawers, labelled “Utensils”, “Tools” and “Kitchen things”.
You could hire someone to stand by the drawers and hand things out (a routing layer). You could tip everything into one big drawer (a merged tool). Or you could add a fourth drawer (a new tool). All of them cost more, and none of them fixes the labels. Claude picks tools the same way the helper picks drawers: from the description of each tool.
- No (one-line or overlapping descriptions): rewrite the descriptions with input formats, example queries, edge cases and boundaries (“not for X: use Y”). This is the first step.
- No, and a prompt line ties a word to a tool (“when they mention stopping, use pause”): remove that line, then fix the descriptions.
- Yes, and picks are still inconsistent: add a few targeted examples to the prompt. A later step, not the first.
- Yes, but the agent holds many tools (18 when its job needs 4 or 5): give it only the tools its role needs.
- The problem isn't which tool: Claude answers in text when a call is required →
tool_choice: "any"; one tool must run first → forced{"type": "tool", "name": …}.
Words in the question that tell you which side you're on
Fix the descriptions
- “minimal”, “one line”, “both read …”
- similar tools, similar ID formats
- “first step”, “most effective”, “low effort”
- picks the wrong one of two or three tools
Something else is the cause
- “descriptions are already detailed”
- many tools (18) for one job → scope the tool set
- “replies in text instead” →
tool_choice - “must run first” → forced tool
Try it: replay a request 100 times
Pick a customer request, then pick how you'd help Claude choose. The simulator replays the request 100 times and shows which tool Claude calls first. The diagram above shows where your fix acts.
What Claude sees
The same fix on all four requests
The rates are illustrative, chosen to show the shape. They are not measurements. The exam guide's point is that descriptions are the primary way Claude selects tools, and minimal descriptions make selection among similar tools unreliable.
Things to try: “Is box 20931 arriving today?” + one-liners, then + edge cases and boundaries. Then “I'm customer 48213, change my address” + keyword routing to see a router hide the right tool. Last, “Last Tuesday's box” + tool_choice “any”: the right lever for a different problem.
The three traps
| Trap | What the wrong option looks like | Why it loses |
|---|---|---|
| Build instead of describe | A routing layer that parses keywords, a classifier that picks a tool subset, merging tools into one lookup_entity, or adding a new tool | Bigger to build and maintain, and none of them fixes the vague descriptions. A router can even hide the right tool. |
| Examples before descriptions | “Add 5–8 few-shot examples showing which tool to call” | Helps on cases like the examples, adds tokens to every call, and leaves the cause in place. Few-shot is a later step. |
| Right lever, wrong problem | tool_choice: "any" or a forced tool to fix a wrong pick; rewriting descriptions when the agent simply has too many tools | tool_choice controls whether (and which, if forced) a tool is called, not how Claude chooses. Too many tools is fixed by scoping the tool set. |
Practice: three exam-style questions
Answer first, then open “Think it through”.
Rule to remember
tool_choice only for whether a tool is called.
Exam guide 2.1: “Tool descriptions are the primary mechanism LLMs use for selection; minimal descriptions → unreliable selection among similar tools.” “Include input formats, example queries, edge cases, boundaries.” “Ambiguous/overlapping descriptions cause misrouting; keyword-sensitive system-prompt wording creates unintended tool associations.” Exam guide 2.3: “Too many tools (18 vs 4-5) degrades selection reliability.”