适用读者：要设计工具 schema、要把工具从十几个扩到上百个、遇到"模型乱选工具"的人。
前置：S21-J08（五类工具）、B03（Function Calling 与工具设计）、B05（MCP 协议）。
覆盖旧文：A-4570（工具，第 4 章，30,369 字符）→ 16 小节 / 约 3 万字符。
扩展点：E-S21-035（ACI：工具应对应目标不是 API）、E-S21-036（形态 vs 披露是两个独立决策）、E-S21-037（描述四件事与参数保真）。
上一篇：S21-J10 · 用户记忆与知识库：从三种层次到可执行记忆
下一篇：S21-J12 · Coding Agent 与通用 Agent。
1. 一句话结论
工具设计有两件常被混为一谈的事：形态（做成工具还是文档）和披露（一次看见多少条）。 前者决定每条能力的常驻成本与传参方式，后者决定同时摆在模型面前的条数。工具选错的根因，八成在描述与披露，不在模型。
出处：《AI Agent 深入理解》第 4 章（
A-4570）。
2. 五类工具的坐标：调用方向 × 作用对象
| 类型 | 调用方向 | 作用对象 | 例子 | 设计重点 |
|---|---|---|---|---|
| 感知 | Agent 主动调用 | 获取信息 | web_search、fetch_url、grep_file |
控制输出量，防上下文爆炸 |
| 执行 | Agent 主动调用 | 改变世界 | shell_exec、code_interpreter、write_file |
安全约束（错一次代价可能极高） |
| 协作 | Agent 主动调用 | 驱动其他 Agent/人 | spawn_subagent、send_message_to_subagent、list_agents |
权限、可见性、成本 |
| 用户沟通 | Agent 主动调用 | 向用户传信息 | reply_to_user、send_card_to_user |
多渠道异步可达 |
| 事件触发 | Agent 注册、外部触发 | 驱动 Agent 开始执行 | set_timer、monitor_shell、connect_channel |
注册与触发两个时刻 |
要点：这张表不是交叉分类框架（每类的作用对象是专属取值），而是定位工具——先问"谁发起""对什么起作用"，再谈 schema。
事件触发工具的双时刻：注册时 Agent 主动声明"我关心什么事件"；触发时由外部回调唤醒。没有它，Agent 只能在用户开口时被动响应（详见 J13 的事件驱动）。
3. ACI：工具应对应"目标"，不是"API"（E-S21-035）
早期形态：把每个 API 端点包成一个工具 → 粒度太细，完成一个目标要协调好几个工具。
ACI（Agent-Computer Interface）：对标 HCI——让工具对 Agent 友好，而不是对人友好。三条原则：
① 形态：能力该做成什么（专用工具 / 通用执行器 / Skill）
② 描述：怎么让模型知道"什么时候用、什么时候不能用"
③ 保真：参数传递不得偷偷改变模型的意图
4. 形态谱系：专用工具 ↔ 通用执行器 ↔ Skill（E-S21-036）
| 形态 | 常驻成本 | 确定性 | 传参 | 谁能改 |
|---|---|---|---|---|
| 专用工具 | 每条 schema 数百 token | 高（schema 约束、可测） | 结构化 | 需发版 |
| 通用执行器（bash / code_interpreter） | 一个工具覆盖大量场景 | 中（靠模型写代码） | 自由文本 | 立即（写脚本） |
| Skill | 目录条目几十 token，正文按需读 | 中（流程文档） | 自然语言 + 通用工具 | 改文档即可 |
默认取向：通用工具优于专用工具——除非存在明确的安全、权限或性能理由。与其给四则运算计算器，不如给装好 sympy/numpy/pandas 的 code_interpreter。
两个独立决策（关键纠偏）：
| 决策 | 决定什么 | 四种组合都真实存在 |
|---|---|---|
| 形态 | 每条能力常驻多少 token、参数怎么传、谁能改 | 几百工具的 MCP 也可能只暴露索引 |
| 披露 | 一次有多少条摆在模型面前 | 二十个 skill 可全量常驻，上千个必须分层检索 |
误区的来源：skill 目录比工具 schema 便宜一个数量级，把"全量常驻"的可行边界推远——但那只是让披露更宽松，没替你选披露策略。
5. 描述的艺术：四件事，边界优先（E-S21-037a）
| 要写 | 反面 | 正例 |
|---|---|---|
| 何时用（触发条件） | "搜索相关内容" | "需要实时信息或查未知事实时使用" |
| 边界与反例（做不到什么） | 只说能做什么 | "仅按文件名匹配，不搜索文件内容" |
| 参数带例子 | "RFC3339 格式" | "RFC3339，例如 2024-03-15T14:30:00Z" |
| 返回值形状 | 无 | "返回 JSON 数组，元素含 title/url/snippet" |
加一条：调用示例。JSON Schema 只能描述类型，无法表达"秒还是毫秒""过滤条件怎么嵌套"。附 1–5 个真实调用例子，原文报告某些基准上准确率从约 72% 提升到 90%（属作者引述的基准数据，非本机实测）。
耗时提示也属描述："此工具需下载整页，大型站点可能 5–10 秒；只要元信息请用 get_page_metadata"——模型据此规划顺序。
调试原则：Agent 频繁选错工具 → 先改描述，再怀疑模型。 改描述的投入产出比通常高于换模型。
6. 参数保真：不许"智能修正"（E-S21-037b）
反模式一：静默输入转换。 某 IDE 的编辑工具把中文弯引号 “” 静默转成 ""：读取工具原样返回弯引号，模型照抄进 old_string，替换工具却已转换 → "未找到匹配"。模型反复重试，永远无法自诊断，因为它看到的世界与工具操作的世界不一致。
反模式二：静默参数注入。 某 bash 工具对所有 git commit 自动追加一个标记参数；用户 Git 版本较旧不支持 → 每次 commit 都失败，模型改措辞、换参数组合都没用。
原则：模型感知到的世界 与 工具操作的世界 之间，不得存在系统性偏差。
需要规范化（如统一编码）→ 必须在描述里说明，并在返回里告知模型。
判据："帮模型修正"是最贵的坑——它把可诊断的报错换成了不可诊断的灵异失败。
7. 工具太多：三层披露（E-S21-036 续）
规模本身就是伤害：超过一百个工具，最先进的模型也容易选错；全量平铺还烧 token，且工具集一变就击穿 KV Cache。
| 层 | 做法 | 证据（原文引述） |
|---|---|---|
| ① 层次化组织 + 按需加载 | 只暴露索引，需要时再查定义 | Cursor A/B：MCP 相关任务总 token 减 46.9% |
| ② 主动工具发现 | Agent 执行中意识到缺口，主动声明需求，系统动态注入 | Anthropic 实验：Opus 4 工具基准49% → 74% |
| ③ Skills 按需查阅 | 不注册工具，当参考资料翻 | 目录几十 token，正文用到才读 |
为什么 ② 比 ① 更进一步：检索式预筛选按初始 query 一次性匹配，而 "Debug the file" 会牵出文件访问、代码分析、命令执行——任务开始时无法预见全部需求。
层次化分类（四类）：
| 类 | 例 |
|---|---|
| 搜索 | 网络/知识库/文件搜索 |
| 读取 | 网页阅读、文档读取、DB 查询 |
| 解析 | OCR、视频分析、音频转写 |
| 查询 | 天气/股票 API、公开数据库 |
在系统提示里写出分类结构，模型能更快定位到工具组。
架构取舍案例：Pi Coding Agent 核心刻意不内置 MCP，优先把能力封成"带 README 的 CLI 工具"+ Skills 按需加载；社区 pi-mcp-adapter 折中为"默认只暴露约 200 token 的代理工具，搜索→查看定义→调用，后端 MCP 首次使用才启动"。
判据："是否采用 MCP 作为互操作协议"与"是否在会话开始就暴露全部 MCP 定义"是两个独立决策。 5 个 MCP 服务器就可能引入数万 token，在 200K 窗口里还没对话就吃掉近三成。
8. 三类主动工具的设计重点
| 类 | 主要风险 | 设计手段 |
|---|---|---|
| 感知 | 输出爆炸（读一个网页灌满上下文） | 分页、摘要、结构化字段、上限 |
| 执行 | 不可逆副作用 | 白名单、沙箱、干跑（dry-run）、人工确认 |
| 协作 | 递归爆炸、成本失控 | 子 Agent 数上限、深度上限、预算传递 |
多模态感知：图片/音频/视频进入观察空间时，先转成文本或结构化字段再入上下文，避免直接塞原始媒体（成本与注意力双高）。
9. 反例与排障
| 现象 | 根因 | 处理 |
|---|---|---|
| 模型总选错工具 | 描述缺"何时用/边界" | 按 §5 四件事重写 |
| token 花在工具定义上 | 全量平铺 | 只暴露索引（§7①） |
| 工具集一变就变慢 | KV Cache 被击穿 | 固定工具集/前缀稳定（J09） |
| 明明匹配却报"未找到" | 静默转换 | 关闭隐式规范化 |
| 多步任务半途用错能力 | 一次性预筛 | 主动发现（§7②） |
10. 自测
- 形态与披露各决定什么？为什么两者常被混淆？
- 工具描述里最该写、却最常被漏掉的是什么？
- 静默输入转换为什么比"直接报错"更糟？
- 按需加载与主动发现的关键差别？各自证据数字是多少？
答案
- 形态决定常驻成本/传参/谁能改；披露决定同时可见条数。混淆源于 skill 目录比 schema 便宜一个数量级。
- 边界与反例（做不到什么）。
- 模型看到的世界与实际操作不一致，无法自诊断，只能无限重试。
- 按需加载按初始需求取索引（token −46.9%）；主动发现在执行中补能力缺口（49%→74%）。
11. 下一篇
S21-J12 · Coding Agent 与通用 Agent —— 为什么"写代码"是 Agent 的基础能力、Coding Agent 的完整流程与 Harness 分工、故障恢复与搜索工具（待写）。
本篇属于系列《S21 · Agent 工程与 MCP》。旧文来源：A-4570（《AI Agent 深入理解》第 4 章）；扩展点 E-S21-035/036/037。46.9%、49%→74% 等数字为原文引述的第三方实验，属待复算。