把工具清单做成能力目录：模型怎么知道有什么工具

工具清单越长，选择与参数填充越容易错。本文给出能力目录的八个字段（重点 when_not 与 side_effects）、分层组织方式、按任务动态给候选的做法、说明的写法与该观测的四个指标。

工具太多，模型反而选错

给智能体接工具时，常见想法是"工具越多能力越强" ✗。

实际是：**工具清单越长，选择与参数填充的错误率越高** ✔（见工具设计那篇 ✔）。

**把工具清单做成一份"能力目录"** ✔：分层、可检索、带边界说明 ✔。

一、目录要有的字段

```

name（直白的名字 ✔）

what（一句话说明用途 ✔）

when（什么时候用 ✔）

when_not（什么时候不要用 ✔）

args（参数与约束 ✔）

cost（耗时/费用量级 ✔）

side_effects（是否有写操作 ✔）

```

**`when_not` 与 `side_effects` 最常被省略** ✗，却最能减少误用 ✔。

二、按"能力"分层，而不是按"接口"罗列

第一层：**能力类别**（查询 / 计算 / 写入 / 通知 ✔）；

第二层：具体工具 ✔；

第三层：参数细节（按需展开 ✔）。

**好处**：模型先选类别（错得少 ✔），再看类别下的少量工具（候选集小 ✔）。

三、按当前任务动态给候选

不要把全部工具都塞进提示词 ✗。做法：

1. 用**规则**先筛（按用户意图/场景 ✔）；

2. 或用**检索**选候选（把"工具描述"当作文档检索 ✔ —— 见检索那几篇 ✔）；

3. 只给 Top 5~10 个工具 ✔，并在提示词里说明"**只能用以下工具**" ✔。

**要点**：候选集要**可解释** ✗ ✔（为什么给这几个 ✔ —— 便于归因与调试 ✔）。

四、工具说明要写"像给人看的文档"

名字直白（`search_orders` ✔ 而不是 `qo_v2` ✗）；

说明里写**边界与常见陷阱**（"只返回最近 90 天" ✔）；

参数要**可枚举的给枚举** ✔（不要自由文本 ✔）；

**返回值要给人看**（见工具返回值那篇 ✔）。

五、该观测什么

**工具选择准确率**（选对工具的比例 ✔ —— 用评测集测 ✔）；

**参数填充错误率**（按工具分组 ✔ —— 错误率高的工具通常说明书写不清 ✔）；

**候选集命中率**（正确工具是否在候选里 ✔ —— 不在就是筛得不对 ✔）；

**工具数量与错误率的关系**（通常正相关 ✔ —— 用来推动精简 ✔）。

一条判据

> 给模型**10 个**工具 vs **50 个**工具 ✔，选择准确率差多少 ✔？

> 如果差很多，说明目录没做分层与筛选 ✗（加工具只会更糟 ✔）。