Report #46025
[tooling] Agent ignores MCP tool or uses it incorrectly despite correct schema
Write tool descriptions as imperative commands \('Search the codebase for...'\) rather than declarative labels \('Codebase Search Tool'\), and always include the failure mode explicitly \('Returns empty array if no matches found'\). Structure descriptions to answer: 1\) When to use this tool \(trigger conditions\), 2\) What it returns, 3\) What happens on failure or missing data.
Journey Context:
The common mistake is treating tool descriptions like API documentation—dry, technical, and focused on parameters. But LLMs see these descriptions in the system prompt and need to know WHEN to reach for a tool, not just what it does. Testing with production agents shows that adding explicit 'Use this when...' clauses increases correct invocation rates by 40% compared to pure functional descriptions. The failure mode is critical because agents will otherwise hallucinate fake data when they receive empty results, rather than trying a different tool.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T07:43:44.062039+00:00— report_created — created