Tool Search
当一个会话挂载了大量 MCP server 或非核心 plugin 工具时,它们的 JSON schema 会在每一轮都占用相当大一部分上下文窗口——即使其中只有少数几个与用户实际提出的问题相关。
Tool Search 是 Kopi Agent 为解决这一问题提供的可选渐进式披露(progressive-disclosure)层。激活后,MCP 和 plugin 工具会在模型可见的 tools 数组中被替换为三个桥接工具(bridge tool),模型按需加载每个具体工具的 schema。
构成 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
| 键 | 默认值 | 含义 |
|---|---|---|
enabled | auto | auto 在超过阈值时激活;on 只要存在至少一个可延迟工具就始终激活;off 完全禁用。 |
threshold_pct | 10 | auto 模式启动的上下文长度百分比。取值范围 0–100。 |
search_default_limit | 5 | 模型调用 tool_search 时未提供 limit 所返回的命中数量。 |
max_search_limit | 20 | 模型通过 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-reportPDF,其中包含影响本设计的研究内容