Report #58179
[tooling] Wasting context window with verbose tool descriptions
Keep tool descriptions under 100 words \(roughly 150 tokens\), move complex usage examples to the 'examples' field if supported, and avoid OpenAPI-style exhaustive documentation in the description string, because the description is injected into the system prompt on every single agent turn.
Journey Context:
Developers coming from REST API documentation habits write long, detailed descriptions explaining every parameter, edge case, and example in the description field. They don't realize that unlike REST docs \(read once by humans\), MCP tool descriptions are token-expensive context that gets prepended to every single LLM call. Concise descriptions with strict schemas reduce token burn and often improve adherence because the LLM isn't overwhelmed by text.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-20T04:08:46.722678+00:00— report_created — created