智能体工具描述决定成败:五条原则让 Claude 少返工
Agent 接入 API 后经常选错工具、填错参数,或被冗长返回值淹没。这篇拆解 Anthropic 将工具视为契约的思路,归纳五条可执行原则,并用工具声明示例、原型与评估闭环说明:如何让 Claude 更准确地选择工具、传递参数并继续行动。
文章目录
给 Agent 接工具,看起来只是把 API 包一层:模型读描述、发参数、收结果。麻烦是它可能选错工具、填错参数,或被冗长返回淹没。Anthropic 将工具视为与 Agent 的契约;工具描述上的小改动,也足以让 Claude 在 SWE-bench 上刷新纪录。
工具质量不只看“能不能返回”,还看 Agent 是否知道何时用、要传什么、结果代表什么。描述越含糊,能力越多,误调用和返工越多。这套做法可拆成五条原则,并串起声明、原型、评估与联调。
1、工具描述不是 API 文档的复制品
1、工具描述不是 API 文档的复制品 · AI 生成示意图
API 文档通常面向开发者,解释地址、字段和返回结构;Agent 更需要选择依据。描述若只是复制说明书,模型可能知道字段,却不知道哪个工具适合当前任务。
契约要回答三件事:何时调用、缺失信息怎么办、结果如何理解并继续使用。好的描述压缩决策信息,而不是堆叠接口细节。
一般可按这张表检查描述是否仍停留在说明书阶段:
| 检查维度 | 只写 API 用法 | 面向 Agent 的描述 |
|---|---|---|
| 目标 | 说明接口能做什么 | 说明哪类任务应选择它 |
| 参数 | 罗列字段与类型 | 说明字段语义、来源和缺失时处理 |
| 返回 | 粘贴原始响应 | 标注结果含义、噪声边界与后续动作 |
| 失败 | 只给错误信息 | 要求 Agent 不猜测,澄清后再调用 |
2、五条原则,把调用规则写进描述
2、五条原则,把调用规则写进描述 · AI 生成示意图
结合原文强调的原型、评估和共同迭代,可把写作要求归纳为五条。
一、围绕任务写用途。 说明它解决哪类任务、如何与其他工具区分,而不是只说“调用某个接口”。
二、让参数要求可判定。 写清字段来自用户、工具结果还是系统上下文;用户没给的信息先澄清,不让模型自行补全。
三、定义返回语义。 说明哪些内容相关、哪些可忽略,以及结果支持什么后续动作。
四、先做最小原型。 用工作流跑通调用链,观察选择、参数和结果理解在哪偏掉,再改描述。
五、形成评估与联调闭环。 围绕已暴露的问题调整描述,用同一组任务复测,让工具实现与 Agent 一起迭代。
下面是一个语法合法、可作为工具声明起点的 JSON 示例;实际字段名称与接入格式以所用规范及原文为准:
{
"name": "lookup_issue",
"description": "查询用户明确指定的代码仓库问题。仅在需要定位问题或核对上下文时调用;缺少仓库标识或问题标识时先向用户询问,不自行猜测。返回内容是定位依据,不等同于修复方案。",
"input_schema": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "用户明确提供的仓库标识"
},
"issue": {
"type": "string",
"description": "用户明确提供的问题标识,不得自行补造"
}
},
"required": ["repository", "issue"],
"additionalProperties": false
}
}
它把调用时机、前提、缺失处理和结果用途写进契约。描述的价值不在字数,而在能否减少决策歧义。
3、原型、评估、联调:让描述形成闭环
原型不是搬运全部 API,而是先定位错误。工具选错,需要补选择边界;参数填错,需要补字段来源与缺失规则;结果读错,需要补返回语义。观察错因,比单纯拉长描述更有用。
评估不能只看请求是否成功。返回成功只说明传输完成,不代表任务完成;还要检查 Agent 是否在正确时机调用、是否忠实传递用户信息、是否根据结果采取合理下一步。
可分别使用改前与改后的描述跑同一组任务,对比失败类型。若错误减少且没有产生新的误解,再把改动合入实际工具。具体评测集和判分方式以原文为准。
联调时,把频繁误选、反复追问和拿到结果后停滞都当成反馈:它们分别指向用途不清、参数约束不足或返回语义模糊。再回到原型与评估,让工具实现与 Agent 的使用方式一起迭代。
写在最后
工具描述决定 Agent 是否理解一项能力,而不只是看见接口。
把用途、参数和返回语义写清,才能减少误选、错填与信息淹没。
原型暴露问题,评估验证改动,联调让描述跟上真实使用。
值得长期维护的,是“接口实现、工具契约、评估用例”组成的闭环。
我的判断:工具描述会逐渐成为 Agent 工程中与代码同等重要的接口资产。
相关阅读
想把这套流程装到自己服务器上?阿凡达提供一次性的私有化部署与出海模型接入服务,说明与报价见站内服务页:查看技术服务。
文中链接
整理自本文的外部链接,请以来源页面说明为准。