三家的 Tool Search 解决的是同一个问题,但实现路线差别很大。 三家都让模型在开始时只看到工具的简要线索,需要调用时再加载完整参数 Schema。区别主要在三处:Gemini 有服务端和客户端两种检索模式,客户端检索可以引入新工具;Claude 公开了 Regex 和 BM25 两种服务端搜索方式,并通过 tool_reference 在已声明的工具集合内做发现;GPT 用 namespace 给工具分组,客户端模式可以通过 tool_search_output 动态注入新工具。选型时要看工具库是否固定、是否变化频繁,以及团队现有的 API 架构。
您读完此文能了解到什么?
- 三家 Tool Search 分别属于哪个 API、用什么字段启用。
- 模型初始上下文里保留的内容有什么不同,以及
short_description、tool_reference、namespace各起什么作用。 - 工具检索和实际函数调用的事件链怎样组成,适配时容易在哪里出错。
- 哪一家支持在对话中加入初始请求里没有的新工具。
- 面对订单与库存这类企业 Agent,如何根据工具库结构做选择。
索引:正文先交代三家发布时间和共同思路,再分别拆解 Gemini、Claude、GPT 的检索机制与原生字段,然后用一张总表对照八个维度,并以同一个订单与库存 Agent 演示三条技术路线。最后的分析部分给出选型原则,并讨论跨模型网关在协议适配上要注意的问题。

Tool Search 相关概念 To Know
| 概念 | 简要解释 |
|---|---|
| 工具目录 | 供检索的业务工具集合,包含名称、描述、参数定义和权限信息 |
| Tool Search | 按当前任务检索所需工具,并按需导入其完整定义的能力 |
defer_loading |
三家都采用的字段,标记工具延迟加载完整定义 |
| Regex | 用正则表达式匹配工具名称、描述或参数线索 |
| BM25 | 按查询词与文本的相关性给搜索结果排序的经典算法 |
tool_reference |
Claude 用来引用已声明工具的内容块,随后由 API 展开为完整定义 |
namespace |
OpenAI Responses API 中把相关函数按业务能力归组的声明 |
| 动态工具注入 | 应用把初始请求中未声明的工具定义交给模型继续使用 |
tool_search_output |
OpenAI 客户端检索时回传匹配工具声明的响应项 |
| 远程 MCP | 通过 Model Context Protocol 提供可发现、可执行工具的远端服务 |
| 缓存前缀 | 多次模型调用之间保持一致、可以复用缓存的输入开头部分 |
Tool Search 影响速览
- Agent 开发者:工具多了以后不必再把所有 Schema 一次塞进上下文,但三家的请求体和返回事件都不同,跨模型 Agent 需要分别实现解析逻辑。
- 企业平台与工具目录维护者:工具命名、简短描述和分组方式开始直接影响检索效果,工具目录本身成了需要设计的资产。
- 成本与运维负责人:Tool Search 不一定省钱。Google 官方算例同时给出了节省和增加 Token 的两种情形,是否启用要以实测账单为准。
客观事实:三家 Tool Search 的发布脉络与机制
为什么 Gemini、Claude、GPT 都提供 Tool Search
当一个 Agent 同时接入 CRM、订单、库存、物流、工单和多个 MCP 服务器时,工具声明本身就会占掉大量上下文。Google 文档提到,几十个函数声明就可能占用数万个 Token。Anthropic 举过一个例子:GitHub、Slack、Sentry、Grafana、Splunk 五个 MCP 服务器共 58 个工具,仅工具定义就约 55,000 Tokens。
三家的发布时间线如下:Anthropic 在 2025 年 11 月 24 日推出 Tool Search Tool;OpenAI 在 2026 年 3 月 5 日随 GPT-5.4 推出 API Tool Search;Google 在 2026 年 11 月 19 日以预览版形式推出 Gemini API 的 Tool Retrieval。三家的基本思路一致:模型先知道有哪些能力,真正要用时再读取完整参数定义。
三家各自公布过性能数据,但测试条件完全不同,不能拿来排名。Anthropic 的例子中,初始上下文从约 77,000 Tokens 降到约 8,700 Tokens,内部 MCP 评估里 Claude Opus 4 的工具选择准确率从 49% 提升到 74%。OpenAI 在 MCP Atlas 的 250 项任务、36 个 MCP 服务器上测得总 Token 降低 47%,准确率保持不变。Google 目前只给出假设性算例:200 个工具时约减少 85.6%,10 个工具配合长上下文时反而增加约 36.5%。
Gemini Tool Search:服务端与客户端两种检索模式
Gemini 的 Tool Retrieval 依托 Interactions API,要求使用 v1beta,旧的 generateContent 不支持。服务端模式的启用方式是在 tools 中加入 {"type": "tool_search"},再给低频的 function 或 mcp_server 设置 defer_loading: true。模型起初只看到延迟工具的名称和 short_description。Google 早期测试显示,每个工具条目平均约 26 Tokens。没有配置简短描述时,会用完整 description 的第一句代替。
有一点容易误解:服务端模式下,开发者仍要提交完整工具定义。即使使用 previous_interaction_id,每次请求也要重新发送完整的 tools 数组。延迟加载只是不让完整 Schema 提前进入模型上下文。此外,已加载的 Schema 在当前会话中无法卸载;单个请求最多声明一个 tool_search;服务端和客户端检索不能在同一请求中混用。
| 维度 | 服务端检索 | 客户端检索 |
|---|---|---|
execution |
server(默认) |
client |
| 检索器 | Gemini API 负责 | 开发者自建 |
| 需提前声明工具库 | 需要 | 不需要 |
defer_loading |
适用 | 不适用 |
| 额外往返 | 无额外客户端往返 | 每次搜索多一次往返 |
| 典型场景 | 大型、相对固定的工具集合 | 私有 Tool Registry、多租户、动态工具 |
客户端模式下,模型调用开发者定义的搜索函数(如 search_tool_registry),应用在 function_result.result 中返回匹配的完整工具声明对象。这种方式可以在对话过程中引入原始请求没有声明过的工具,比如用户在会话中临时连接了一个新的 SaaS 服务。
Claude Tool Search:Regex、BM25 与 tool_reference
Claude 的 Tool Search Tool 属于 Messages API,服务端提供两种搜索工具类型:tool_search_tool_regex_20251119 由模型生成正则表达式,适合命名规律强的工具库;tool_search_tool_bm25_20251119 由模型生成自然语言查询,适合按能力描述来发现工具。两种方式都会检索工具名称、描述、参数名称和参数描述。Claude 的参数字段是 input_schema,这一点和另外两家的 parameters 不同。
一次典型检索的事件链是:Claude 先发起 server_tool_use 调用内建搜索工具,API 返回 tool_search_tool_result,结果中包含 tool_reference,再由 API 展开为完整定义,最后模型产生业务层面的 tool_use。Anthropic 特别说明,内建搜索工具的 srvtoolu_... 标识不需要开发者回传 tool_result,应用只需执行实际的业务 tool_use。
| Claude Tool Search 规则 | 官方规定 |
|---|---|
| 单请求延迟工具上限 | 10,000 个 |
| 单次搜索默认返回 | 最多 5 个,可通过 limit 调整 |
| Regex 查询长度 | 最多 200 字符 |
| BM25 查询长度 | 最多 500 字符 |
| 不支持的模型 | Claude Opus 4.1 及更早模型 |
| 缓存约束 | defer_loading: true 的工具不能设置 cache_control |
开发者也可以用 embedding 等自有算法实现自定义搜索,但返回的仍然是 tool_reference,被引用的工具必须已经在顶层 tools 中声明。所以 Claude 的设计更接近“从预先声明的工具库里找出需要的工具”。MCP 方面,Claude 通过 MCP Connector 的 mcp_toolset 配置延迟策略,可以在 default_config 中统一设置,也可以在 configs 中逐个工具设置。
GPT Tool Search:Namespace 与动态工具注入
OpenAI 的 Tool Search 位于 Responses API,由 GPT-5.4 及更新的兼容模型支持,同样通过 tool_search 和 defer_loading 启用。它的特色是 namespace:开发者可以把相关函数按 crm、billing 等业务域分组,模型先根据命名空间的名称和描述判断哪类能力相关,需要时再展开组内的延迟函数。这样工具分组成了 API 层面的结构,而不只是命名约定。
服务端模式的事件链是 tool_search_call → tool_search_output → function_call → 应用返回 function_call_output。客户端模式下,应用收到 tool_search_call 后自行查询工具目录,再用相同的 call_id 返回 tool_search_output,其 tools 字段包含匹配的完整工具声明,模型在下一轮才调用这些函数。官方文档支持在这里返回原始请求未声明过的工具,同时要求开发者严格校验动态 Schema,只暴露可信的工具定义。
在缓存方面,OpenAI 会把新发现的工具定义追加到上下文后部,以减少对已有缓存前缀的影响。MCP 方面需要注意:Responses API 的 Tool Search 支持 MCP 工具按需发现,Agents API 则在模型和提供方支持时由运行时自动接入工具发现。官方明确提醒,两套配置不能直接互相套用。
下面是一个示意性的 Responses API 请求,演示延迟加载的基本结构。字段以 OpenAI 官方文档为准:
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # API易 OpenAI 兼容入口
)
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "inventory_get_stock",
"description": "Inventory: check stock level by SKU.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"sku": {"type": "string"}},
"required": ["sku"]
}
}
]
resp = client.responses.create(
model="gpt-5.4",
input="订单 A-1042 还没发货,帮我查一下 SKU-88 的库存。",
tools=tools
)
for item in resp.output:
print(item.type) # 预期可见 tool_search_call / function_call 等事件
查看客户端检索与动态注入的示意代码
import requests
BASE_URL = "https://api.apiyi.com/v1" # 经 API易 转发 Responses API 请求
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
def search_registry(query: str) -> list:
"""在企业私有工具目录中检索,并按用户权限过滤(示意)"""
return [{
"type": "function",
"name": "warehouse_schedule_shipment",
"description": "Warehouse: schedule a new shipment date.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
"date": {"type": "string"}
},
"required": ["order_id", "date"]
}
}]
def handle(output_items: list) -> list:
follow_ups = []
for item in output_items:
if item["type"] == "tool_search_call":
query = item.get("arguments", {}).get("query", "")
follow_ups.append({
"type": "tool_search_output",
"call_id": item["call_id"], # 与检索调用使用相同 call_id
"tools": search_registry(query) # 可包含初始请求未声明的工具
})
return follow_ups
# 注意:动态返回的 Schema 务必先做校验,只暴露可信工具
🚀 快速验证建议:在接入真实业务前,可以先用 API易 apiyi.com 的统一 Key 分别调用 GPT、Claude、Gemini,把同一个工具目录在三家各跑一遍,确认事件结构能被你的解析层正确识别,再决定主力方案。

上图中的事件名称均为各家原生字段。需要逐家实测事件流的读者,可以通过 API易 apiyi.com 用同一套测试脚本切换模型来对照。
三家 Tool Search 机制集中对比

| 维度 | Gemini | Claude | GPT |
|---|---|---|---|
| 所属 API | Interactions API(v1beta) |
Messages API | Responses API |
| 检索方式 | 服务端(算法未披露)/ 客户端 | Regex / BM25 / 自定义搜索 | 服务端 / 客户端 |
| 初始上下文保留 | 名称 + short_description |
搜索工具 + 非延迟工具 | 延迟工具或 namespace 摘要 |
| 工具组织 | 命名约定 + 简短描述 | 名称、描述、参数均可被检索 | namespace 分组 |
| 参数字段 | parameters |
input_schema |
parameters |
| 客户端检索 | 支持 | 自定义搜索返回 tool_reference |
支持(tool_search_output) |
| 动态加入新工具 | 客户端模式支持 | 引用的工具须已在顶层声明 | 客户端模式支持,需校验 Schema |
| MCP 集成 | mcp_server + defer_loading |
mcp_toolset 的 default_config / configs |
Responses 与 Agents 规则不同 |
| 缓存及计费 | 无独立功能费;关注 total_tool_use_tokens |
不单独收费;延迟工具不可设 cache_control |
新工具追加到后部以保护缓存前缀 |
💡 选择建议:上表只对比可核验的接口规则。实际效果取决于你的工具库和对话长度,建议借助 API易 apiyi.com 的多模型统一入口做小样本 A/B 测试,再结合各家账单字段核算成本。
分析判断:Tool Search 选型的适配条件
用订单与库存 Agent 看三条技术路线
设想这样一个业务需求:用户查询订单状态,发现商品还没发货,接着查询库存,再判断能否安排新的发货日期。系统里有 CRM、订单、库存、仓库调度、物流、退款、账单、通知、审批九类工具,每类又有多个函数。
- Gemini 路线:把常用的订单查询直接加载,库存、仓库调度等长尾工具设为延迟加载,并写好
short_description,由服务端检索挑出get_inventory的 Schema。如果仓库调度工具按租户动态开通,就改用客户端检索,从私有 Registry 中返回。 - Claude 路线:如果工具命名规整(如
inventory_*、warehouse_*),Regex 能精确命中;如果用户说的是“看看还能不能补货”这类口语,BM25 更合适。最终由tool_reference展开为可调用的tool_use。 - GPT 路线:按
crm、inventory、logistics建立namespace,模型先判断涉及库存和物流两个域,再展开组内的函数。临时接入的新物流商,可以通过客户端tool_search_output注入。
这个场景只用来说明机制差异,不代表三家的实测成功率或延迟。
四条面向开发者的选择原则
- 工具库大而固定:优先看服务端检索能力。三家都能覆盖,但要注意 Gemini 每次请求都要重发完整工具数组,Claude 单请求延迟工具上限为 10,000 个。
- 需要显式控制搜索策略:Claude 公开的 Regex 和 BM25 是唯一明确披露算法的方案,适合想按命名规则精确命中的团队。Gemini 和 GPT 的服务端算法没有披露,不应推断它们与 Claude 相同。
- 工具库频繁变化或需要按用户权限过滤:重点看客户端动态注入。Gemini 和 GPT 的客户端模式都能引入新工具;Claude 的自定义搜索只能引用已声明的工具,需要在发请求前组装好候选集。
- 工具规模小:Google 的算例显示,10 个工具配合 30,000 Tokens 长上下文时,Token 用量反而增加约 36.5%。Google 建议少于约 20 个稳定工具时继续静态加载,这一点对另外两家也有参考意义,但仍需各自实测。
跨模型网关的协议适配问题
做跨模型 Agent 的团队最容易踩的坑,是把“能调用这个模型”等同于“这个模型的 Tool Search 能用”。可以把能力拆成四层:模型访问、协议端点(Interactions / Messages / Responses)、工具声明字段(tool_search、defer_loading、namespace、MCP 配置)、执行与状态管理(检索事件、函数结果、signature、会话历史)。模型接入成功只能说明第一层没问题。
尤其要注意 Gemini 的一条规则:在 store=false 的无状态会话中,tool_search_call、tool_search_result 及其 signature 都不能修改或删除,否则会返回 HTTP 400。这意味着网关不能随意压缩或重写历史消息。把三家抽象成统一的 Tool Search 接口,需要在 Agent 框架层面维护一张事件映射表,不能指望改个 Base URL 就让同一份请求体通用。
🎯 技术建议:通过 API易 apiyi.com 这类聚合平台接入多家模型时,建议先用小流量确认目标端点和
tool_search、defer_loading、namespace等字段是否被完整透传,再把 Tool Search 纳入生产链路。
值得持续关注的变量
Gemini Tool Retrieval 仍是预览版,正式发布前接口可能调整。它在真实生产环境中的平均节省比例、延迟和准确率,截至 2026 年 11 月 20 日都还没有可核验的独立测试。可以预期的一个方向是:三家都在把“工具目录治理”交给开发者,命名、简短描述、分组和权限会越来越像检索系统的索引工程。上线前,建议按初始输入 Token、工具使用 Token、正确工具选择率、无匹配检索率和平均搜索次数建立对照实验,用 API易 apiyi.com 等多模型环境在相同任务集上横向验证,避免被单一厂商的宣传数字带偏。
工具多了,并不等于 Agent 更聪明;能否在需要时准确找到合适的工具,才决定 Agent 的上限。正如《论语·卫灵公》所言:“工欲善其事,必先利其器。”
参考资料
- Google Tool Retrieval 技术文档:服务端与客户端检索、限制、计费与算例
- 链接:
aistudio.google.com/docs/tool-retrieval
- 链接:
- Google 官方公告:Introducing Tool Retrieval in the Gemini API
- 链接:
blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval
- 链接:
- Anthropic Tool Search Tool 文档:Regex、BM25、tool_reference 与限制
- 链接:
platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
- 链接:
- Anthropic Advanced Tool Use 公告:Tool Search 发布与内部评测
- 链接:
anthropic.com/research/advanced-tool-use
- 链接:
- OpenAI Tool Search 文档:namespace、客户端检索与动态注入
- 链接:
developers.openai.com/api/docs/guides/tools-tool-search
- 链接:
- OpenAI GPT-5.4 公告:Tool Search 发布与 MCP Atlas 测试
- 链接:
openai.com/index/introducing-gpt-5-4
- 链接:
作者:APIYI 技术团队
技术交流:如需进一步探讨多模型 Agent 的工具调用适配,欢迎访问 API易 apiyi.com 联系我们,更多接入资料可查阅 docs.apiyi.com 文档中心
