跳到主要内容

Tool Search

当一个会话挂载了大量 MCP server 或非核心 plugin 工具时,它们的 JSON schema 会在每一轮都占用相当大一部分上下文窗口——即使其中只有少数几个与用户实际提出的问题相关。

Tool Search 是 Kopi Agent 为解决这一问题提供的可选渐进式披露(progressive-disclosure)层。激活后,MCP 和 plugin 工具会在模型可见的 tools 数组中被替换为三个桥接工具(bridge tool),模型按需加载每个具体工具的 schema。

内置 Kopi Agent 工具永远不会被延迟加载

构成 Kopi Agent 核心能力集的工具(terminal、read_file、write_file、patch、search_files、todo、memory、browser_*、web_search、web_extract、clarify、execute_code、delegate_task、session_search,以及 _KOPI_CORE_TOOLS 的其余部分)始终直接加载。只有 MCP 工具和非核心 plugin 工具才会被延迟加载。

工作原理​

当 Tool Search 在某一轮被激活时,模型会看到三个新工具来替代被延迟的那些:

tool_search(query, limit?)     — search the deferred-tool catalog
tool_describe(name) — load the full schema for one tool
tool_call(name, arguments) — invoke a deferred tool

一次典型的交互如下:

Model: tool_search("create a github issue")
→ { matches: [{ name: "mcp_github_create_issue", ... }, ...] }
Model: tool_describe("mcp_github_create_issue")
→ { parameters: { type: "object", properties: { ... } } }
Model: tool_call("mcp_github_create_issue", { title: "...", body: "..." })
→ { ok: true, issue_number: 42 }

当模型调用 tool_call 时,Kopi Agent 会解包桥接层,并像模型直接调用底层工具一样精确地分发该工具。工具调用前的 hook、防护机制、审批提示以及工具调用后的 hook,全部针对真实工具名运行——而不是针对 tool_call。CLI 和 gateway 中的活动流也会解包,因此你看到的是底层工具,而不是桥接工具。

何时激活?​

默认情况下,Tool Search 以 auto 模式运行:只有当可延迟工具的 schema 会占用当前活动模型上下文窗口的至少 10% 时才会激活。低于该阈值时,tools 数组的组装是纯直通的,你无需承担任何开销。

每次构建 tools 数组时都会重新评估这一决策,因此:

  • 只挂载少量 MCP 工具且使用长上下文模型的会话永远不会激活 Tool Search。
  • 挂载了大量 MCP server(通常 15 个以上工具)的会话会开始激活它。
  • 在会话中途移除 MCP server 后,下一次组装时会正确地恢复为直接暴露。

配置​

tools:
tool_search:
enabled: auto # auto (default), on, or off
threshold_pct: 10 # percentage of context — only used in auto mode
search_default_limit: 5
max_search_limit: 20
键默认值含义
enabledautoauto 在超过阈值时激活;on 只要存在至少一个可延迟工具就始终激活;off 完全禁用。
threshold_pct10auto 模式启动的上下文长度百分比。取值范围 0–100。
search_default_limit5模型调用 tool_search 时未提供 limit 所返回的命中数量。
max_search_limit20模型通过 limit 可请求的硬上限。取值范围 1–50。

你也可以切换到旧版布尔形式:

tools:
tool_search: true # equivalent to {enabled: auto}

何时不应使用它​

Tool Search 用每轮固定的 token 成本(三个桥接工具的 schema,约 300 token)以及至少一次额外的往返(搜索 → 描述 → 调用)来换取被延迟 schema 的节省。当你工具很多但每轮只用少数几个时,它明显划算;当你工具总数很少时,它就是开销。

auto 的默认值会替你处理好这一点。如果你无条件地设置 enabled: on,在小型工具集上预期会有轻微的每轮开销。

无法消除的权衡​

这些权衡源于 prompt-cache 完整性不变式——它们是任何渐进式披露设计所固有的,并非本实现特有:

  • 冷门工具多一次往返。 模型首次需要某个被延迟的工具时,会多花一到两次模型调用来查找并加载其 schema。静态侧的 token 节省是真实的,但其中一部分会在运行时被偿还。
  • 被延迟的 schema 没有缓存收益。 已加载的 tool_describe 结果会进入对话历史(因此在后续轮次中确实会被缓存),但它永远无法受益于系统提示词的缓存前缀。
  • 依赖模型能力。 Tool Search 假设模型能够为它想要的工具写出合理的搜索查询。较小的模型在这方面表现较差;Anthropic 公布的数据(Opus 4 上有/无 tool search 对比为 49% → 74%)既显示了收益空间,也说明仍有约 26 个百分点的准确率差距源于检索失败。
  • 工具集变更会使缓存失效。 在会话中途添加或移除工具会改变桥接工具的描述(其中包含被延迟工具的数量)以及目录,因此 prompt cache 会失效。这与任何工具集变更的权衡相同。

实现细节​

  • 检索: 对分词后的工具名 + 描述 + 参数名执行 BM25。当 BM25 未返回任何正分命中时,回退到对工具名进行字面子串匹配,以抵御零 IDF 的退化情况(例如,在所有工具名都包含 "github" 的目录中搜索 "github")。
  • 目录跨轮次无状态。 每次组装都会从当前的 tool-defs 列表重建——不存在按会话键控的 Map。这避免了存储的目录与实时工具注册表失步这一类 bug。
  • 目录的作用域限定在会话的工具集内。 tool_search、tool_describe 和 tool_call 只能看到并调用该会话实际被授予的工具。被限制在某个工具集子集内的 subagent、kanban worker 或 gateway 会话,无法通过桥接层发现或调用该子集之外的工具——被延迟的目录是该会话自身已启用/禁用工具集中可延迟的那部分,而不是整个进程的注册表。
  • 没有 JS 沙箱。 Kopi Agent 使用更简单的"结构化工具"模式(search / describe / call 作为普通函数)。其他一些实现提供的 JS 沙箱"代码模式"是一个很大的攻击面,我们跳过了它。

参见​

  • tools/tool_search.py ——实现代码
  • tests/tools/test_tool_search.py ——回归测试套件
  • 原始实现 PR 中的 openclaw-tool-search-report PDF,其中包含影响本设计的研究内容