tool-discovery

name	tool-discovery
description	当工具数量达到成百上千、模型面对平铺工具列表选择精度下降、需要让 Agent 主动发现并按需加载工具时使用。不适用于单个工具接口设计（见 tool-interface）或 MCP 互操作（见 tool-mcp-ecosystem）。

主动工具发现（Proactive Tool Discovery）

角色与读者

面向需要管理大规模工具库的 Agent 开发者。本 Skill 服务的目标：从"被动接受者"变为"主动发现者"——不把全部工具 schema 一次性注入上下文，而是让 Agent 在执行中意识到能力缺口时主动声明需求、系统按需注入。核心认识：把"工具选择"问题转化为"知识检索"问题（后者正是 LLM 擅长）。

核心原则（配正例/反例）

1. 主动声明缺口，系统按需注入

   • 传统做法一次性注入所有 schema，上千工具时上下文被"说明书"塞满，选择精度下降。检索式预筛按初始查询一次性匹配，无法预见多步骤跨领域工具链（"Debug the file" 牵出文件/代码/命令多工具）。
   • 正例：系统提示词只保留少数基础工具 + 一个"工具搜索工具"（discover_tools / Tool Search），Agent 用自然语言描述需求即可检索加载。
   • 效果：MCP-Zero 在约 2800 工具上比全量注入省 ~98% token；Anthropic 实验使 Opus 4 工具使用准确率从 49% 提升到 74%。

2. 层次化匹配：先定位服务器，再匹配工具

   • 工具按服务器分组（类似手机 App），匹配分两层——先按能力描述定位相关服务器，再在服务器内匹配具体工具，搜索空间从"数千工具"缩小为"数十服务器 × 每服务器数十工具"。
   • 候选相似度都低于阈值时明确返回"未找到"，让 Agent 改写需求、用基础工具手工实现、或创造新工具。

3. 动态加载与 KV Cache：新 schema 追加到轨迹末尾

   • 把新工具完整 schema 追加到上下文末尾（静态前缀保持稳定），此后固定在轨迹原位置作为普通历史消息继续命中缓存；状态栏只维护简短工具名列表。
   • 真正导致重算的只有两种情况：Prompt Cache TTL 过期，或修改/移除/重排已加载工具集。
   • "工具定义必须在上下文最前面"不再是铁律——代价是模型必须在后训练中学会理解散落在上下文各处的工具定义。

4. Skills：把工具发现变成"按需查阅"（更省心的思路）

   • 不需要"嵌入索引+语义匹配"基础设施。启动时只看到薄薄目录（每 skill 的 name + description，数百 token），真正需要时模型读取对应 sub-skill，顺引用再读脚本/子文档。
   • 更像人用参考资料（顺索引逐个查阅词条），靠通用文件阅读能力（grep、读文件）翻阅目录即可。

5. 模型原生工具 vs Skill 的友好度取舍

   • 模型原生工具对模型友好（JSON 规定输入输出格式，限制采样强制遵循，易解析）；Skill 对人类编写者友好（自然语言描述，无需编程，局部修改不牵一发动全身）。
   • Skill 对模型要求更高（生成合法命令行参数、特殊字符转义，转义规则跨平台不同）；参数结构复杂仍建议用模型原生工具，或 Skill 中要求把复杂结构化参数写 JSON 文件再命令行导入。

执行流程（SOP 检查清单）

1. 判断工具规模：<10 全量注入；数十~上百检索式预筛或 Skills 目录；上千主动发现。
2. 保留基础工具 + 一个工具搜索元工具；把工具名列表放状态栏（轻量）。
3. 新工具 schema 追加到轨迹末尾（不插回前缀），状态栏更新工具名。
4. 引导模型在能力缺口时主动调用 discover_tools（而非"字段数量超阈值"的规则代替模型决策）。
5. 对弱模型价值尤其显著（4B 模型 120+ 工具全量注入指令遵循能力退化，主动发现让小模型保持可用）。

禁止清单（写清合法例外）

• 禁止上千工具全量注入 system prompt（上下文塞满 + 选择精度下降）。例外：工具少时可全量。
• 禁止动态加载时把 schema 插回前缀（破坏缓存）。例外：追加到轨迹末尾，固定原位置继续命中。
• 禁止修改/移除/重排已加载工具集（缓存从变动点起失效）。例外：Prompt Cache TTL 过期整段重算。
• 禁止用"字段数量超阈值"这类规则代替模型决策（是否调用工具发现应由模型判断）。例外：明确的能力缺口信号可作辅助。
• 禁止参数结构复杂还用 Skill 而非模型原生工具。例外：Skill 中要求把复杂结构化参数写 JSON 文件再命令行导入。

参考资料

• 本书第 4.7 节《主动工具发现与基于 Skill 的渐进式披露》（模型原生发现、层次化匹配、动态加载与 KV Cache、Skills）。
• 笔记 04-工具.md 第 4.7 节。
• MCP-Zero 论文；OpenAI "Tool search" / Anthropic "Tool Search" / Codex CLI tool_search。