Subagents fail with 'prompt is too long' when user has many MCP servers (tool definitions exceed 200k)

[TweedBeetle]

Problem

When a user has many MCP servers configured at the user level, subagents (Explore, Plan, general-purpose) fail immediately with prompt is too long: 209117 tokens > 200000 maximum before executing a single tool call. The TUI shows Done (0 tool uses · 0 tokens · 44s) with no error visible to the user.

Root Cause

Subagents inherit all MCP tool definitions from the parent session. Each tool definition includes a full JSON schema. With many MCP servers, the tool schemas alone exceed Sonnet's 200k context limit.

Reproduction

Setup: 34 MCP servers configured in ~/.claude.json (Bright Data, Discord, GitHub, Gmail, Playwright, Sentry, YouTube, etc.) totaling ~566 MCP tools.

Main session: Opus 4.6 (1M context) on Claude Max — works fine, 209k of tool schemas fits within 1M.

Subagent spawn: Any Agent call (Explore, Plan, general-purpose) → Sonnet 200k → immediate API error:

"error": "invalid_request"
"errorDetails": "prompt is too long: 209117 tokens > 200000 maximum"

The user prompt was ~156 tokens. The Explore system prompt is ~500 tokens. The remaining ~208,000 tokens are tool definitions.

Subagent JSONL evidence (from agent-a4ff9338a6a5a0f09.jsonl):

{
  "error": "invalid_request",
  "errorDetails": "400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"prompt is too long: 209117 tokens > 200000 maximum\"}}"
}

Version: Claude Code v2.1.81, macOS, Claude Max subscription.

Why This Isn't a Duplicate

Previous issues were auto-closed incorrectly:

• Intelligently disable MCP tools for subagents to prevent context overflow #29157 ("Intelligently disable MCP tools for subagents") → auto-duped to Task agent fails with 'tools: Tool names must be unique' when parent has many MCP tools #10668 ("Tool names must be unique"), which was a completely different bug fixed in v2.0.31
• Feature: hierarchical deferred tool discovery to reduce context usage from large MCP servers #27208 ("Hierarchical deferred tool discovery") → auto-duped to Feature: Lazy MCP tool group loading to reduce context usage #23508 ("Lazy MCP tool group loading"), which was closed as stale without resolution

The underlying problem — subagents receiving all MCP tool schemas regardless of relevance, causing context overflow — remains unfixed.

Proposed Solutions (any would work)

1. Apply deferred/ToolSearch to subagents — The main session already uses deferred tools (tool names listed, schemas loaded on demand via ToolSearch). Subagents should get the same treatment.
2. Filter tools by subagent type — Explore agents don't need Canva, Stripe, Discord, etc. Only pass tools relevant to the subagent's declared tool set.
3. Inherit parent model — If the main session is Opus 1M, subagents should also get 1M context (or at least Sonnet 1M if available on the plan).
4. Graceful degradation — If tool definitions exceed the subagent's context, prune least-relevant MCP tools rather than failing silently.

Workarounds

• Pass model: "opus" explicitly on Agent calls (costs more quota)
• Reduce MCP servers in ~/.claude.json (defeats the purpose of having them)
• Move servers to project-level configs (tedious, easy to forget)

Impact

Any Claude Max user with 15+ MCP servers will hit this. The failure is completely silent in the TUI — users see "0 tool uses · 0 tokens" and have no idea why. This makes Explore, Plan, and general-purpose agents unusable for power users.

[github-actions]

Found 2 possible duplicate issues:

1. [FEATURE] Extend deferred tool loading to built-in subagents #31623
2. Intelligently disable MCP tools for subagents to prevent context overflow #29157

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[Cianai]

Not a duplicate of #10668 or #31623 — this is a distinct bug, not a feature request.

#10668 was about non-unique tool names causing conflicts (fixed in v2.0.31). This issue is about tool schema volume exceeding the subagent context window.

#31623 is the feature request for the real fix (deferred tool loading for subagents). This issue is the bug report documenting the broken behavior that fix would address. Both should remain open — one tracks the symptom, the other the solution.

Reproducing independently: I hit this on v2.1.81 with 25 MCP servers (~450 tools) on Claude Max (Opus 1M main session). Every Explore/Plan/general-purpose subagent fails immediately with Prompt is too long. Workaround: model: "opus" on all Agent calls, which defeats the purpose of lighter subagents.

The auto-close bot's duplicate detection is pattern-matching on keywords, not understanding the issue semantics. Please keep this open.

[samargy]

Also have the exact same issue.

[draciunescu]

Having the same issue.