tool-interface

name	tool-interface
description	当你在设计或审查单个工具的接口（描述、参数、返回值、粒度、通用性、参数保真）时使用；当 Agent 频繁选错工具、传错参数、调用失败后无法自诊断时使用。不适用于工具生态互操作（见 tool-mcp-ecosystem）或大规模工具发现（见 tool-discovery）。

工具接口设计（Tool Interface Design / ACI）

角色与读者

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

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

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. 工具粒度：整合相似工具，保留高频/参数集差异大的独立工具

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

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

   • 不得静默输入转换（弯引号→直引号）或静默参数注入（git commit 自动加 AI 标记）。
   • 反例：静默转换导致模型传入原文却"找不到匹配"，反复失败无法自诊。
   • 例外：确实需规范化时，必须在工具描述说明 + 返回中明确告知。

6. 执行工具的幂等性与取消语义（副作用到底发生没有）

   • 执行工具改变外部世界，必须回答"调用被取消/超时时副作用发生没有"。转账超时返回失败，钱可能已转出——盲目重试就重复转账。
   • 幂等手段：① 操作携带唯一标识，服务端凭此去重，重复请求返回首次结果；② 先查询后变更（重试前查目标资源状态，确认未完成再执行）。
   • 非幂等操作（发邮件/打电话/转账）："预检-确认"两段式——第一段用不同家族模型+专用安全检查提示词校验（查余额、确认收款方、生成内容），第二段才真正执行；执行失败不能盲目重试，返回详细错误给主模型重新规划。

执行流程（SOP 检查清单）

1. 先问"该不该做成工具"：参数复杂度 / 变更频率 / 模型能力三维判断（频繁变化用 Skill+通用执行器，稳定底层用专用工具）。
2. 写描述：什么时候用 + 边界（不能做什么）+ 参数具体例子 + 返回值 + 耗时提示。
3. 附 1-5 个真实调用示例。
4. 确定粒度与通用性：相似整合、高频独立、高风险专用。
5. 检查参数保真：有无静默转换/注入。
6. 对执行工具设计幂等性（唯一标识去重 / 先查询后变更）或非幂等操作的"预检-确认"两段式。
7. 调试原则：Agent 频繁选错工具时，优先改工具描述而非换模型。

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

• 禁止静默输入转换和静默参数注入。例外：规范化处理必须显式说明并在返回中告知。
• 禁止把高风险操作做成通用工具。例外：支付/删除/发信必须专用 + 权限受限 + 可审计 + 人工确认。
• 禁止工具数量无节制膨胀。例外：超数十个考虑 Skill+通用执行器（7 个核心工具覆盖大部分场景）或主动工具发现。
• 禁止粒度过粗或过细。例外：功能相似但参数集差异大、或使用频率极高时保持独立。
• 禁止抽象参数规范（"RFC3339 格式"）不配例子。例外：复杂任务中模型只能分一小部分注意力确认格式，具体例子让它直接套用。
• 禁止非幂等操作（发邮件/打电话/转账）盲目重试（每执行一次产生一个不可撤销真实事件）。例外：用"预检-确认"两段式，执行失败返回详细错误给主模型重新规划。

参考资料

• 本书第 4.2 节《工具设计的通用原则》（能力表达形式、粒度、通用性、描述艺术、参数保真、三代演进）。
• 笔记 04-工具.md 第 4.2 节。
• Claude Code 工具定义（观察使用边界、具体示例、性能提示、工具协作关系）。