# Tool Design

设计 Agent 工具时使用, , 新增/重构工具集、给 MCP 服务器设计工具、判断能力该做成专用工具还是 Skill、编写工具描述与参数...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill tool-design -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill tool-design -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill tool-design -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill tool-design -g -a gemini-cli -y`

## Description

设计 Agent 工具时使用, , 新增/重构工具集、给 MCP 服务器设计工具、判断能力该做成专用工具还是 Skill、编写工具描述与参数 schema、设计感知工具的输出分页与截断、给执行工具加安全审批与沙盒、设计子 Agent 协作接口时查阅。覆盖工具分类、ACI 通用设计原则、感知/执行/协作三类工具的设计要点。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 工具设计

## 何时使用
- 为 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 远高于换更强的模型。

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/tool-design/SKILL.md