设计好用的工具
设计好用的工具：把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面，通过架构、轨迹和故障重放完成验收。
学习目标
- 能解释“设计好用的工具”如何把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面
- 能区分ACI、工具边界、poka-yoke、结构化错误、工具评测，并指出控制权、数据与副作用边界
- 能固定输入与版本，沿以下证据定位首个分叉：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率
- 能注入“提供多个功能重叠的万能工具，参数含糊，错误只返回 internal error”，完成阻断、恢复、复位和同输入重放
来源、课程编排与适用边界
“设计好用的工具”以Anthropic 公开全文《Building effective agents》为总纲，并用Anthropic《Writing effective tools for agents》核对本单元机制；涉及 MCP 的控制权边界再由MCP 2025-06-18 官方规范交叉检查。
这不是 Anthropic 出版的“19 章教材”。平台把公开文章、官方工具文档与协议规范重组为 19 个应用单元；下列 152 个节点是站内课程地图，不冒充原文目录。正文、代码、图表、实验和练习均为独立教学重写；产品接口、模型行为或协议版本变化时必须重新验证。
本单元的八个课程坐标
- 设计好用的工具：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 1 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 先打个比方：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 2 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 先看全景：好工具的五个维度：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 3 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 第一个取舍：工具粒度——不大不小才好用：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 4 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 第二个关键：错误信息——决定 agent 能不能自己爬起来：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 5 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 第三个关键：返回值——给精料，别甩一地原料：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 6 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 动手看：错误信息的好坏，怎么让 agent 一个爬起来、一个躺平：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 7 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 代码对照：同一个工具，坏的写法 vs 好的写法：这是“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的第 8 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
术语与运行合同
↡ACI：面向智能体设计的计算机操作界面；在“设计好用的工具”中按以下证据核对：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。、↡工具边界：一个工具负责和明确不负责的动作范围；在“设计好用的工具”中按以下证据核对：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。、↡poka-yoke：通过接口结构让常见错误更难发生的防错设计；在“设计好用的工具”中按以下证据核对：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。、↡结构化错误：包含错误类型、可否重试和恢复提示的结果；在“设计好用的工具”中按以下证据核对：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。、↡工具评测：在代表轨迹上测量选择、参数、结果理解和恢复的过程；在“设计好用的工具”中按以下证据核对：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。。
本页不变量是：工具名称、边界、参数和返回语义共同指向一个清晰动作，危险操作默认不可达。任何“成功”结论都要保存以下证据：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率，模型生成的计划或自信不能替代环境事实。
关键机制与可推翻实验
工具定义本身就是提示
模型依据名称、描述、参数和示例选择工具，它们需要与系统提示同等评测。
动手验证：只改工具描述，在冻结任务集上比较选择混淆矩阵。
贴近模型自然表达
要求复杂转义、手工行号或冗长 diff header 会制造格式错误。
动手验证：比较整段重写与复杂补丁接口的首轮成功率。
参数结构承担防错
绝对路径、枚举、互斥字段和资源标识可把错误挡在执行前。
动手验证：提交相对路径或冲突参数，确认 schema 直接拒绝。
结果只返回决策所需信息
原样倾倒大对象浪费上下文；应给摘要、稳定标识和按需深入入口。
动手验证：比较原始响应与紧凑结果的 token 和下一步正确率。
先预测，再操作三类证据
1. 架构与复杂度边界
在“设计好用的工具”中切换简单基线、受控工作流与自主循环，先预测“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”在哪个阶段需要增加控制权，再比较延迟、成本、可观测性和自主性。
Architecture decision laboratory
设计好用的工具
把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面
不变量：工具名称、边界、参数和返回语义共同指向一个清晰动作，危险操作默认不可达
最小可运行实现
const readFileTool = defineTool({
name: "read_file",
description: "读取工作区内一个绝对路径；目录请改用 list_directory",
schema: z.object({ absolutePath: workspacePath }),
run: async ({ absolutePath }) => ({
content: await readLimited(absolutePath),
truncated: false,
}),
});这段切片只暴露“把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面”的最小运行合同。交付版本还要补齐超时、密钥隔离、结构化日志、幂等和批量评测；缺少工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率时，代码能运行也不代表本章结论成立。
练习与答案
练习
问题 1：最小证明。 怎样用最少样本证明“工具名称、边界、参数和返回语义共同指向一个清晰动作，危险操作默认不可达”？
问题 2：课程覆盖。 设计好用的工具、先打个比方、先看全景：好工具的五个维度、第一个取舍：工具粒度——不大不小才好用、第二个关键：错误信息——决定 agent 能不能自己爬起来、第三个关键：返回值——给精料，别甩一地原料、动手看：错误信息的好坏，怎么让 agent 一个爬起来、一个躺平、代码对照：同一个工具，坏的写法 vs 好的写法如何进入可操作验证？
问题 3：恢复闭环。 怎样证明“提供多个功能重叠的万能工具，参数含糊，错误只返回 internal error”已经修复？
本章回顾
- “设计好用的工具”的主问题是把工具设计成模型容易选、难以误用、结果紧凑且错误可恢复的操作界面。
- 核心不变量是工具名称、边界、参数和返回语义共同指向一个清晰动作，危险操作默认不可达。
- 首要反例是提供多个功能重叠的万能工具，参数含糊，错误只返回 internal error。
- 最小证据包包含工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。
名词解释
本章出现的专业名词，用大白话再讲一遍。
- ACI
面向智能体设计的计算机操作界面。在“设计好用的工具”中必须能按以下证据重新定位：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。
- 工具边界
一个工具负责和明确不负责的动作范围。在“设计好用的工具”中必须能按以下证据重新定位：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。
- poka-yoke
通过接口结构让常见错误更难发生的防错设计。在“设计好用的工具”中必须能按以下证据重新定位：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。
- 结构化错误
包含错误类型、可否重试和恢复提示的结果。在“设计好用的工具”中必须能按以下证据重新定位：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。
- 工具评测
在代表轨迹上测量选择、参数、结果理解和恢复的过程。在“设计好用的工具”中必须能按以下证据重新定位：工具选择混淆矩阵、参数错误率、恢复率、token 成本、权限拒绝与任务成功率。