工具太多，模型反而选错
给智能体接工具时，常见想法是"工具越多能力越强" ✗。
实际是：工具清单越长，选择与参数填充的错误率越高 ✔（见工具设计那篇 ✔）。
把工具清单做成一份"能力目录" ✔：分层、可检索、带边界说明 ✔。
一、目录要有的字段
name（直白的名字 ✔）
what（一句话说明用途 ✔）
when（什么时候用 ✔）
when_not（什么时候不要用 ✔）
args（参数与约束 ✔）
cost（耗时/费用量级 ✔）
side_effects（是否有写操作 ✔）
when_not 与 side_effects 最常被省略 ✗，却最能减少误用 ✔。
二、按"能力"分层，而不是按"接口"罗列
- 第一层：能力类别（查询 / 计算 / 写入 / 通知 ✔）；
- 第二层：具体工具 ✔；
- 第三层：参数细节（按需展开 ✔）。
好处：模型先选类别（错得少 ✔），再看类别下的少量工具（候选集小 ✔）。
三、按当前任务动态给候选
不要把全部工具都塞进提示词 ✗。做法：
- 用规则先筛（按用户意图/场景 ✔）；
- 或用检索选候选（把"工具描述"当作文档检索 ✔ —— 见检索那几篇 ✔）；
- 只给 Top 5~10 个工具 ✔，并在提示词里说明"只能用以下工具" ✔。
要点：候选集要可解释 ✗ ✔（为什么给这几个 ✔ —— 便于归因与调试 ✔）。
四、工具说明要写"像给人看的文档"
- 名字直白（
search_orders✔ 而不是qo_v2✗）； - 说明里写边界与常见陷阱（"只返回最近 90 天" ✔）；
- 参数要可枚举的给枚举 ✔（不要自由文本 ✔）；
- 返回值要给人看（见工具返回值那篇 ✔）。
五、该观测什么
- 工具选择准确率（选对工具的比例 ✔ —— 用评测集测 ✔）；
- 参数填充错误率（按工具分组 ✔ —— 错误率高的工具通常说明书写不清 ✔）；
- 候选集命中率（正确工具是否在候选里 ✔ —— 不在就是筛得不对 ✔）；
- 工具数量与错误率的关系（通常正相关 ✔ —— 用来推动精简 ✔）。
一条判据
给模型10 个工具 vs 50 个工具 ✔，选择准确率差多少 ✔？
如果差很多，说明目录没做分层与筛选 ✗（加工具只会更糟 ✔）。