摘要给智能体写工具难点不在接口能否被调用而在于让模型知道何时调用、怎样传参、哪些返回值得相信、下一步能做什么。本文解读 Anthropic 的工程经验文章围绕「选择契约、输入契约、输出契约」展开先从工作流出发决定暴露哪些能力用命名空间和消歧字段避免模型在名称处走偏让返回值支持下一步而非展示后端一切省 token 时保住判断所需信息并用真实任务评测工具而非固定路线。核心方法是一套用任务评测反复改进工具的迭代流程最终让正确的信息更容易获得、业务对象更容易辨认、下一步动作更容易选对。“客户说同一笔订单被扣了三次帮我查清楚。”你给智能体接上了用户查询、订单查询、支付流水、日志读取四个 API。每个接口单独测试都正常。模型却拿着错误的标识符反复查询读了一大段无关日志最后把三次支付重试当成了三笔真实扣款。接口没有报错任务仍然失败了。给智能体做工具难点就在这里工具不仅要能被执行还要让模型知道何时调用、怎样传参、哪些返回内容值得相信以及下一步能做什么。本文解读 Anthropic 于 2025 年 9 月 11 日发表的Writing effective tools for agents — with agents。原文是工程经验文章核心是一套用任务评测反复改进工具的方法。下文的账单与日志接口是本文构造的教学例子未进行真实 LLM 性能实验。[1]工具契约里多了一个会理解错的调用者传统 API 的调用程序通常已经写好了字段映射和调用顺序。模型面对的却是一段自然语言需求它需要自行决定调用哪个工具、先查什么、是否继续、怎样解释结果。同一份工具定义对不同模型、不同任务上下文可能产生不同调用行为。这里的“不确定”主要发生在智能体的选择与生成环节并不意味着工具后端可以随意改变业务语义。因此一份可用的工具契约至少需要说明三件事选择契约什么情况下用它与相近工具的边界是什么。输入契约参数代表什么对象单位、格式、约束和默认值是什么。输出契约返回值支持什么判断是否完整有没有可继续调用的资源标识。例如statussuccess究竟表示 API 请求成功还是已经成功扣款如果工具定义不区分模型可能把一次请求成功当成业务完成。这个错误不能靠 JSON 语法检查发现。你仍然需要普通软件测试检查查询是否正确、分页是否稳定、业务操作是否符合约束还要增加智能体层面的任务评测检查模型能否借助这些接口完成真实目标。两种测试回答不同的问题。图 1原文的评测驱动迭代思路。中央流程从任务到原型再到评测与改进回路表示修改后重新测试右侧留出任务用于检查改进是否超出开发样例。这里优化的是工具与接口设计图中没有模型训练步骤。依据原文整理布局原创。[1]先从工作流出发决定暴露哪些能力把每一个后端 API 都包装成工具容易把数据库内部结构直接交给模型理解。模型要在许多相似名称之间选择还要完成大量低层关联。对开头的扣款问题一种接口设计可能要求模型先查客户再查订单再查支付尝试最后关联日志。另一种设计可以提供一个只读工具按支付尝试返回关联的请求记录、账务记录和必要日志。第二种设计把一部分确定性的关联工作放回程序。它的收益不只在于减少调用次数模型不必自己猜测哪个字段是关联键也少了一次把请求事件当作实际入账的机会。这并不要求所有操作都合成一个万能工具。查询范围过大、参数含糊、返回内容膨胀的“大工具”也会增加理解负担。适合合并的通常是边界稳定、经常连续出现、程序能确定执行的子流程。任务需要较难使用的接口形态更值得评测的候选设计找到与事故相关的日志返回一整天全部日志按时间、业务对象和事件类型搜索并提供少量上下文理解一位客户的近期情况分别列出全部订单、留言和流水汇总与当前问题相关的信息保留可追溯标识找到一个联系人一次返回完整通讯录先按姓名等条件搜索再返回明确候选与唯一标识完成多资源关联任务把所有关联键交给模型拼接在工具内部完成确定性关联暴露有业务意义的结果这是设计候选不是预先成立的优劣排名。是否合并要在同一批任务、同一调用预算上比较。对于需要灵活探索的场景较细的工具仍可能更合适。[1, §Choosing the right tools for agents]一个实用判断是这个参数要求模型做业务判断还是要求它重复一段可以确定编程的机械操作前者可以由模型处理后者往往适合留在工具内部。工具名称和描述决定了模型最早的分岔模型调用错误工具可能还没轮到复杂推理就已经在名称处走偏。search放在一个工具很少的应用里并不奇怪当系统同时有文档、人员、日志和工单搜索它就失去了区分力。原文建议按服务或资源进行命名空间划分同时提醒前缀和后缀的效果会随模型变化需要实测。[1, §Namespacing your tools]例如本文的日志接口可以叫billing_search_events。billing提示服务边界search_events说明操作对象。相近的billing_get_incident_context则用于读取一个明确事故对象的关联信息。两者的描述应该解释何时检索何时根据已有标识读取详情。参数同样需要消歧。user是姓名、用户名还是数据库 IDtime是北京时间、UTC还是服务器本地时间与其在描述末尾补一句“请正确使用”不如让字段名和结构本身消除歧义。{customer_id:cus_184,start_time_utc:2026-09-28T00:00:00Z,end_time_utc:2026-09-29T00:00:00Z,event_types:[payment_attempt,ledger_charge],limit:20,response_format:concise}这是一份示意参数不是实际调用记录。真正的工具规范还应写清时间区间是否包含边界、事件类型枚举、分页方法以及结果排序。工具描述可以像一份给新同事的简短使用说明解释目标、输入要求、返回内容以及重要的邻近工具差别。别让模型自行补齐人类工程师默认知道的背景。原文给出过一个很具体的案例模型在网页搜索查询中不必要地追加年份导致结果偏向特定时间。团队通过改写工具描述引导它改变行为。这个例子提醒我们描述里的几句话可能改变数据来源进而改变最终答案不能把它当成接口旁边的装饰文字。[1, §Analyzing results]返回值要支持下一步而不是展示后端的一切工具返回了 200 个字段不等于给了模型 200 份有效信息。对于扣款问题有用的内容是哪些事件属于同一支付尝试哪个是请求重试哪个形成了真实账务记录证据来自哪里。图片缩略图尺寸、内部 MIME 类型和无关调试字段通常无法帮助当前判断。但“优先返回语义信息”也不能写成“删除所有 ID”。如果下一步需要读取某笔交易的明细模型必须拿到可用的唯一标识。显示名帮助理解稳定 ID 支持操作两者承担不同职责。可以为工具提供concise与detailed两种返回模式简洁模式先给任务相关内容详细模式再补充下游操作和审计所需的字段。原文的 Slack 示例分别为 72 与 206 tokens说明的是一次示例响应的体积差异不是所有任务都会节省同样比例也不是准确率提升幅度。[1, §Returning meaningful context from your tools]图 2返回设计的关键关系。语义参数帮助限定查询分页裁剪控制结果范围资源标识允许继续读取对象证据支撑后续判断。图中“相关结果”不能只剩总结必要的原始依据和可调用标识仍须保留。机制示意原创。一份面向任务的返回值可以有这样的结构{events:[{event_id:evt_701,payment_attempt_id:pa_82,event_type:payment_attempt,summary:同一支付尝试的一次请求重试}],returned_count:1,has_more:true,next_cursor:cursor_2}这个例子刻意保留has_more。如果只显示“找到一条记录”却不告诉模型还有下一页它可能把局部结果当成全集。裁剪与摘要需要一份清楚的完整性说明。原文还指出JSON、XML 或 Markdown 的最佳选择依赖具体模型和任务。结构正确并不保证模型理解正确。应比较实际调用和结果解释而不是仅凭格式偏好决定。省 token 时要保住判断所需的信息长响应会占用上下文增加读取成本。原文建议使用分页、范围选择、过滤和截断并给出合理默认值。[1, §Optimizing tool responses for token efficiency]这里更值得优化的是无关信息而非一味压短。若一个错误日志同时写明失败位置、参数和重试条件压成“调用失败”虽然节省了 token却删掉了恢复需要的信息。同样工具报错应指向可执行的修正。假设查询超出允许时间范围可以返回明确错误代码、允许的最大跨度以及如何分段查询。直接暴露长堆栈或只说“无效参数”都可能让模型继续盲试。原文提到 Claude Code 当时默认限制工具响应为 25,000 tokens。这是文章发布时的一项产品设置不是推荐所有工具都接近这个长度也不是本文声称当前各版本仍采用同一上限。对日志任务一个可以实际检查的约束是返回信息中有多少条与事故有关分页有没有遗漏相关事件是否还能追溯到同一支付尝试这些检查比单独记录“响应更短了”更有解释力。用真实任务评测工具不把标准答案写成固定路线“搜索包含某字符串的日志”可以测试检索参数却很难测试模型能否查清事故。较强的任务会保留真实目标让模型自己选择步骤再用可核验结果判定是否完成。例如本文的扣款任务可以要求输出真实入账次数、对应交易标识、重试事件数量以及受影响对象。验证器检查这些结果不必强制它严格按照某一条工具序列执行。有些任务存在多条有效路线。如果验证器只接受特定措辞、标点或调用顺序就会把成功的方法判成失败。反过来如果只检查回答中有没有“重复扣款”这几个字也会放过没有证据的结论。图 3结果、成本和轨迹需要一起看。先对齐任务与预算记录实际调用再用独立判定检查结果最后比较工具版本。独立判定指评测标准与被测工具的自我描述分开并不要求每个任务都用另一位 LLM 裁判。依据原文整理。观察项能帮助定位的失败需要避免的误读可核验的任务完成率工具能否支撑目标API 成功返回不等于任务完成调用次数与重复调用是否有无效绕路、分页不当调用少也可能是提前放弃参数错误与工具错误定义、例子和约束是否清楚不把外部服务故障都归给模型输入输出 token返回信息是否挤占上下文短响应也可能删掉关键证据任务总时间与调用时间等待、串行依赖、慢查询单次调用快不等于任务完成快原始调用与返回记录模型忽略了什么误读了什么模型自己的总结可能漏掉关键错误最后一项尤其有用。模型会给出“工具设计得很好”的反馈却在真实调用里反复用错一个字段。你应先看它执行了什么再看它如何解释执行过程。原文也强调模型遗漏的行为有时比主动报告的意见更能暴露问题。官方工具评测 Cookbook 提供了按任务运行智能体、记录调用时间并汇总结果的示例。它适合帮助搭建评测骨架具体的结果验证仍需要根据业务目标设计。[2]让智能体改工具也要给它开发集之外的题目模型可以阅读失败轨迹提出更清楚的描述、调整参数名、合并常用查询并检查不同工具之间的定义是否一致。Anthropic 把这种合作用于内部 Slack、Asana 等工具的迭代并用留出任务检查效果。[1, §Collaborating with agents]真正值得复制的是这个实验顺序用开发任务发现问题修改工具重新运行再在未参与修改的任务上确认是否仍有收益。若每一轮都把测试答案交给优化工具的模型后面的分数就失去了留出验证的意义。对于开头的支付事故先修复一个可观察的问题就足够具体把支付重试与账务入账在工具返回中明确分开然后检查模型还会不会混淆。接着再判断是否需要聚合关联信息、调整分页或重写说明。一套好工具应该让正确的信息更容易获得让业务对象更容易辨认让下一步动作更容易选对。检查这三件事时最有说服力的材料是一条真实完成任务的调用轨迹。参考资料Ken Aizawa.Writing effective tools for agents — with agents.Anthropic2025-09-11。原文。已核对工作流、五项设计原则、示例与评测建议。原文内部评测图没有提供完整公开样本、代码与误差分析本文未补造图上的精确收益数字。Anthropic.Tool evaluation.官方 Cookbook。核对任务运行、调用计时与结果汇总部分网页代码可能更新资料核对日期为 2026-10-03。本文没有运行其 API 示例。