|

Gemini、Claude、GPT 都开始按需加载工具:三家 Tool Search 机制的 6 处关键不同

Gemini、Claude、GPT 都开始按需加载工具:三家 Tool Search 机制的 6 处关键不同

三家的 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 演示三条技术路线。最后的分析部分给出选型原则,并讨论跨模型网关在协议适配上要注意的问题。

gemini-claude-gpt-tool-search-comparison-image-0


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,把同一个工具目录在三家各跑一遍,确认事件结构能被你的解析层正确识别,再决定主力方案。

gemini-claude-gpt-tool-search-comparison-image-1

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

三家 Tool Search 机制集中对比

gemini-claude-gpt-tool-search-comparison-image-2

维度 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 注入。

这个场景只用来说明机制差异,不代表三家的实测成功率或延迟。

四条面向开发者的选择原则

  1. 工具库大而固定:优先看服务端检索能力。三家都能覆盖,但要注意 Gemini 每次请求都要重发完整工具数组,Claude 单请求延迟工具上限为 10,000 个。
  2. 需要显式控制搜索策略:Claude 公开的 Regex 和 BM25 是唯一明确披露算法的方案,适合想按命名规则精确命中的团队。Gemini 和 GPT 的服务端算法没有披露,不应推断它们与 Claude 相同。
  3. 工具库频繁变化或需要按用户权限过滤:重点看客户端动态注入。Gemini 和 GPT 的客户端模式都能引入新工具;Claude 的自定义搜索只能引用已声明的工具,需要在发请求前组装好候选集。
  4. 工具规模小: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 的上限。正如《论语·卫灵公》所言:“工欲善其事,必先利其器。”


参考资料

  1. Google Tool Retrieval 技术文档:服务端与客户端检索、限制、计费与算例
    • 链接: aistudio.google.com/docs/tool-retrieval
  2. Google 官方公告:Introducing Tool Retrieval in the Gemini API
    • 链接: blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval
  3. Anthropic Tool Search Tool 文档:Regex、BM25、tool_reference 与限制
    • 链接: platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
  4. Anthropic Advanced Tool Use 公告:Tool Search 发布与内部评测
    • 链接: anthropic.com/research/advanced-tool-use
  5. OpenAI Tool Search 文档:namespace、客户端检索与动态注入
    • 链接: developers.openai.com/api/docs/guides/tools-tool-search
  6. OpenAI GPT-5.4 公告:Tool Search 发布与 MCP Atlas 测试
    • 链接: openai.com/index/introducing-gpt-5-4

作者:APIYI 技术团队
技术交流:如需进一步探讨多模型 Agent 的工具调用适配,欢迎访问 API易 apiyi.com 联系我们,更多接入资料可查阅 docs.apiyi.com 文档中心

延伸阅读

类似文章