工具提示工程：让 agent 会用工具而不是猜工具
工具提示工程：让 agent 会用工具而不是猜工具：把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复，通过架构、轨迹和故障重放完成验收。
学习目标
- 能解释“工具提示工程：让 agent 会用工具而不是猜工具”如何把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复
- 能区分工具提示工程、选择精度、参数通过率、结果理解率、恢复率，并指出控制权、数据与副作用边界
- 能固定输入与版本，沿以下证据定位首个分叉：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹
- 能注入“只看工具函数单元测试通过，却从不测模型是否会选择和正确填写它”，完成阻断、恢复、复位和同输入重放
来源、课程编排与适用边界
“工具提示工程：让 agent 会用工具而不是猜工具”以Anthropic 公开全文《Building effective agents》为总纲，并用Anthropic《Writing effective tools for agents》核对本单元机制；涉及 MCP 的控制权边界再由MCP 2025-06-18 官方规范交叉检查。
这不是 Anthropic 出版的“19 章教材”。平台把公开文章、官方工具文档与协议规范重组为 19 个应用单元；下列 152 个节点是站内课程地图，不冒充原文目录。正文、代码、图表、实验和练习均为独立教学重写；产品接口、模型行为或协议版本变化时必须重新验证。
本单元的八个课程坐标
- 工具提示工程：让 agent 会用工具而不是猜工具：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 1 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 先打个比方：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 2 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 工具定义就是给模型看的提示：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 3 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 描述要写边界，而不只写功能：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 4 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 参数 schema 要替模型消歧：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 5 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 返回结果语义会改变下一次选择：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 6 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 错误要帮助模型恢复：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 7 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 工具定义要靠 eval 迭代：这是“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的第 8 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
术语与运行合同
↡工具提示工程：通过迭代工具定义改善模型使用行为的过程；在“工具提示工程：让 agent 会用工具而不是猜工具”中按以下证据核对：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。、↡选择精度：需要该工具的任务中模型正确选择它的比例；在“工具提示工程：让 agent 会用工具而不是猜工具”中按以下证据核对：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。、↡参数通过率：模型生成参数一次通过 schema 与业务校验的比例；在“工具提示工程：让 agent 会用工具而不是猜工具”中按以下证据核对：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。、↡结果理解率：模型能否依据工具返回做出正确下一步的比例；在“工具提示工程：让 agent 会用工具而不是猜工具”中按以下证据核对：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。、↡恢复率：工具返回可恢复错误后模型能修正并继续的比例；在“工具提示工程：让 agent 会用工具而不是猜工具”中按以下证据核对：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。。
本页不变量是：工具改动必须在代表轨迹上同时验证选对、填对、读懂和恢复四个环节。任何“成功”结论都要保存以下证据：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹，模型生成的计划或自信不能替代环境事实。
关键机制与可推翻实验
从真实失败轨迹开始
凭直觉润色描述容易优化错误问题，应先聚类误选、误填和误读。
动手验证：标注一批失败轨迹并计算各类占比。
边界描述比功能口号重要
“搜索数据”太宽，应该说明数据域、何时使用和与相邻工具的区别。
动手验证：用相邻意图样本测误选率。
参数名要消除歧义
抽象缩写、隐式单位和布尔开关会增加猜测，应改成语义明确的枚举和结构。
动手验证：比较改名前后的首轮 schema 通过率。
错误返回指导下一步
错误需说明缺什么、能否重试、何时转人工，不能只给内部代码。
动手验证：注入缺权限、速率限制和不存在资源三类错误，测恢复路径。
先预测，再操作三类证据
1. 架构与复杂度边界
在“工具提示工程：让 agent 会用工具而不是猜工具”中切换简单基线、受控工作流与自主循环，先预测“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”在哪个阶段需要增加控制权，再比较延迟、成本、可观测性和自主性。
Architecture decision laboratory
工具提示工程：让 agent 会用工具而不是猜工具
把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复
不变量：工具改动必须在代表轨迹上同时验证选对、填对、读懂和恢复四个环节
最小可运行实现
for (const version of toolDefinitionCandidates) {
const runs = await runToolEval(version, representativeTasks);
report(version, {
selection: precision(runs),
arguments: schemaPassRate(runs),
comprehension: nextStepAccuracy(runs),
recovery: recoveryRate(runs),
});
}这段切片只暴露“把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复”的最小运行合同。交付版本还要补齐超时、密钥隔离、结构化日志、幂等和批量评测；缺少工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹时，代码能运行也不代表本章结论成立。
小结
- 工具定义是给模型看的提示，须当作可评测提示迭代
- 描述要写边界而不只写功能，消除误选
- 参数名要消除歧义，用语义明确的枚举和结构
- 错误返回要指导模型恢复，不能只给内部代码
- 须同时验证选对、填对、读懂和恢复四个环节
练习与答案
练习
问题 1：最小证明。 怎样用最少样本证明“工具改动必须在代表轨迹上同时验证选对、填对、读懂和恢复四个环节”？
问题 2：课程覆盖。 工具提示工程：让 agent 会用工具而不是猜工具、先打个比方、工具定义就是给模型看的提示、描述要写边界，而不只写功能、参数 schema 要替模型消歧、返回结果语义会改变下一次选择、错误要帮助模型恢复、工具定义要靠 eval 迭代如何进入可操作验证？
问题 3：恢复闭环。 怎样证明“只看工具函数单元测试通过，却从不测模型是否会选择和正确填写它”已经修复？
本章回顾
- “工具提示工程：让 agent 会用工具而不是猜工具”的主问题是把工具定义当作可评测提示，迭代名称、描述、参数、返回与错误恢复。
- 核心不变量是工具改动必须在代表轨迹上同时验证选对、填对、读懂和恢复四个环节。
- 首要反例是只看工具函数单元测试通过，却从不测模型是否会选择和正确填写它。
- 最小证据包包含工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。
名词解释
本章出现的专业名词，用大白话再讲一遍。
- 工具提示工程
通过迭代工具定义改善模型使用行为的过程。在“工具提示工程：让 agent 会用工具而不是猜工具”中必须能按以下证据重新定位：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。
- 选择精度
需要该工具的任务中模型正确选择它的比例。在“工具提示工程：让 agent 会用工具而不是猜工具”中必须能按以下证据重新定位：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。
- 参数通过率
模型生成参数一次通过 schema 与业务校验的比例。在“工具提示工程：让 agent 会用工具而不是猜工具”中必须能按以下证据重新定位：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。
- 结果理解率
模型能否依据工具返回做出正确下一步的比例。在“工具提示工程：让 agent 会用工具而不是猜工具”中必须能按以下证据重新定位：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。
- 恢复率
工具返回可恢复错误后模型能修正并继续的比例。在“工具提示工程：让 agent 会用工具而不是猜工具”中必须能按以下证据重新定位：工具定义版本、任务集、选择率、参数通过率、结果理解率、恢复率与失败轨迹。