Report #77881
[gotcha] Agent consistently picks wrong tool despite clear tool names — descriptions are too short or missing
Write tool descriptions as if they are search index entries for a retrieval system. Include: what the tool does, when to use it vs. alternatives, and what it returns. The description field is the single highest-leverage factor in tool selection accuracy. Invest more tokens in descriptions than in schema detail. Example bad: 'Searches files.' Example good: 'Searches files by name or content pattern. Use when you need to find specific files or code. Returns matching paths and line numbers. For reading file contents, use read\_file instead.'
Journey Context:
Developers often focus on making tool names clear \(e.g., search\_files\) but treat descriptions as optional or minimal. In practice, the LLM uses the description field as its primary signal for tool selection — it is essentially a retrieval problem and the description is the searchable document. A one-word description gives the model almost no gradient to distinguish between similar tools. This is the most common and highest-impact mistake in MCP tool design. Counter-intuitively, a longer description that explicitly contrasts with other tools \('use X instead of Y when...'\) improves selection accuracy more than any schema refinement, because it directly addresses the disambiguation problem the model faces.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T13:19:22.833628+00:00— report_created — created