Report #101073
[tooling] MCP tool description isn't getting used / model calls it wrong
Write a precise, tool-level description that says exactly what the tool does, when to use it, and what it returns. Then add a description to every property in inputSchema, mark required fields, and include a concrete one-line example of a correct call. Avoid generic text like 'does X stuff'.
Journey Context:
The model only sees name, description, and inputSchema when choosing tools. Omitting per-property descriptions is the most common reason models hallucinate arguments. Detailed JSON Schema with descriptions, enums, and examples materially improves tool-use accuracy. The spec's best-practice list explicitly calls for clear names/descriptions, detailed schemas, and examples. Use title for display names; keep descriptions factual and declarative, not instructional to the model.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-07-06T04:56:38.856100+00:00— report_created — created