工具：Agent 的手脚怎么设计
第 4 章聊工具（Tools）——Agent 连接”大脑”和真实世界的手脚和感官。书里类比《Her》里的 Samantha。
先分清：工具长什么样
能力表达有个谱系，从专用到通用：
- 专用工具：结构化函数调用，确定、可测，但每个定义占几百 token
- 通用执行器：比如
code_interpreter、bash，给”元能力”，用代码串起一堆操作 - Skill：自然语言写的文档（SKILL.md），用到才读
默认取向：通用优先于专用。能用 code_interpreter 代替计算器就别造专用工具。退回专用只在这四种情况：要审计安全权限、要屏蔽平台差异、使用极高频、参数结构太复杂。
这跟第 2 章 Skills 懒加载是一脉相承的——能通用就别堆专用，token 和注意力都省。
五个工具类型
书里把工具分五类，前三类是 Agent 主动调的：
- 感知：获取信息（web_search、read_file、grep）
- 执行：改变世界（shell_exec、write_file、send_email）
- 协作：驱动其他 Agent 或人（spawn_subagent、send_message）
- 用户沟通：向用户传信息（reply_to_user、发卡片）
- 事件触发：Agent 注册、外部触发（set_timer、monitor_shell）
后两类依赖异步运行时，第 6 章才展开。
工具描述比模型更重要
核心不是让模型知道”能做什么”，而是”何时用”——边界（不能做什么）比能力描述更重要。
几个实战点：
- 参数给具体例子（
+8613888888888）而不是抽象规范（E.164） - 附 1–5 个真实调用示例，准确率能从 ~72% 飙到 ~90%
- 选错工具？先改 description，别急着换模型
参数保真：别偷偷改
两个反模式要避：
- 静默输入转换：执行前偷偷把弯引号变直引号，模型还以为传的是弯的，匹配直接失败
- 静默参数注入：工具自己给 git commit 加 AI 标记，旧版 git 不认，提交报错
保真性是硬要求。要规范化也得写进描述、并告诉模型。
工具怎么分发：MCP 与 Skill Hub
- MCP（Model Context Protocol）：Anthropic 2024 底出的开放标准，客户端-服务器，JSON Schema 描述工具。一次开发处处用。
- Skill Hub：文件夹即分发单元，一条
npx skills add装，token 成本比 MCP 低一两个数量级。
风险得防：第三方描述即不可信输入，可能投毒；Skill 含代码更危险。缓解：审描述、锁版本、最小凭证、Sidecar 门控。
前面讲工具怎么设计、怎么分发。接着讲规模化后的组织，和三类主动工具的设计坑。
工具太多怎么办
成百上千个工具，一次全塞上下文？不行。三条路：
- 层次化组织 + 按需加载：只暴露索引。实测 Cursor 减 46.9% token；Anthropic 检索式预筛把 Opus 4 准确率从 49% 拉到 74%
- 模型原生主动发现：不预置 schema，Agent 自己声明缺口去搜（MCP-Zero 省 98% token）
- Skills：把发现变成”按需查阅”，连嵌入索引都省了
（易错：做成 Skill 还是专用工具，跟”一次暴露多少条”是两个独立决策，别混。）
感知工具：控制输出量
搜索返回结构化列表 + 分页；读文件支持 offset/limit + 显式截断。关键：截断必须显式注明省略了多少行、怎么继续读，否则模型以为看全了。
只读的可以缓存、可以并行。
执行工具：多层安全
- 输入验证 → 权限黑名单 → 提议者审核 → Sidecar 门控
- 写文件后跑 linter，形成”执行-验证-反馈”闭环
- 长输出截断后持久化，别丢
- 沙盒隔离：注意 venv ≠ 沙盒，真隔离要容器/microVM
- 幂等性：发邮件、转账不能重复执行，得预检-确认两段式，超时别盲重试
协作工具：子 Agent 与 HITL
- 原语：spawn / cancel / message / list
- 提示词标清来源，防注入（来源 A 的内容假装成来源 B 的指令）
- HITL：人在回路，超时降级 + 反馈循环
两个安全机制
- 提议者-审核者：独立第二视角检验，事前审批或事后验证
- Sidecar：伴随主循环的轻量 LLM 调用，对单次工具调用做安全门控，只读结构化字段防注入
Sidecar 敢用轻量模型，是因为它审的是”分类问题”不是”开放思考”；提议者要同族能力。分工很妙。
