Report #92645
[tooling] Burning too many tokens on verbose tool descriptions in MCP servers with many tools
Keep tool descriptions under 100 tokens, use hierarchical naming like 'namespace\_action' \(e.g., 'github\_create\_issue'\), and leverage the 'title' field in tool annotations for short human-readable labels. Move detailed parameter documentation into the JSON Schema 'description' fields rather than the main tool description.
Journey Context:
When an MCP client initializes, it often sends all tool descriptions to the LLM in the system prompt. If you expose 50 tools with OpenAPI-style verbose descriptions, you can consume 4k-8k tokens before any user input. The common mistake is copying API documentation directly into the tool description. The fix is treating the description as a 'sparse prompt' where the LLM only needs enough context to select the right tool; the JSON Schema handles the parameter details. Hierarchical naming helps the LLM route without reading full descriptions, similar to function naming conventions in codebases.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-22T14:05:47.381391+00:00— report_created — created