1 · 30 秒速览

1 · The 30-second version

一句话:工具定义是要占上下文的,而且是每一轮都占。当工具从十几个涨到上百个,你会同时踩到两个坑——token 账单变贵、模型选错工具变多。解法的共同思路是:别一开始就把所有工具说明书塞进去,让模型需要的时候再去「查目录」。

In one line: tool definitions consume context, and they do it on every turn. Once your toolset grows from a dozen to a few hundred, you hit two problems at once — a bigger token bill and more wrong-tool selections. Every fix shares the same idea: don't load the whole manual upfront; let the model look things up when it actually needs them.

来源:Anthropic Engineering, Introducing advanced tool use(2025-11-24) · Tool search tool, Claude Platform Docs

Sources: Anthropic Engineering, "Introducing advanced tool use" (Nov 24, 2025) · Tool search tool, Claude Platform Docs

2 · 问题从哪来:你其实在付两笔账

2 · Where the problem comes from: you're paying two bills

先讲清楚一个容易被忽略的机制:模型不会「知道」你有哪些工具,你必须在每一次请求里,把每个工具的名字、说明、参数结构(JSON Schema)全部写给它。这堆说明书通常放在系统提示词的前缀里,是对话的固定开销。

Start with a mechanism that's easy to overlook: the model has no innate knowledge of your tools. You must send every tool's name, description, and parameter schema (JSON Schema) with every request. That bundle normally sits in the system-prompt prefix — a fixed overhead on the whole conversation.

第一笔账:token

Bill #1: tokens

Anthropic 官方给出的一组实测数字,是一个很典型的「五个 server」配置:

Anthropic published measurements for a typical five-server setup:

再加一个 Jira(单独约 17K),很快就逼近 10 万 token 的开销。官方还提到:在 Anthropic 内部,曾出现工具定义在优化前吃掉 134K token 的情况。

Add Jira (~17K on its own) and you're closing in on 100K+ of overhead. Anthropic also notes that internally they have seen tool definitions consume 134K tokens before optimization.

第二笔账:准确率

Bill #2: accuracy

这笔账更隐蔽,但往往更致命。官方原话是:「最常见的失败是选错工具和参数给错,尤其当工具名字很像的时候」——例如 notification-send-user 和 notification-send-channel。Claude Platform 文档进一步给出量化边界:一旦可用工具超过 30–50 个,Claude 挑对工具的能力就开始下降。

This one is subtler but often more damaging. In Anthropic's words: "the most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names" — think notification-send-user vs. notification-send-channel. The platform docs put a number on it: Claude's ability to pick the right tool degrades once you exceed 30–50 available tools.

3 · 核心概念:五个词看懂机制

3 · Core concepts: five terms that explain the mechanism

defer_loading(延迟加载标记)

打在单个工具定义上的布尔值。它控制的是「什么进上下文窗口」,不是「什么发给 API」——你每次请求依然要把所有工具的完整定义发过去,因为服务端要靠它们来跑搜索和展开引用。至少要有一个工具不被延迟(通常就是搜索工具本身),否则 API 直接返回 400。

tool_reference(工具引用块)

搜索命中后 API 返回的一个轻量指针,只带工具名。API 会在把内容交给模型之前,自动把它展开成完整定义。你不需要、也不应该自己展开。

server_tool_use(服务端工具调用)

搜索这一步是在 Anthropic 服务器上跑的,不需要你执行。它的 id 形如 srvtoolu_...——绝对不要给这个 id 回 tool_result,API 会拒绝整个请求。

regex 变体 vs BM25 变体

两种搜索算法。tool_search_tool_regex_20251119 让 Claude 写 Python re.search() 正则(大小写不敏感,模式最长 200 字符);tool_search_tool_bm25_20251119 让 Claude 用自然语言查询(最长 500 字符)。两者都会搜索工具名、描述、参数名和参数描述。

Progressive discovery(渐进式发现)

更上位的一个模式名:server 先只暴露一个很小的入口,随着对话收敛再逐步露出更多目录。Tool Search 是这个模式在 Anthropic 平台上的一种实现;截至调研时,它还不是 MCP 协议本身的一部分,但已被 2026-08-22 的新版 MCP 路线图列为优先方向(见第 8 节)。

defer_loading

A boolean on an individual tool definition. It controls what enters the context window, not what you send in the request — you still ship every full definition on every request, because the server needs them to run the search and expand references. At least one tool must stay non-deferred (normally the search tool itself), or the API returns a 400.

tool_reference

A lightweight pointer the API returns for each search hit, carrying only a tool name. The API expands it into the full definition before the model sees it. You neither need to nor should expand it yourself.

server_tool_use

The search step runs on Anthropic's servers; you don't execute it. Its id looks like srvtoolu_... — never return a tool_result for that id, or the API rejects the request.

regex variant vs. BM25 variant

Two search algorithms. With tool_search_tool_regex_20251119 Claude writes Python re.search() patterns (case-insensitive, max 200 characters). With tool_search_tool_bm25_20251119 Claude writes natural-language queries (max 500 characters). Both search tool names, descriptions, argument names and argument descriptions.

Progressive discovery

The umbrella pattern: a server exposes a small entry point first and reveals more of its catalog as the conversation narrows. Tool Search is Anthropic's platform implementation of it. As of this research it is not part of the MCP specification itself, but the MCP roadmap published on 2026-08-22 names it a priority (see §8).

4 · 怎么用:三层落地

4 · How to use it: three layers

同一个能力在三个层面上暴露给你,配置方式完全不同。搞清楚你在哪一层,能省掉大量试错。

The same capability is exposed at three levels, each configured differently. Knowing which level you're on saves a lot of trial and error.

4.1 API 层:显式打标记

4.1 API level: mark tools explicitly

把搜索工具放进 tools 数组,给不常用的工具加 defer_loading: true:

Put a search tool in the tools array and add defer_loading: true to the less-used tools:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "旧金山天气怎么样?"}],
    tools=[
        # 搜索工具本身:绝不能延迟加载
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": { ... },
            "defer_loading": True,       # ← 用到再加载
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": { ... },
            "defer_loading": True,
        },
    ],
)

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        # The search tool itself: never defer this one
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": { ... },
            "defer_loading": True,       # ← loaded on demand
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": { ... },
            "defer_loading": True,
        },
    ],
)

如果工具来自 MCP 连接器,不要在单个工具上打标记,而是在 mcp_toolset 条目上按 server 整体设置,再对个别高频工具开例外:

If the tools come from the MCP connector, don't mark individual tools. Set it once on the mcp_toolset entry for the whole server, then make exceptions for high-use tools:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": { "defer_loading": true },   // 整个 server 延迟
  "configs": {
    "search_files": { "defer_loading": false }   // 最常用的那个保持常驻
  }
}

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": { "defer_loading": true },   // defer the whole server
  "configs": {
    "search_files": { "defer_loading": false }   // keep the most-used tool loaded
  }
}

代码来自 Claude Platform Docs · Tool search tool 与 Anthropic Engineering,已按中文语境改写注释与 prompt。

Code adapted from Claude Platform Docs · Tool search tool and Anthropic Engineering.

4.2 Agent SDK 层:默认已开,用阈值调

4.2 Agent SDK level: on by default, tuned by threshold

在 Claude Agent SDK 里,tool search 默认就是开的,你不用做任何事。要调的话用 ENABLE_TOOL_SEARCH 环境变量:

In the Claude Agent SDK, tool search is on by default — you don't have to do anything. To tune it, use the ENABLE_TOOL_SEARCH environment variable:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": { type: "http", url: "https://tools.example.com/mcp" }
    },
    allowedTools: ["mcp__enterprise-tools__*"],   // 通配符预授权整个 server
    env: {
      ...process.env,          // TS 里 env 会替换子进程环境,必须展开继承变量
      ENABLE_TOOL_SEARCH: "auto:5"
    }
  }
})) { /* ... */ }

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": { type: "http", url: "https://tools.example.com/mcp" }
    },
    allowedTools: ["mcp__enterprise-tools__*"],   // wildcard pre-approves the server
    env: {
      ...process.env,          // in TS, env replaces the subprocess env — spread to keep inherited vars
      ENABLE_TOOL_SEARCH: "auto:5"
    }
  }
})) { /* ... */ }

4.3 Claude Code CLI 层:用 alwaysLoad 开例外

4.3 Claude Code CLI level: carve out exceptions with alwaysLoad

日常用 Claude Code 时,tool search 同样默认开启。你唯一需要主动做的决定是:哪个 server 的工具必须每轮常驻?在它的配置上加 alwaysLoad: true,该 server 的工具就以完整 schema 在第一轮可用,豁免于 tool search 延迟。

In day-to-day Claude Code use, tool search is likewise on by default. The one decision you actively make: which server's tools must be resident every turn? Set alwaysLoad: true on its config and that server's tools are available at full schema from the first turn, exempt from tool-search deferral.

{
  "mcpServers": {
    "our-internal-api": {
      "type": "http",
      "url": "https://tools.internal.example.com/mcp",
      "alwaysLoad": true          // 每轮都用 → 免去一次搜索往返
    },
    "jira": {
      "type": "http",
      "url": "https://jira.example.com/mcp"
      // 不设 alwaysLoad → 交给 tool search 按需发现
    }
  }
}

{
  "mcpServers": {
    "our-internal-api": {
      "type": "http",
      "url": "https://tools.internal.example.com/mcp",
      "alwaysLoad": true          // used every turn → skip the search round-trip
    },
    "jira": {
      "type": "http",
      "url": "https://jira.example.com/mcp"
      // no alwaysLoad → discovered on demand by tool search
    }
  }
}

alwaysLoad 还有一个副作用值得知道:Claude Code 会在启动时等这个 server 的工具列表(受同一个连接超时上限约束),其它 server 继续在后台连接;如果是有缓存工具列表的远程 server,则无需连接即可提供。

One side effect worth knowing: Claude Code waits at startup for that server's tools (capped by the same connection deadline) while other servers keep connecting in the background. A remote server with a cached tool list supplies them without connecting at all.

来源:Claude Code Docs · Scale to many tools with tool search · Connect to external tools with MCP

Sources: Claude Code Docs · Scale to many tools with tool search · Connect to external tools with MCP

4.4 让搜索搜得准:写好名字和描述

4.4 Make search work: names and descriptions matter

搜索是按名字和描述匹配的,所以这两样东西的质量直接决定发现准确率。官方给的正反例:

Search matches against names and descriptions, so their quality directly determines discovery accuracy. Anthropic's own good/bad example:

// 好
{
  "name": "search_customer_orders",
  "description": "Search for customer orders by date range, status, or total amount.
                  Returns order details including items, shipping, and payment info."
}

// 差
{
  "name": "query_db_orders",
  "description": "Execute order query"
}

// Good
{
  "name": "search_customer_orders",
  "description": "Search for customer orders by date range, status, or total amount.
                  Returns order details including items, shipping, and payment info."
}

// Bad
{
  "name": "query_db_orders",
  "description": "Execute order query"
}

• 统一命名空间:用服务或资源做前缀(github_、slack_),一次搜索就能命中一整组。
• 描述里放用户会用的词:用户怎么描述任务,描述里就该出现那些词。
• 在系统提示词里加一段「有哪些类别」:比如「你可以搜索用于 Slack、GitHub、Jira 的工具」——让模型知道值得去搜什么。
• 观察它实际发现了什么,反过来改描述。

• Namespace consistently: prefix by service or resource (github_, slack_) so one search matches a whole group.
• Use the words your users use: descriptions should echo how people phrase the task.
• Add a category list to the system prompt: e.g. "You can search for tools to interact with Slack, GitHub, and Jira" — so the model knows what's worth searching for.
• Watch what it actually discovers and refine descriptions from there.

5 · 什么场景用:阈值、案例与真实数据

5 · When to use it: thresholds, cases, and real numbers

官方给的判断标准

The official decision criteria

案例:Amazon Prime Video 的自建渐进式发现

Case: Amazon Prime Video's home-grown progressive discovery

据 ZenML 的 LLMOps 案例库记录,Amazon Prime Video 团队遇到的问题是:内部 agent 接入了集中式 MCP server,上面有数百个工具,上下文膨胀既拖慢性能又让幻觉变多。他们的做法是用 MCP 的协议通知(notifications)与会话追踪,初始化时只暴露一个「find tools」能力,agent 按问题类别动态发现并加载相关子集,把每个任务面对的工具数从数百个压到三四个。

Per ZenML's LLMOps case database, the Amazon Prime Video team hit this: internal agents were connecting to a centralized MCP server carrying hundreds of tools, and the resulting context bloat both degraded performance and increased hallucinations. Their fix used MCP protocol notifications plus session tracking to expose a single "find tools" capability at initialization; agents then discovered and loaded a relevant subset per problem category, cutting tool exposure from hundreds down to three or four per task.

来源:ZenML LLMOps Database · Amazon: Progressive Tool Discovery for MCP Servers(第三方整理的案例记录,非 Amazon 一手公告,细节以原始演讲为准)

Source: ZenML LLMOps Database · "Amazon: Progressive Tool Discovery for MCP Servers" — a third-party case write-up rather than a first-party Amazon announcement; check the original talk for details.

相邻案例:Claude for Excel 与程序化工具调用

Adjacent case: Claude for Excel and programmatic tool calling

Anthropic 提到,Claude for Excel 使用的是同一批「高级工具使用」能力中的另一个——程序化工具调用(Programmatic Tool Calling),用来读写数千行的表格而不撑爆上下文。这说明一件事:「工具太多」和「工具结果太大」是两个不同的病,药也不同(下一节展开)。

Anthropic notes that Claude for Excel uses a sibling capability from the same "advanced tool use" batch — Programmatic Tool Calling — to read and modify spreadsheets with thousands of rows without overloading context. The lesson: "too many tools" and "tool results too large" are different ailments with different cures (next section).

6 · 对比与选型:三种「省上下文」的手段别搞混

6 · Alternatives & trade-offs: three context-saving tools, don't mix them up

官方建议是先找你最大的瓶颈,对症下一个药,再按需叠加——不要一上来就三个全开。

Anthropic's advice: start with your biggest bottleneck and apply one fix, then layer more as needed — don't turn all three on upfront.

还有哪些路子

Other approaches in the wild

• 自定义搜索(嵌入 / 语义检索):官方明确支持——你自己写一个搜索工具,返回 tool_result 里带 tool_reference 块即可,API 照样帮你展开。前提是被引用的工具在顶层 tools 里有定义(通常 defer_loading: true)。适合内置的 regex/BM25 匹配不动你的领域词汇时。
• server 侧自建渐进式发现:像 Prime Video 那样,在 MCP server 内部实现「先给一个 find_tools 入口」。好处是对任何客户端都生效、不依赖某家模型厂;代价是你要自己维护这套逻辑。
• tools/list 分页:MCP 规范本身支持游标分页,客户端可以分批取工具。这是最"协议原生"的降载手段,但它解决的是传输层面的分批,不等于模型上下文里就少了工具——真正的收益取决于客户端怎么用。

• Custom search (embeddings / semantic retrieval): officially supported — write your own search tool and return tool_reference blocks inside a normal tool_result; the API expands them the same way. Every referenced tool must still have a definition in the top-level tools array, normally with defer_loading: true. Useful when built-in regex/BM25 matching doesn't fit your domain vocabulary.
• Server-side progressive discovery: as Prime Video did — implement a "find_tools" entry point inside the MCP server itself. It works for any client and doesn't depend on one model vendor; the cost is that you maintain the logic.
• tools/list pagination: the MCP spec supports cursor-based pagination, so clients can fetch tools in chunks. It's the most protocol-native lever, but it batches transport, which isn't the same as fewer tools in the model's context — the actual benefit depends on what the client does with the pages.

7 · 常见坑与限制

7 · Pitfalls & limits

1. 把所有工具都延迟了 → 400 报错。至少要有一个 defer_loading=false。错误信息原文:At least one tool must have defer_loading=false. 别把搜索工具本身也标上延迟。
2. 给 srvtoolu_... 回了 tool_result → 请求被拒。搜索是服务端跑的,那一步不需要你返回结果。继续对话时,要把 server_tool_use 与 tool_search_tool_result 块原样放回消息历史,并且每次都发同一套完整 tools 数组。
3. 延迟的工具不能带 cache_control → 400。缓存断点要打在没被延迟的工具上。
4. 引用了没有定义的工具 → 400。报错原文:Tool reference 'unknown_tool' not found in available tools。自定义搜索时尤其容易踩。
5. 多了一次往返。首次发现某个工具时会多一个搜索步骤。工具少于 10 个、定义能舒服装进上下文时,全部前加载通常更快。这是一个真实的延迟代价,不是纯赚。
6. 长对话被压缩后,已发现的工具可能被清掉。SDK 压缩早期消息释放空间时,先前发现的工具可能一起消失,模型需要重新搜索。这是设计如此,但会影响你对延迟的预期。
7. 代理和第三方部署会静默改变行为。ANTHROPIC_BASE_URL 指向非一方主机时,SDK 默认关闭 tool search(多数代理不转发 tool_reference 块);Azure 上托管的 Microsoft Foundry 部署会在服务端拒绝,ENABLE_TOOL_SEARCH 也覆盖不了。
8. 搜不到不报错,返回空数组。没命中时是一个 tool_references 为空的正常结果,不是错误——排查时别只盯着异常。
9. 模型有门槛。Claude Opus 4.1 及更早的模型不支持 tool search;Agent SDK 侧最低是 Sonnet 4.5 / Haiku 4.5 / Opus 4.5 及之后。
10. 规模上限。每次请求最多 10,000 个延迟工具;每次搜索默认返回最多 5 个命中(模型可自行把 limit 设到 1–10,000);regex 模式最长 200 字符,BM25 查询最长 500 字符。

1. Deferring every tool → 400. At least one tool needs defer_loading=false. The error reads: At least one tool must have defer_loading=false. Never defer the search tool itself.
2. Returning a tool_result for srvtoolu_... → rejected. The search runs server-side; that step needs no result from you. When continuing, pass the server_tool_use and tool_search_tool_result blocks back unchanged, and send the same complete tools array every time.
3. A deferred tool can't carry cache_control → 400. Put the cache breakpoint on a non-deferred tool.
4. Referencing a tool with no definition → 400. The error reads: Tool reference 'unknown_tool' not found in available tools. Easy to hit with custom search implementations.
5. You add a round-trip. The first time Claude discovers a tool there's an extra search step. With fewer than ~10 tools whose definitions fit comfortably, loading everything upfront is typically faster. This is a real latency cost, not a free win.
6. Compaction can drop discovered tools. When the SDK compacts earlier messages to free space in a long conversation, previously discovered tools may be removed and the agent searches again. By design, but it shapes your latency expectations.
7. Proxies and third-party deployments silently change behavior. With ANTHROPIC_BASE_URL pointed at a non-first-party host, the SDK disables tool search by default (most proxies don't forward tool_reference blocks). Microsoft Foundry deployments hosted on Azure reject it server-side, and ENABLE_TOOL_SEARCH can't override that.
8. No match is not an error. A search that matches nothing returns a normal result with an empty tool_references array — don't debug by only watching for exceptions.
9. Model floor. Claude Opus 4.1 and earlier don't support tool search. On the Agent SDK the minimum is Sonnet 4.5 / Haiku 4.5 / Opus 4.5 and later.
10. Scale limits. Up to 10,000 deferred tools per request; each search returns up to 5 hits by default (the model may set limit from 1 to 10,000); regex patterns max 200 characters, BM25 queries max 500.

8 · 协议侧:2026-08-22 的新版 MCP 路线图

8 · Protocol side: the new MCP roadmap (2026-08-22)

上面讲的都是某一家平台的实现。而就在 2026 年 8 月 22 日,MCP 核心维护者 David Soria Parra 与 Den Delimarsky 发布了新版路线图,把这件事抬到了协议级议程。路线图收敛为五个优先领域,其中「改进原语(Improved primitives)」一节直接点了这个问题:

Everything above is one platform's implementation. On August 22, 2026, MCP lead maintainers David Soria Parra and Den Delimarsky published a new roadmap that raises the issue to the protocol agenda. It's organized into five priority areas, and the "Improved primitives" section names this problem directly:

同一节还提到另一件相关的事:tools/call 的响应可以用多种形式携带同一份输出,而 server 开发者今天没办法知道某个客户端会把哪一种形式呈现给模型——路线图的目标是收敛到一份清晰的契约。

The same section flags a related issue: a tools/call response can carry the same output in more than one form, and a server developer has no way to know which form a given client will put in front of the model. The roadmap aims to standardize on one clear contract.

五个优先领域一览

The five priority areas at a glance

来源:The New MCP Roadmap(2026-08-22) · 路线图页面

Sources: The New MCP Roadmap (Aug 22, 2026) · The roadmap page

9 · 学习资源

9 · Resources

• Tool search tool — Claude Platform Docs:API 层最完整的参考,含响应格式、错误码、限制、自定义搜索实现。
• Scale to many tools with tool search — Claude Code Docs:Agent SDK 侧的默认行为与 ENABLE_TOOL_SEARCH 全部取值。
• Connect to external tools with MCP — Claude Code Docs:alwaysLoad、连接时序、allowedTools 权限、错误排查。
• Introducing advanced tool use — Anthropic Engineering:三个能力的设计动机与实测数字的一手出处。
• Programmatic tool calling — Claude Platform Docs:结果太大时的对症方案。
• The New MCP Roadmap 与 roadmap 页面:协议未来方向。
• Cookbook:用嵌入做工具搜索:自定义搜索的完整示例。

• Tool search tool — Claude Platform Docs: the fullest API-level reference, including response format, error codes, limits, and custom search implementations.
• Scale to many tools with tool search — Claude Code Docs: SDK defaults and every value of ENABLE_TOOL_SEARCH.
• Connect to external tools with MCP — Claude Code Docs: alwaysLoad, connection timing, allowedTools permissions, troubleshooting.
• Introducing advanced tool use — Anthropic Engineering: first-party source for the design rationale and the measured numbers.
• Programmatic tool calling — Claude Platform Docs: the fix when results, not definitions, are the problem.
• The New MCP Roadmap and the roadmap page: where the protocol is heading.
• Cookbook: tool search with embeddings: a complete custom-search example.