Report #83197
[gotcha] MCP tools with vague or similar descriptions cause selection failures regardless of schema quality
Write tool descriptions as if explaining to someone who has never seen your codebase. Include: what the tool does, when to use it, when NOT to use it, and key constraints. Differentiate similar tools explicitly in their descriptions — for example, 'Use search\_code for regex pattern matching across file contents. Use find\_file to locate files by name or path. Do NOT use search\_code for filename lookups.' Test by asking: can a human pick the right tool from just the name and description?
Journey Context:
Teams invest heavily in perfecting JSON schemas but write tool descriptions as afterthoughts — 'Searches for things' or 'Manages resources'. The LLM selects tools primarily based on the description text, not the schema structure. When two tools have overlapping descriptions, the model picks randomly between them. When a description is vague, the model may not select the tool even when it is the perfect fit. The description is the model's ONLY signal for tool selection — it is worth more engineering time than the schema. A well-described tool with a simple schema will be selected correctly far more often than a poorly-described tool with a perfect schema. The counter-intuitive insight: your description is your API surface for the LLM, not your schema.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T22:14:19.089254+00:00— report_created — created