[DOCS] MCP Tool Search docs omit gateway compatibility behavior for `ANTHROPIC_BASE_URL` proxies

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

MCP Tool Search compatibility guidance for third-party gateways configured via ANTHROPIC_BASE_URL.

Current Documentation

The docs currently say:

Tool search runs in auto mode by default ... This feature requires models that support tool_reference blocks: Sonnet 4 and later, or Opus 4 and later.

And gateway requirements currently say:

For an LLM gateway to work with Claude Code, it must meet the following requirements ...

Claude Code determines which features to enable based on the API format.

What's Wrong or Missing?

Changelog v2.1.70 includes a user-facing fix for third-party gateway setups:

• API 400 errors when using ANTHROPIC_BASE_URL with a gateway are now handled by detecting proxy endpoints and disabling tool_reference blocks.

Current MCP + gateway docs do not explain this compatibility behavior or troubleshooting path. They describe model support and gateway API shape, but they do not tell users what happens when a gateway/proxy path cannot safely use tool_reference blocks.

Suggested Improvement

Add a short compatibility note in MCP Tool Search docs (and cross-link from LLM gateway docs) that explains:

1. Tool Search may disable tool_reference blocks automatically when a third-party proxy endpoint is detected.
2. Why this prevents 400 errors with certain gateway configurations.
3. A troubleshooting checklist for ANTHROPIC_BASE_URL + gateway users (what to verify, and how to confirm Tool Search mode).

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 988-1015 | Tool Search behavior and tool_reference requirement, but no gateway/proxy compatibility note |
| https://code.claude.com/docs/en/llm-gateway | 17-38, 126-142 | Gateway requirements and ANTHROPIC_BASE_URL examples without Tool Search compatibility guidance |
| https://platform.claude.com/docs/en/agent-sdk/mcp | 334-350 | Agent SDK cross-reference: mirrors Tool Search tool_reference requirement without proxy behavior notes |

Total scope: 3 pages affected

Source: Release v2.1.70

• Fixed API 400 errors when using ANTHROPIC_BASE_URL with a third-party gateway — tool search now correctly detects proxy endpoints and disables tool_reference blocks