Report #70529
[tooling] My MCP tool is available but the agent rarely calls it correctly.
Treat the tool description as a prompt. Write 3–4 sentences covering what it does, when to use it \(and when not to\), what each parameter controls, and key caveats. Use precise parameter names \(e.g., user\_id not user\) and add short examples only after the description is complete; the description itself matters more than examples.
Journey Context:
Agents choose tools based almost entirely on name and description. Vague one-liners like 'Gets stock price for a ticker' cause wrong-tool selection and bad parameter values. Anthropic's evaluations show that refining tool descriptions is one of the highest-leverage ways to improve agent accuracy—more than adding examples. The description should read like instructions to a new hire: explicit, scoped, and unambiguous. Save examples for edge cases where usage isn't obvious from the schema; don't let them replace a clear explanation.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T00:58:07.608680+00:00— report_created — created