tool-design

name	tool-design
description	当你在设计、审查或调试 Agent 的工具接口（函数/CLI/MCP 工具的描述、参数、返回值、粒度、权限）时使用；当 Agent 频繁选错工具、传错参数、调用失败后无法自我恢复时使用。不适用于工具背后的业务逻辑实现，也不适用于上下文布局（见 context-engineering）。

工具设计（Tool Design / ACI）

子 Skill 索引（渐进式披露：目录常驻，正文按需加载）

子 Skill	目录	何时深入加载
工具接口设计	tool-interface	设计/审查单个工具的描述、参数、粒度、保真
MCP 与工具生态	tool-mcp-ecosystem	接入 MCP、控制上下文开销、评估第三方工具信任风险
主动工具发现	tool-discovery	工具成百上千、模型选择精度下降、按需发现加载

角色与读者

面向 Agent 工具开发者。本 Skill 服务的目标：让工具接口对 Agent（而非程序员）友好——这就是 ACI（Agent-Computer Interface，对标 HCI）的核心。设计不好的工具会让再强的模型也频繁出错，因为模型与工具之间唯一的沟通通道就是接口本身。

核心原则（配正例/反例）

1. 描述"什么时候用"而非"能做什么"，边界比能力更重要

   • 大多数工具调用失败的根因不是模型不知道工具能做什么，而是不知道工具不能做什么。
   • 正例："当需要获取实时信息或查找未知事实时使用"（帮助决策）> "搜索相关内容"（只描述功能）。
   • 正例（边界）：文件搜索工具明确写"只能基于文件名匹配，不能搜索文件内容"。

2. 参数用具体例子代替抽象规范，并描述返回值

   • 正例：timestamp：RFC3339 格式，例如 2024-03-15T14:30:00Z；phone：E.164 格式（国家代码+号码，无空格），例如 [phone]。
   • 正例：返回"JSON 数组，每个元素含 title、url、snippet 三个字段"。
   • 耗时工具注明执行代价："此工具需下载完整网页，大型网站 5-10 秒；只需元信息请用 get_page_metadata"。
   • 为每个工具附带 1-5 个真实调用示例（JSON Schema 只描述类型，无法表达"时间戳是秒还是毫秒、过滤条件如何嵌套"；加示例准确率可从 72% 提到 90%）。

3. 通用基础能力用于组合探索，专用工具用于约束高风险强业务规则操作

   • 正例（通用）：四则运算 → 一个 code_interpreter（沙盒装 sympy/numpy/pandas），代替十几个专用计算器。
   • 正例（专用）：支付、删除数据、发邮件、生产部署 → 封装为参数明确、权限受限、全程可审计的专用工具 + 预览 + 人工确认。

4. 参数传递保真（模型感知的世界 = 工具操作的世界）

   • 不得在模型不知情时修改输入或输出（静默输入转换）或追加参数（静默参数注入）。
   • 反例：把中文弯引号静默转直引号 → 模型传入原文却"找不到匹配"，反复失败无法自诊；给 git commit 静默加 AI 标记参数 → 旧版本 Git 报错，模型改措辞也无效。
   • 例外：确实需要规范化时，必须在工具描述说明 + 在返回中明确告知模型。

5. 工具粒度：整合相似工具，保留高频/参数集差异大的独立工具

   • 正例（整合）：extract_pdf_text / extract_docx_content / extract_pptx_content → 统一 read_document(file_type=...)。
   • 反例：工具数量超 100 个（即使先进模型也易选错）；把 grep/find 塞进 bash（丢失清晰行号反馈和平台屏蔽）。

执行流程（SOP 检查清单）

1. 从任务所需最窄能力起步，先问"该不该做成工具"（参数复杂度 / 变更频率 / 模型能力三维判断：频繁变化用 Skill+通用执行器，稳定底层用专用工具）。
2. 写描述：什么时候用 + 边界（不能做什么）+ 参数具体例子 + 返回值 + 耗时提示。
3. 附 1-5 个真实调用示例。
4. 确定粒度与通用性：相似整合、高频独立、高风险专用。
5. 检查参数保真：有无静默转换/注入。
6. 调试原则：Agent 频繁选错工具时，优先改工具描述而非换模型。

禁止清单（写清合法例外）

• 禁止静默输入转换和静默参数注入。例外：规范化处理必须显式说明并在返回中告知。
• 禁止把高风险操作做成通用工具。例外：支付/删除/发信等必须专用 + 权限受限 + 可审计 + 人工确认。
• 禁止工具数量无节制膨胀。例外：超过数十个就考虑 Skill+通用执行器（7 个核心工具覆盖大部分场景）或主动工具发现。
• 禁止粒度过粗（单个工具太复杂）或过细（工具激增）。例外：功能相似但参数集差异大、或使用频率极高时保持独立。
• 禁止把工具描述当无害元数据（第三方 MCP 工具描述是提示注入入口）。例外：接入前把 description 当不可信输入审计。

参考资料

• 本书第 4 章《工具》（五类工具、通用设计原则、MCP、感知/执行/协作工具、主动工具发现）。
• 笔记 04-工具.md。
• Claude Code 工具定义（观察其使用边界、具体示例、性能提示、工具协作关系）。