[DOCS] Vertex AI docs omit MCP tool search default disablement

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Configure tool search" in the MCP guide, plus the related Vertex AI setup and environment variable reference pages.

Current Documentation

The docs currently say:

"Tool search is enabled by default: MCP tools are deferred and discovered on demand. When ANTHROPIC_BASE_URL points to a non-first-party host, tool search is disabled by default because most proxies do not forward tool_reference blocks. Set ENABLE_TOOL_SEARCH explicitly if your proxy does."

And the environment variable reference says:

"ANTHROPIC_BASE_URL ... When set to a non-first-party host, MCP tool search is disabled by default. Set ENABLE_TOOL_SEARCH=true if your proxy forwards tool_reference blocks"

"ENABLE_TOOL_SEARCH ... Unset: all MCP tools deferred by default, but loaded upfront when ANTHROPIC_BASE_URL points to a non-first-party host."

The Vertex AI setup page documents CLAUDE_CODE_USE_VERTEX=1, ANTHROPIC_VERTEX_PROJECT_ID, and optional ANTHROPIC_VERTEX_BASE_URL, but it does not mention that Vertex AI disables tool search by default or that users must opt in with ENABLE_TOOL_SEARCH.

What's Wrong or Missing?

Changelog v2.1.119 says:

Tool search is now disabled by default on Vertex AI to avoid an unsupported beta header error (opt in with ENABLE_TOOL_SEARCH)

The current docs still describe tool search as enabled by default except for non-first-party ANTHROPIC_BASE_URL proxy hosts. That leaves out the Vertex AI-specific default and the reason for it.

As written, the docs can mislead Vertex AI users into expecting deferred MCP tool loading to work automatically, even though the current behavior requires explicitly setting ENABLE_TOOL_SEARCH to opt in.

Suggested Improvement

Update the MCP and environment variable docs to document the Vertex AI exception explicitly.

Suggested changes:

1. In mcp → "Configure tool search", note that Vertex AI disables tool search by default to avoid unsupported beta header errors, and that users can opt in with ENABLE_TOOL_SEARCH.
2. In the ENABLE_TOOL_SEARCH and related base URL rows in env-vars, clarify how the unset/default behavior changes on Vertex AI.
3. In google-vertex-ai, add a short note or example such as:

Optional: Vertex AI disables MCP tool search by default to avoid unsupported beta header errors. If your Vertex setup supports tool search, opt in explicitly with ENABLE_TOOL_SEARCH=true (or auto / auto:N as appropriate).

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary "Configure tool search" explanation and behavior table |
| https://code.claude.com/docs/en/env-vars | ANTHROPIC_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, and ENABLE_TOOL_SEARCH reference entries |
| https://code.claude.com/docs/en/google-vertex-ai | Vertex AI setup instructions and configuration notes |
| https://code.claude.com/docs/en/third-party-integrations | Vertex AI gateway configuration guidance |

Total scope: 4 pages affected

Source: Changelog v2.1.119

Exact changelog entry: Tool search is now disabled by default on Vertex AI to avoid an unsupported beta header error (opt in with ENABLE_TOOL_SEARCH)