[DOCS] MCP Tool Search behavior conflicts between docs.claude.com and Anthropic partner training (Claude Code 101)

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/mcp and https://anthropic-partners.skilljar.com/claude-code-101 (Context Costs lesson)

Section/Topic

MCP Tool Search default behavior

Current Documentation

code.claude.com/docs/en/mcp says:
"Tool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and Claude uses a search tool to discover relevant ones when a task needs them. Only the tools Claude actually uses enter context."

The Anthropic Partner Network course "Claude Code 101" (Context Costs lesson) says:
"MCP servers add tool definitions to your context window — even when you're not actively using them... If your MCP tools exceed 10% of your context window, Claude Code automatically switches to tool search mode."

What's Wrong or Missing?

These two Anthropic-authored sources describe different default behaviors for MCP Tool Search:

• code.claude.com/docs/en/mcp implies ALL MCP tool definitions are deferred by default, regardless of size — only tool names/server instructions load at session start.
• The partner training course implies tool definitions load into context normally by default, and only switch to search/deferred mode once they cross a 10% context threshold.

docs.claude.com/en/agent-sdk/tool-search suggests the 10%-threshold behavior is actually the opt-in ENABLE_TOOL_SEARCH=auto mode, not the default — which would mean the partner course is describing outdated/pre-update behavior. But this isn't confirmed, and it's confusing for anyone cross-referencing the two.

Suggested Improvement

Please confirm which is the current default behavior and update whichever source is stale:

1. If "always deferred" is the current default, update the Claude Code 101 partner course's "Context Costs" lesson to remove the 10%-threshold framing, or clarify that 10% only applies to ENABLE_TOOL_SEARCH=auto.
2. If a 10% threshold still applies by default in some configurations, update code.claude.com/docs/en/mcp to mention the threshold rather than implying unconditional deferral.

Suggested text for code.claude.com/docs/en/mcp (if threshold still applies):
"Tool search is enabled by default. When MCP tool descriptions would exceed 10% of your context window, tools are deferred rather than loaded upfront, and Claude uses a search tool to discover relevant ones on demand."

Impact

Medium - Makes feature difficult to understand

Additional Context

Screenshot of the partner course "Context Costs" lesson attached (anthropic-partners.skilljar.com/claude-code-101/469797).

<img width="2554" height="1298" alt="Image" src="https://github.com/user-attachments/assets/453e8e7d-e541-4646-9763-19520c977483" />