Diagnose wrong-tool-pick to description
What you'll learn
If the model keeps picking the wrong tool, fix the descriptions before anything else. Say what each tool does, what it operates on, when to use it, and what it doesn't handle.
- Wrong-tool-pick → check the description first.
- Good description = operation + operand + when-to-use + when-NOT-to-use.
- Differentiation between neighbouring tools is the most-missed component.
When the model calls the wrong tool, the *first* fix to consider is the tool description, not the tool list, the model, or the system prompt. The model picks tools by reading their schemas and descriptions; vague or overlapping descriptions are the most common cause of wrong-tool-pick. This is consistent enough that 'model picks wrong tool' should map mentally to 'check the descriptions' as the default first hypothesis.
A good tool description names four things: (1) what the tool *does* (the operation), (2) what it *operates on* (the input/data class), (3) what scenario it's the right pick for ('use this when…'), and (4) what it does *not* handle (the boundary that distinguishes it from neighbouring tools). Most bad descriptions miss (3) and (4); the model has to infer the differentiation, which it does by guessing.
Concrete example: two tools, `search_documents` and `find_files`. With descriptions 'Search the system for documents' and 'Find files,' they read like synonyms — the model picks based on noise. Rewriting to 'search_documents: search indexed PDFs and Word docs by content' and 'find_files: list filenames in the working directory by glob pattern' makes the choice mechanical for the model.
The diagnostic order: (1) check tool descriptions for clarity and differentiation; (2) check schema parameters for ambiguity; (3) only after both are clean, consider whether the *set* of tools is wrong (too many overlapping, too few covering distinct use cases). Renaming tools, adding system-prompt nudges ('prefer X when…'), or merging tools are all weaker fixes that paper over a description-quality problem.
Key points
- Wrong-tool-pick → check the description first.
- Good description = operation + operand + when-to-use + when-NOT-to-use.
- Differentiation between neighbouring tools is the most-missed component.
- Rename / system-prompt nudges / tool merges are second-order fixes.
Examples
search_documents: 'Search the system for documents.' find_files: 'Find files.' Reads as synonyms; model picks based on noise.
search_documents: 'Search indexed PDFs and Word docs by *content* (full-text search). Use when the user asks about what's *in* a document. Does not list filenames or directory contents.' find_files: 'List filenames in the working directory by glob pattern. Use when the user asks where a file *is*. Does not search inside files.' Differentiation is explicit; selection becomes mechanical.
Pitfalls
- Renaming tools as the fix. The model reads descriptions, not names.
- Adding 'prefer search_documents when in doubt' to the system prompt. Bias without information; doesn't fix the structural ambiguity.
- Merging two ambiguous tools into one with a `mode` param. Pushes the disambiguation onto a parameter; the description-quality problem just moves.
- Skipping the 'does NOT handle' clause. The boundary is what differentiates.
Source notes: 00-academy-basics/notes/05-mcp-intro.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.