Agent keeps picking the wrong tool for the job? How to diagnose wrong tool selection

The agent has the right tool available. It just doesn't use it. It reaches for web_search when it should have called calculator, or picks a generic tool over the specific one that would have nailed the task. Nothing errors — the run completes, the answer's just wrong, and you're left wondering why it ignored the obvious tool.

Why models mis-select tools

Tool selection is a matching problem: the model reads the task and the tool descriptions and picks what fits. It goes wrong when the descriptions don't give it enough to discriminate:

• Overlapping descriptions. Two tools sound like they do the same thing, so the model picks the first plausible one — often the wrong one.
• Vague descriptions. A tool described as "gets data" could match almost anything; the model has nothing to rule it out.
• Too many tools. A large tool set dilutes the signal — the right tool is in there, but so are ten near-misses.
• No negative guidance. The description says what the tool does but never when not to use it.

The fix is in the tool descriptions

1. Make descriptions sharp and non-overlapping. Each should say what the tool is for AND when to use it over the alternatives.
2. Add negative guidance. "Use this for X; do NOT use it for Y (use Z instead)." Discrimination beats description.
3. Trim the tool set. Expose only the tools the task needs. Fewer, clearer options mean fewer wrong turns.
4. Give examples. A couple of "this task → this tool" examples anchor the matching.

Diagnose it

Send the trace and Snapback returns failure_class: "wrong_tool_selection" with the root cause and which tool should have been used — so you know whether to sharpen a description, trim the set, or add negative guidance:

diagnose_trace({trace: { final_status: "failed", steps: [
  {index:1, action:"web_search", inputs:{query:"12.5% of 840"}, status:"success"},
  {index:2, action:"final_answer", outputs:{answer:"about 100"}, status:"success"} ]}})

// → { failure_class: "wrong_tool_selection",
//      root_cause: "used web_search for a calculation; calculator was available", fix_suggestion }