CCA-F start here · Trap gym · The tool picker

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

At a glance: If Claude picks the wrong tool, first improve the tool descriptions (what each does, its inputs, its edge cases, when not to use it) before adding routers or new tools.

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”.

Vague labels. The helper opens a drawer more or less at random. Sometimes they guess right. Whatever you do next, the problem is the labels.
Good labels. “Whisks and spoons: for mixing. Knives are in the next drawer.” The helper gets it right first time, every day, and you only wrote three labels.

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.

What Claude reads when it picks a tool System prompt instructions + examples Tool descriptions the main signal tool_choice auto, any or forced Customer request “Is box 20931 arriving?” Routing layer (optional) Claude picks one tool calls get_customer the account lookup_order one box's contents track_delivery a box on its way
The one question to ask: does Claude have what it needs, in the descriptions, to tell these tools apart?

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.

1. The customer request
2. Your fix

What Claude sees


    

right toolwrong toolno tool call

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

TrapWhat the wrong option looks likeWhy it loses
Build instead of describeA routing layer that parses keywords, a classifier that picks a tool subset, merging tools into one lookup_entity, or adding a new toolBigger 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 problemtool_choice: "any" or a forced tool to fix a wrong pick; rewriting descriptions when the agent simply has too many toolstool_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

Wrong tool picked? Fix the descriptions first. Build nothing until they're clear. Then examples if picks are still inconsistent; scope the tool set if there are too many; 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.”

← All traps