Agent SDK 工具搜索（Tool Search）参考

本文是对 Claude Agent SDK 官方文档某页的中文整理，完整与最新内容以原文为准：https://code.claude.com/docs/en/agent-sdk/tool-search

概述

Tool search（工具搜索）让 agent 能够处理成百上千个工具，方式是按需动态发现并加载工具，而不是一开始就把所有工具定义都塞进上下文窗口。agent 会搜索你的工具目录，只加载它需要的工具。

这种方式解决了工具库规模扩大后的两个问题：

• 上下文效率：工具定义会占用上下文窗口的大量空间（50 个工具可能消耗 10-20K tokens），留给实际工作的空间就变少。
• 工具选择准确率：一次性加载超过 30-50 个工具后，工具选择的准确率会下降。

工作原理

Tool search 默认开启，例外情况见下文「配置 tool search」一节。

当它处于激活状态时，工具定义不会出现在上下文窗口中。agent 会收到一份可用工具的摘要，当任务需要一个尚未加载的能力时就去搜索相关工具。默认情况下，最多会有 5 个最相关的工具被加载进上下文，并在后续轮次中保持可用。如果对话足够长、SDK 对早期消息做了压缩（compact）以腾出空间，之前发现的工具可能会被移除，agent 会在需要时重新搜索。

Claude 第一次发现某个工具时，tool search 会多一次往返（搜索这一步），但对大型工具集而言，每一轮更小的上下文会抵消这个开销。如果工具少于约 10 个、定义能轻松放进上下文窗口，通常直接预先加载全部工具会更快。

关于底层 API 机制的细节，参见官方文档「Tool search in the API」：https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

注意：Tool search 不支持部署在 Azure 上的 Microsoft Foundry 部署（该场景下服务端会拒绝该功能）。SDK 会检测到这一拒绝并为该部署改为预先加载工具定义。ENABLE_TOOL_SEARCH 无法覆盖这一行为，因为拒绝来自部署本身。

配置 tool search

Tool search 默认开启。对于 SDK 「不支持模型列表」中的模型，SDK 会改为预先加载工具定义，任何 ENABLE_TOOL_SEARCH 取值都无法覆盖这一点。在 Google Cloud 的 Agent Platform 上，SDK 会按模型代际决定：

• Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新模型：tool search 默认开启。
• 更早的 Agent Platform 模型：SDK 会预先加载工具定义，因为它们的服务栈会拒绝所需的 beta header。ENABLE_TOOL_SEARCH 无法覆盖这一行为。

在 Claude Code v2.1.221 之前，SDK 会对 Google Cloud Agent Platform 上的所有模型禁用 tool search，除非你设置了 ENABLE_TOOL_SEARCH。

当 ANTHROPIC_BASE_URL 指向一个非 first-party 主机时，SDK 也会禁用 tool search，因为大多数代理不会转发 tool_reference 数据块。你可以通过 ENABLE_TOOL_SEARCH 环境变量覆盖这个默认行为：

设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 会使 tool search 保持关闭状态，你无法通过自行设置 ENABLE_TOOL_SEARCH 来覆盖它。在 Claude Code v2.1.227 及更高版本中，你所在的组织可以通过 managed settings（参见 Settings files）强制保持 tool search 开启。具体覆盖范围及该变量剥离的内容，参见「Disable pre-release capabilities」（/docs/en/llm-gateway-protocol#disable-pre-release-capabilities）。

Tool search 适用于所有已注册的工具，无论它们来自远程 MCP 服务器还是自定义 SDK MCP 服务器。当你使用 auto 时，SDK 会把所有 tool search 可以延迟加载的定义计入同一个合并阈值：每个来自任意服务器、且未被标记为 alwaysLoad 的 MCP 工具，加上按需加载的内置工具。像 Bash、Read、Edit 这些核心内置工具，SDK 总是会预先加载，不计入该阈值。

在 query() 的 env 选项中设置该值。在 TypeScript 中，env 会替换子进程的环境变量，因此需要展开 ...process.env 以保留继承的变量。在 Python 中，env 会合并到继承的环境变量之上。下面的示例连接到一个暴露了大量工具的远程 MCP 服务器，用通配符预先批准了其中所有工具，并使用 auto:5，使 tool search 在可延迟加载的定义达到上下文窗口的 5% 时被激活：

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

try {
  for await (const message of query({
    prompt: "Find and run the appropriate database query",
    options: {
      mcpServers: {
        "enterprise-tools": {
          // Connect to a remote MCP server
          type: "http",
          url: "https://tools.example.com/mcp"
        }
      },
      allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
      env: {
        ...process.env, // env replaces the subprocess environment, so keep inherited variables
        ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result
  console.log(`Session ended with an error: ${error}`);
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "enterprise-tools": {
                "type": "http",
                "url": "https://tools.example.com/mcp",
            }
        },
        allowed_tools=[
            "mcp__enterprise-tools__*"
        ],  # Wildcard pre-approves all tools from this server
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when deferrable definitions reach 5% of context
        },
    )

    try:
        async for message in query(
            prompt="Find and run the appropriate database query",
            options=options,
        ):
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)
    except Exception as error:
        # A single-shot query() raises after yielding an error result
        print(f"Session ended with an error: {error}")


asyncio.run(main())

运行这个示例时，把 https://tools.example.com/mcp 替换为你自己的 MCP 服务器地址。运行成功后，结果文本会打印到控制台。

因为这是一次性的 query() 调用，SDK 会在产出一个错误结果后抛出异常，所以示例把循环包在 try 块中。要了解某次运行为何失败，可以在循环内检查结果消息的 subtype 字段，例如 error_during_execution。关于结果消息的更多内容，参见「Handle the result」（/docs/en/agent-sdk/agent-loop#handle-the-result）。

优化工具发现

搜索机制会把查询与工具的名称、描述做匹配。像 search_slack_messages 这样的名字，比 query_slack 能覆盖更多类型的请求。描述里带有具体关键词（例如「Search Slack messages by keyword, channel, or date range」）也比笼统的描述（例如「Query Slack」）能匹配更多查询。

你还可以在 system prompt 中追加一段，列出可用的工具类别，让 agent 了解有哪些类型的工具可供搜索。可以在 TypeScript 中通过 systemPrompt 选项、在 Python 中通过 system_prompt 选项，使用 claude_code 预设（preset）配合 append，把你的文本追加到预设 prompt 之后，而不是替换它：

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "You can search for tools to interact with Slack, GitHub, and Jira."
  }
}

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "You can search for tools to interact with Slack, GitHub, and Jira.",
    }
)

关于 system prompt 的完整选项，参见「Modifying system prompts」（/docs/en/agent-sdk/modifying-system-prompts）。

限制

• 工具数量上限：工具目录中最多 10,000 个工具
• 搜索结果数：默认每次搜索最多返回 5 个最相关的工具
• 模型支持：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更新模型；当前完整列表参见 API 文档中的「model compatibility」(https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#model-compatibility)。在 Google Cloud 的 Agent Platform 上，同样适用这些最低模型要求。

相关文档

• 「Tool search in the API」(https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool):tool search 的完整 API 文档，包括自定义实现方式
• 「Connect MCP servers」（/docs/en/agent-sdk/mcp）：通过 MCP 服务器连接外部工具
• 「Custom tools」（/docs/en/agent-sdk/custom-tools）：通过 SDK MCP 服务器构建自定义工具
• 「TypeScript SDK reference」（/docs/en/agent-sdk/typescript）：完整 API 参考
• 「Python SDK reference」（/docs/en/agent-sdk/python）：完整 API 参考