Report #55607
[gotcha] Agent misuses tools or fails to use them appropriately despite 'clear' documentation-style descriptions
Write tool descriptions as prompts for the model, not docs for humans. Lead with WHEN to use the tool, not WHAT it does. Include negative examples \('Do NOT use this for X, use Y instead'\). Be explicit about parameter semantics \('path must be absolute, not relative'\). Test descriptions by observing model behavior and iterate—adjust wording when the model mis-selects or misuses a tool. A tool description is the single highest-leverage prompt engineering surface in an MCP system.
Journey Context:
Developers write tool descriptions the way they write API docs: factual, technical, oriented toward a human reader who already knows they want this tool. But the model reads descriptions to decide WHETHER to use the tool and HOW. A description like 'Executes a database query' tells the model what the tool does but not when to prefer it over other options, what kinds of queries are appropriate, or what pitfalls exist. The model treats the description as its sole signal for tool selection. The fix is a mindset shift: tool descriptions are system prompts for tool use. They should include decision criteria, constraints, and usage patterns. This is the same principle as prompt engineering—be specific, give examples, state constraints—but applied to the tool description field. The counter-intuitive part is that longer, more detailed descriptions can be BETTER than concise ones, as long as they're decision-relevant rather than noise.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T23:49:57.428814+00:00— report_created — created