04 - 工具设计哲学
给 Agent 设计工具 ≠ 给人设计 API
给人用的 API 追求功能齐全，但给 agent 用，重点不是功能堆得多完整，而是让它更容易用对。
设计原则
- 名称前缀按系统或资源分层：
github_pr_*、jira_issue_* - 对大响应支持 response_format：
concise/detailed - 错误响应要教模型如何修正，不要只抛 opaque error code
- 能合并成高层任务工具时，不要暴露过多底层碎片工具，避免
list_all_*让模型自行筛选
AskUserQuestion 的演进
Claude Code 团队试了三种做法来实现”任务中途停下来问用户”：
| 版本 | 方案 | 问题 |
|---|---|---|
| 第一版 | 给已有工具加 question 参数 | Claude 大多数时候直接忽略参数 |
| 第二版 | 输出里写特定 markdown 格式 | 没有强制约束，Claude 经常”忘了”按格式写 |
| 第三版 | 独立的 AskUserQuestion 工具 | 调用即暂停，没有歧义 |
教训：既然要 Claude 停下来问一句，就直接给它一个专门的工具。加 flag 或约定输出格式，很多时候它一顺手就略过去了。
Todo 工具的演进
早期用 TodoWrite 工具 + 每 5 轮插入提醒让 Claude 记住任务。随着模型变强，这个工具反而成了限制——Todo 提醒让 Claude 认为必须严格遵循计划，无法灵活修改。
当初加这个工具是因为模型不够强，模型变强之后它反而变成了枷锁。
值得过段时间回来检查：当初加的限制还成不成立。
搜索工具的演进
最初用 RAG 向量数据库，虽然快但需要索引、不同环境脆弱，最重要的是 Claude 不喜欢用。改成 Grep 工具让 Claude 自己搜索后，好用很多。
顺带的好处：Claude 读 Skill 文件 → Skill 引用其他文件 → 模型递归读取 → 按需发现信息，不需要提前塞进去。这个模式后来被叫做”渐进式披露”。
什么时候不该再加 Tool
- 本地 shell 可以可靠完成的事情
- 模型只需要静态知识，不需要真正与外部交互
- 需求更适合 Skill 的工作流约束，而不是 Tool 的动作能力
- 还没验证过工具描述、schema 和返回格式能被模型稳定使用
Prev: 03 - Skills 设计 | Next: 05 - Hooks 设计