工具选择歧义消解：先把描述写清楚再谈路由

工具选择歧义这件事，很多团队是在工具从 5 个涨到 30 个之后才第一次撞上的。之前 Agent 表现尚可，之后开始出现一种很奇怪的症状：任务能跑完，返回 200，日志里没有异常，但调用的工具不是应该调的那个。模型不会说“我不知道用哪个”，它会挑一个听起来合理的，用另一套 schema 拼参数，工具老老实实执行，结果静静地错。

歧义从哪里来

最常被低估的一类歧义源头是描述重叠。设想两个工具，一个叫 send_notification，一个叫 push_alert。名字相近，描述都是“向用户发送提醒”。模型的选择依据只剩语气和先验概率，它本质上是在猜。而这种谜底可能落在描述文本里并未写出的实现差异上：一个走站内信，一个走移动端推送；一个支持重试，一个不保证到达。

Anthropic 的内部测试里提到，58 个工具定义大约消耗 55,000 个 Token。这不只是钱的问题。工具数量上去之后，模型在上下文中看到的是一大堆结构相似、边界模糊的候选，选择能力随之退化。Tian Pan 的记录里引用了 Berkeley Function Calling Leaderboard 的数据：跨多个领域的日历调度任务中，工具从 4 个扩展到 51 个时，准确率从 43% 降到 2%。这不是平缓的曲线，是断崖。

模型很少会说“我不知道该用哪个工具”，它会选一个看似合理的，然后返回一个格式合法、语义错误的结果。

先修描述，而不是先加路由

遇到选择错误，工程师的本能是引入检索层：向量化工具描述，对用户查询做相似度检索，只把 Top-k 喂给模型。这个方向没错，但顺序经常反了。检索只负责缩小候选集，它无法修复“候选之间本来就分不清”的问题。send_notification 和 push_alert 无论被谁排到前列，模型依旧只能赌。

Machine Learning Mastery 那篇工具设计文章提到一个关键点：好的工具定义要写清与其他工具的边界，而不只是告诉模型这个工具怎么用。缺了边界说明，模型会从名字去推断适用范围，规模一上去，这就是稳定的选错来源。

真正对检索有用的描述字段，和写给人类看的 API 文档不完全是同一套。实际做法通常要加这几项：

• 典型用例：什么情况下该调它，给一个具体场景而不是抽象职责。
• 反面示例：明确写清什么情况下应该改用哪个相邻工具。
• 前置与后置条件：调用前有什么必须成立，调用后环境会发生什么变化。
• 失败模式：入参越界、下游不可用、部分成功时分别返回什么。

Tian Pan 那篇文章引用的工具检索文档扩展研究发现，加入 when_to_use、tags、limitations 这类结构化字段带来的检索指标提升最大，甚至超过改进基础描述本身。这一点很有指导性：把“消歧信息”写成独立字段，而不是埋在长句里，模型与检索器都更容易吃到。

分层路由的取舍

如果描述已经足够区分，工具总数仍在四五十以上，就需要分层。可行结构大概是三层：意图分类先把请求引到一个类别，在类别内用稠密加稀疏混合检索收窄候选，最后按当前执行状态重排序。最终模型每轮看到的是 5 到 8 个工具，而不是 50 个。

混合检索在这件事上比纯向量明显更稳：API 文档里有大量精确术语，方法名、参数名、缩写，BM25 吃关键词比嵌入模型更准。用户说“重新安排会议”，和工具名 calendar_event_update 之间的余弦相似度可能并不高，纯向量会系统性地漏掉正确选项。这也是 Top-k 截断的隐患：正确工具被排到第 k+1 位，模型根本没有机会看见。

重排序需要看得见执行上下文。多步任务里第 2 步该用什么工具，往往取决于第 1 步的输出。只用原始查询做检索引擎，会持续漏掉执行中期才变得相关的工具。让重排器看到已经调了哪些工具、拿到什么结果，筛选质量会上一个台阶。

分层路由有两个代价要提前认。第一，意图分类的粗粒度选错了，后续层做得再好也救不回来，所以分类器的错误率必须单独评估，而不是混在端到端指标里。第二，路由链条拉长之后，失败定位变难。原本只有一个“模型选错工具”的故障点，现在要区分是分类错、检索错、重排错还是模型错。日志必须按层记录候选与得分，否则你连 debug 的入口都没有。

触发条件是数字，不是感觉

什么时候该加路由，可以给个粗略的门槛：15 个工具以内，静态塞进上下文即可，把精力放在描述质量上；15 到 40 个，单次语义检索配上混合打分；40 个以上，分层路由；跨多个 Agent、200 个工具以上，考虑工具与 Agent 共享嵌入空间的联合检索。需要提醒的是，这组数字来自对生产实践的归纳，不是严格实验结论，具体阈值依赖模型的工具调用能力和你的工具同质化程度。

检索之外的两种失败

工具选择只是整件事的一半。另一种失效模式是选对了工具但调错了：在有状态系统里，调用会改变后续调用的语义。删除一条记录的 Agent 不怎么理解下一次 SELECT 的结果会变；发邮件不重试还好，重试会重复发。这层靠检索修不了，只能靠执行前规划，让模型先排出调用序列，标出依赖关系与不可逆操作。

Tian Pan 提到 NESTFUL 基准的一个数字：即便是 GPT-4o，处理依赖式 API 调用的完整序列时，准确率也只有 28%。这个数字是个提醒，别把所有的功能问题都记在检索层账上。

怎么知道歧义是不是真在降低

工具选择错误的隐蔽性来自它的响应总是合法。因此评估要下沉到调用级别，而不是只看最终回答对不对。值得跟踪的几个量：每个意图类别的选择准确率、Recall@k（正确工具在不在前 k）、工具调用重试率、每轮平均工具数。重试率高，通常说明上游选择有问题；每轮平均工具数随时间上升，说明检索没在有效地收窄候选。

实践中容易被跳过的一步是先做评估再做路由。很多团队在下意识里把“模型不够聪明”当成结论，于是换更大的模型，问题短期缓解，工具涨到 80 个再回来。而把选错当成检索与描述缺陷的团队，至少能在工具数量扩张时不至于崩掉。