/doctor MCP warning doesn't distinguish deferred vs always-loaded tools

Resolved 💬 4 comments Opened Mar 2, 2026 by alexswan123 Closed Mar 30, 2026

Summary

/doctor reports a "Large MCP tools context" warning that counts all MCP tools at their full schema token cost, even when they're deferred (loaded on-demand via ToolSearch).

Example

Context Usage Warnings
 └ ⚠ Large MCP tools context (~52,780 tokens > 25,000)
   └ MCP servers:
     └ posthog: 52 tools (~26,624 tokens)
     └ gmail: 19 tools (~9,728 tokens)
     └ google-calendar: 13 tools (~6,656 tokens)
     └ claude_ai_Google_Calendar: 9 tools (~4,608 tokens)
     └ claude_ai_Gmail: 6 tools (~3,072 tokens)
     └ (1 more servers)

All of these tools are deferred — they appear in the ToolSearch deferred tools list and their full schemas only load when explicitly selected via ToolSearch. The actual per-turn cost is just the tool names in the ToolSearch description, which is significantly less than 52K tokens.

Expected behaviour

/doctor should either:

  1. Not count deferred tools toward the "Large MCP tools context" threshold, or
  2. Distinguish between deferred and always-loaded tools in the warning (e.g. "52,780 tokens total, ~X always-loaded, ~Y deferred")

Impact

The current warning is misleading — users may spend time removing or reconfiguring MCP servers that aren't actually causing context bloat, or just learn to ignore /doctor warnings entirely.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗