智能体工具描述决定成败:五条原则让 Claude 少返工

Agent 接入 API 后经常选错工具、填错参数,或被冗长返回值淹没。这篇拆解 Anthropic 将工具视为契约的思路,归纳五条可执行原则,并用工具声明示例、原型与评估闭环说明:如何让 Claude 更准确地选择工具、传递参数并继续行动。

文章目录

原文:一个小改动,让 Claude 在 SWE-bench 上刷新纪录:工具描述有多重要

给 Agent 接工具,看起来只是把 API 包一层:模型读描述、发参数、收结果。麻烦是它可能选错工具、填错参数,或被冗长返回淹没。Anthropic 将工具视为与 Agent 的契约;工具描述上的小改动,也足以让 Claude 在 SWE-bench 上刷新纪录。

工具质量不只看“能不能返回”,还看 Agent 是否知道何时用、要传什么、结果代表什么。描述越含糊,能力越多,误调用和返工越多。这套做法可拆成五条原则,并串起声明、原型、评估与联调。

1、工具描述不是 API 文档的复制品

1、工具描述不是 API 文档的复制品(AI 生成示意图)

1、工具描述不是 API 文档的复制品 · AI 生成示意图

API 文档通常面向开发者,解释地址、字段和返回结构;Agent 更需要选择依据。描述若只是复制说明书,模型可能知道字段,却不知道哪个工具适合当前任务。

契约要回答三件事:何时调用、缺失信息怎么办、结果如何理解并继续使用。好的描述压缩决策信息,而不是堆叠接口细节。

一般可按这张表检查描述是否仍停留在说明书阶段:

检查维度 只写 API 用法 面向 Agent 的描述
目标 说明接口能做什么 说明哪类任务应选择它
参数 罗列字段与类型 说明字段语义、来源和缺失时处理
返回 粘贴原始响应 标注结果含义、噪声边界与后续动作
失败 只给错误信息 要求 Agent 不猜测,澄清后再调用

2、五条原则,把调用规则写进描述

2、五条原则,把调用规则写进描述(AI 生成示意图)

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 工程中与代码同等重要的接口资产。

相关阅读

想把这套流程装到自己服务器上?阿凡达提供一次性的私有化部署与出海模型接入服务,说明与报价见站内服务页:查看技术服务。

文中链接

整理自本文的外部链接,请以来源页面说明为准。

智能体工具描述决定成败:五条原则让 Claude 少返工 · 阿凡达博客