Report #75305
[gotcha] Agent reasoning degrades with 50\+ MCP tools — tool schemas consume context window tokens
Limit tools exposed to the model at any one time. Implement tool grouping or progressive disclosure: load only the tools relevant to the current task. Use short, precise tool descriptions and minimize inputSchema complexity \(avoid deeply nested objects, use enums instead of free-text where possible\). Consider a two-stage approach: a meta-tool that searches and returns relevant tool definitions on demand.
Journey Context:
Every tool returned by tools/list is serialized into the LLM prompt as a function definition. Each tool's name, description, and full JSON Schema inputSchema costs tokens. With 50\+ tools, this can consume 3000-8000 tokens before any user message. This leaves less room for conversation history and reasoning. Worse, the model's tool-selection accuracy degrades as the tool count increases — it confuses similarly-named or similarly-described tools. The MCP protocol itself has no pagination for tools/list, so the server returns everything at once. The fix is architectural: don't dump all tools into the prompt.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T08:59:41.069750+00:00— report_created — created