给 Agent 接入几个工具时，把工具说明全部交给模型，通常容易理解和实现。但工具增长到几十、几百个以后，系统可能出现新的问题：说明占据大量上下文、相似接口难以区分、模型选中了“名字很像但用途不对”的工具。
本文用智能 OnCall 助手的例子，讲清工具检索 Tool Retrieval 的工作方式、工具目录如何设计、候选工具怎样筛选，以及如何验证它是否真的改善了任务表现。
一、工具越来越多，为什么 Agent 反而可能不好用了？
想象你让一名维修师傅拧紧一颗螺丝。
桌上只有三把工具时，他很容易找到螺丝刀。如果把整个仓库的几百件工具连同说明书一起搬过来，他先得判断哪些东西和这次维修有关。
Agent 也会遇到类似的问题。
假设你的 OnCall 助手已经接入日志、监控、发布、工单、知识库等系统，现在用户问：
帮我查一下，payment-api 今天下午为什么突然变慢了，只分析，不做变更。
候选工具里可能同时存在：
| 工具 | 实际用途 |
|---|---|
monitor.query_metrics | 查询服务运行指标 |
logs.search_application | 查询应用日志 |
audit.search_events | 查询账号与权限审计事件 |
deploy.list_releases | 查询发布记录 |
deploy.rollback_release | 回滚已经发布的版本 |
tickets.search_history | 查询历史工单 |
这些工具有的都叫“查询”，有的都与服务故障有关，但它们并不能互相替代。
当目录变大，模型需要在更多相似选项之间做选择。与此同时，工具定义还会占用上下文和处理预算。
具体影响有多大，取决于模型、工具说明与任务，并不是工具数量一增加，准确率就必然下降。
因此，工程上值得考虑一个问题：
能不能先把这次可能用到的工具找出来，再让 Agent 阅读详细说明并调用？
这就是工具检索的基本思路。
二、Tool Retrieval 到底检索的是什么？
Tool Retrieval 可以理解为：根据当前任务，从工具目录中查找相关工具，形成一个较小的候选集合。
它检索的主要是工具名称、用途、适用条件、参数说明等元信息，不是已经执行出来的业务结果。
| 能力 | 找的是什么？ | 产出是什么？ |
|---|---|---|
| 文档检索 | 能回答问题的资料 | 文档片段、证据 |
| 工具检索 | 能完成某种操作的工具 | 工具标识及相关定义 |
| 工具调用 | 按参数执行具体操作 | 日志、订单、查询结果等 |
例如，工具检索发现logs.search_application适合查应用日志。
这一步并没有查询 payment-api 的任何日志。
后面还需要加载工具定义，填写服务、时间范围等参数，再真正调用。
可以把它记成：
先找到会干这件事的工具，再告诉它具体干什么。
Anthropic 官方介绍过按需发现、加载工具的机制，用于减少大量工具定义同时进入模型上下文的问题。这是工具检索的一种产品实现，并不意味着所有系统都要使用相同接口。
三、完整流程：从几百个工具里找到这次需要的几个
下面给出一套示例设计。假设用户已经明确了服务、生产环境和故障时间段。
第一步：确定当前阶段需要什么能力
“服务变慢”是用户的问题，检索器需要的则是更具体的能力描述。
可以先整理为：
查询目标服务的延迟、错误率和资源指标。
查询对应时间窗口的应用错误日志。
查询故障前后的发布记录。
当前任务仅允许分析，不执行生产变更。
这里无需一次性规划出所有后续步骤。
先找能推进当前阶段的工具就够了，得到新证据后还可以继续检索。
第二步：先过滤，再匹配相关性
相关性高，不代表工具对当前用户可用。
在这个示例系统里，可以先按身份权限、所属租户、运行环境、启用状态和任务允许的操作范围，过滤工具目录，再进行相关性匹配。
由于用户明确要求“只分析”，当前候选集合可以排除回滚、重启和修改配置等变更工具。
执行端仍需要独立校验权限。
候选过滤能够减少选错机会，但不能代替最终授权检查。
第三步：检索并比较候选
检索不一定必须使用向量数据库。
| 方式 | 适合的情况 | 可能遇到的问题 |
|---|---|---|
| 分类目录或规则路由 | 业务领域清晰、工具较少 | 边界任务可能分错类 |
| 关键词检索 | 用户用语与工具术语比较接近 | 可能漏掉同义表达 |
| 语义检索 | “卡顿”与“延迟指标”等表达不一致 | 容易召回语义接近但能力不同的工具 |
| 混合检索与重排 | 既有精确名称，又有自然语言描述 | 需要额外维护与评测 |
可以先得到若干候选，再检查它们到底能返回什么、需要什么输入、是否适合当前任务。
例如，“权限审计日志”和“应用运行日志”都包含“日志”，但排查接口超时通常更需要后者。
不能只按名字里有没有关键词来判断。
第四步：加载完整定义，再生成调用参数
工具摘要适合帮系统找工具，完整定义才用于正确调用。
完整定义中可能包含：
参数名称、类型和必填条件。
时间单位、时区、分页等约定。
服务标识的格式。
输出结构和错误语义。
如果只有一句“查询日志”，模型可能猜出app_name这个参数，但真实接口要求的是service_id。
检索摘要负责找到工具，完整定义负责告诉 Agent 怎么使用它。
第五步：根据结果决定是否再找工具
假设日志表明超时主要发生在数据库请求阶段，下一步可能需要查询数据库连接池指标。
此时重新检索相关工具即可，不必在任务开始时就把所有数据库工具装进上下文。
这种设计让候选工具随任务进展变化：
当前需要什么能力，就补充什么能力。
四、工具目录怎么写，才能让工具更容易被选对？
给工具写说明，不能只写一句“这是一个查询接口”。
它更像给仓库货架贴标签：除了名称，还要说明适合拿它来做什么、不能拿它来做什么。
下面是一张示例工具卡片：
| 字段 | 示例内容 |
|---|---|
| 工具名称 | logs.search_application |
| 用途 | 查询指定服务和时间范围内的应用运行日志 |
| 适用场景 | 排查报错、超时、异常堆栈 |
| 能力边界 | 不查询账号操作审计，不修改线上配置 |
| 必要输入 | 服务 ID、开始时间、结束时间 |
| 输出 | 日志时间、级别、内容和分页信息 |
| 操作属性 | 只读，但返回内容可能包含敏感字段 |
| 环境与权限 | 支持的环境及所需权限 |
| 定义版本 | 与注册中心中的实际接口版本对应 |
Anthropic 在工具设计文章中讨论了工具命名、描述、命名空间与评测的重要性。
但这里也有个容易忽略的细节：
工具卡片中的“只读”或“安全”字样，不应成为唯一的执行依据。
这些描述帮助选择，实际能力和权限仍应由可信注册信息及执行服务约束。
否则，一个描述写得非常动听、实际能力却不匹配的工具，就像包装精美但标签贴错的零件，反而更容易被拿错。
五、是不是每次检索 Top-5 就够了？
没有一个对所有任务都合适的固定数字。
只查一个订单，候选可能很少；排查跨系统故障，可能需要多个能力协作。
Top-K 里的 K 可以理解成“先拿出多少个候选”，不等于“必须调用多少个工具”。
| 候选集合 | 好处 | 代价 |
|---|---|---|
| 较小 | 工具说明少，干扰较少 | 可能漏掉必要工具 |
| 较大 | 更容易覆盖所需能力 | 选择负担和上下文开销增加 |
| 按阶段调整 | 与当前任务进展更贴近 | 需要管理追加检索与预算 |
在这个 OnCall 示例里，可以先提供日志和指标工具；出现发布相关线索后，再引入发布记录查询。
如果没有找到合适工具，也不必勉强从低相关候选里挑一个。
系统可以改写检索词、扩大授权范围内的搜索类别、澄清需求，或明确说明暂时没有对应能力。
“没有合适工具”应是一个可以正常表达的结果。
六、怎么知道问题出在“没找到”，还是“选错了”？
把任务最终失败都归为“模型不够聪明”，会让优化失去方向。
可以把失败拆开看：
| 失败位置 | 例子 | 应优先检查什么 |
|---|---|---|
| 检索阶段 | 应用日志工具根本没进入候选 | 工具描述、检索词、过滤条件 |
| 选择阶段 | 候选中有正确工具，却选了审计日志 | 能力差异是否清楚、候选是否混杂 |
| 参数阶段 | 工具选对，但时间窗口填错 | 参数定义与任务信息 |
| 执行阶段 | 请求正确，但服务不可用 | 工具服务及运行环境 |
| 解释阶段 | 工具结果正确，结论却不受证据支持 | 结果理解与回答生成 |
工具检索主要改善前面的发现与选择环节，不能保证后面的参数、执行和解释自动正确。
一个能手算的评测例子
假设测试集中有 100 个单工具任务，每道题标注一个目标工具；正确工具进入前五个候选的有 92 道。
那么，这个简单设定下的 Recall@5 为 92%。
这只能说明“正确工具有没有出现在候选中”，并不表示 92% 的任务最终做成了。
对于需要日志、指标和发布记录共同完成的任务，还可以检查“必要能力是否全部覆盖”。
如果同一能力存在多个等价工具，也应认可有效替代方案，而不是把唯一工具 ID 当成唯一答案。
本文的数字用于说明指标含义，不是实际实验结果。
七、它一定能省钱、提速吗？
不一定。
按需加载可能减少工具定义带来的上下文开销，但工具检索本身也可能增加搜索、重排或模型交互的时间。
可以把总账拆成：
工具发现开销 + 模型决策开销 + 业务工具执行开销。
如果原本只有四个短小、清晰的工具，额外引入复杂检索流程，可能得不偿失。
此外，“工具定义没有全部进入模型上下文”，也不一定意味着“API 请求不再提交完整工具目录”。
例如，Claude 官方工具搜索文档区分了定义在请求中的提供方式与延迟进入上下文的行为。
因此，比较方案时应同时记录候选覆盖、选工具正确率、端到端任务成功率、总延迟和实际费用。
不能仅凭候选数量变少，就宣称整体性能提高。
八、面试精简总结：一分钟怎么回答？
当 Agent 接入大量工具时，我会考虑工具检索：先根据当前任务所需能力，从工具目录里筛出相关候选，再加载完整定义并生成调用参数。工具较少时可以直接提供，目录较大时再按任务阶段按需发现。
工具目录要写清用途、适用条件、能力边界与参数要求。检索可以使用规则、关键词、语义匹配或组合方案，并结合身份、环境和任务范围过滤。检索到工具并不等于获得调用权限，执行端还要独立校验。
评测时我会区分候选召回、工具选择、参数正确与最终任务成功，避免把所有问题归因于模型。同时比较检索新增开销和上下文节省，验证它是否真正改善了整体效果。
一句话记忆：工具检索像查仓库目录，先找到合适的工具，再按完整说明使用。
