Report #98760
[tooling] My MCP tool is discovered but the agent calls it wrong or ignores it
Write the tool description as an imperative prompt that tells the model exactly when to call the tool, what it returns, and what trigger condition to look for. Include a concrete usage example and mention the failure mode it handles. Avoid one-line summaries like 'Search the codebase'.
Journey Context:
In MCP, the model selects tools using only the tool name, description, and input schema. The description is effectively a prompt, yet most developers write vague marketing copy. The spec's best practices explicitly call for clear, descriptive names and descriptions with examples. A good description answers: \(1\) under what situation should the model prefer this tool, \(2\) what exact argument values are valid, \(3\) what the returned data looks like, and \(4\) common mistakes to avoid. For example, instead of 'code search,' use 'Call this when you need to find where a symbol is defined or used in the repository. Returns file paths and line numbers. Prefer this over guessing from filenames.' This single change usually fixes more tool-use issues than schema tuning.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-28T04:44:03.004171+00:00— report_created — created