tool-design

工具设计

何时使用

• 为 Agent 新增一批工具，或审查既有工具集（"这个工具该不该拆/该不该合"）
• 判断一项能力应做成专用工具（function calling）、通用执行器，还是一份 Skill
• 编写或修订工具 name / description / 参数 schema / 返回值说明
• 设计感知工具（搜索、读取、多模态解析）的返回格式、分页与截断策略
• 设计执行工具（shell、文件、外部系统）的输入验证、审批、沙盒与可观测性
• 设计协作工具（spawn_subagent、HITL、通知）的接口与提示词

核心原则

• 工具对应目标，不对应 API 端点。 早期反模式是把每个 API 端点包成一个工具，Agent 要协调好几个才能完成一个目标。这是 ACI（Agent-Computer Interface）的核心：让工具对 Agent 而非对人友好。
• 默认通用优于专用。 LLM 本身有强大的思考与代码生成能力，不要限制它。与其提供四则运算计算器，不如给一个装好 sympy/numpy/pandas 的 code_interpreter。
• 四种情况才退回专用工具：① 安全、权限、审计需要（如生产库写操作）；② 屏蔽平台差异并给出更好反馈（如 grep/find 在 Mac/Win/Linux 语法不一）；③ 使用频率极高；④ 参数结构复杂（嵌套对象、多字段联合校验）。
• 粒度偏向整合。 判断标准是功能相似性与使用场景重叠度：extract_pdf_text/extract_docx_content/extract_pptx_content 应合成 read_document(file_type=...)。整合降低认知负担、描述更清晰、便于扩展。
• 形态与数量是两个独立决策。 能力做成什么形态定"每条能力常驻多少 token、参数怎么传、谁能改"；一次暴露多少条是披露策略。别把两者混为一谈。
• 感知工具防上下文爆炸，执行工具防不可逆错误。 前者的设计关键是控制输出信息量，后者的设计核心是安全约束。
• 模型感知到的世界与工具操作的世界之间不能有系统性偏差——不得静默转换或注入参数。

实践模式

1. 形态选择的四个决策维度

维度	判据
安全与权限	需精细授权、审计留痕、有不可逆风险 → 专用工具；否则优先通用
参数复杂度	嵌套对象、多字段联合校验 → 专用 schema；简单参数走 CLI 同样可靠
变更频率	频繁变化 → Skill（改文本，不用重新测试部署）；稳定底层操作 → 专用工具
模型能力	强模型可用 Skill + 通用执行器减少工具数；弱模型需要结构化 schema 引导

Skill 的代价：模型要生成合法命令行参数并处理引号转义，规则比 JSON 复杂且跨平台有差异，参数复杂时更易出错。折中办法：Skill 要求把复杂结构化参数写成 JSON 文件，再在命令行导入。 Skill 的收益：人类编写者友好，不会因局部语法错误"牵一发而动全身"（schema 少个花括号会让整个 Agent 报错，Skill 少量错误不会）。

2. 工具描述的四条写法

• 写"什么时候用"，不只"能做什么"：不说"搜索相关内容"，说"当需要获取实时信息或查找未知事实时使用"。
• 明确边界比描述能力更重要：文件搜索工具必须说明它只按文件名匹配、不能搜文件内容。多数调用失败的根因是模型不知道工具不能做什么。
• 参数给具体例子：timestamp：RFC3339 格式，例如 2024-03-15T14:30:00Z；phone：E.164（国家代码+号码，无空格），例如 +8613888888888 / +12025551234。
• 描述返回值与代价："返回 JSON 数组，每元素含 title/url/snippet"；"此工具需下载完整网页，大型站点可能 5-10 秒，只要元信息请用 get_page_metadata"。
• 每个工具附 1-5 个真实调用示例。JSON Schema 只能表达类型，无法表达时间戳是秒还是毫秒、过滤条件如何嵌套这类隐式约定；加示例后基准准确率可从约 72% 升到 90%。
• 调试原则：Agent 频繁选错工具时，先查工具描述，别先怀疑模型。修正描述的 ROI 远高于换更强的模型。

3. 参数保真性

反模式是静默输入转换与静默参数注入：

• Cursor 曾把 old_string 中的中文弯引号（“”）静默转成英文直引号，导致读取工具原样返回弯引号、替换工具却匹配不到——模型反复失败且无法自行诊断。
• 某 IDE 的 bash 工具自动给所有 git commit 追加"AI 生成"标记参数，老版本 Git 直接报错，模型怎么改提交信息都失败。 规则：必须规范化时，在工具描述中说明，并在返回值中明确告知模型。