# Agent 调错工具，先查你写的工具描述

> Anthropic 把详细描述列为影响工具表现的首要因素，本文以一家物流公司的 API 为例逐步改写。

原文: https://fdetimes.net/zh/guides/writing-tool-definitions-for-customer-apis/

Anthropic 的工具调用文档指出，详细的描述是决定工具表现好坏的首要因素，而且远超其他因素。所以在换模型、换框架之前，先回头看看自己写的那几句话。

原因很简单。按照 Hugging Face Agents 课程的说法，工具描述会插入系统提示词，模型只知道写在那里的内容。Paragon 描述的也是同一机制：模型根据每个工具附带的名称、描述和输入来选择工具。

客户有一个内部 API，你需要把它封装起来供 Agent 使用。本指南用一个假设的例子逐步演示，每一步之后都有一项检查。

## 要做什么，需要准备什么？

假设客户是一家名为 Acme 的物流公司。它有三个端点：按 ID 查询订单、按电话号码查找订单、取消订单。目标是让客服 Agent 在用户用自然语言提问时，以正确的参数调用正确的端点。

先记住函数调用的工作方式。Prompting Guide 把它描述为把自然语言转换成有效 API 调用的方法，但模型只以 JSON 形式生成参数，真正调用 API 是你的代码的事。你需要熟悉 JSON Schema，手头有客户的 API 文档，并在模型和 API 之间放一层小小的封装。

## 第 1 步：看清初稿为什么失败

直接照搬端点名称时，常会写出这样的定义：

```json
{
  "name": "get",
  "description": "获取订单",
  "input_schema": {
    "type": "object",
    "properties": { "order": { "type": "string" } },
    "required": ["order"]
  }
}
```

名称“get”没说明获取的是什么，也没说明来自哪个系统。参数“order”可能是订单 ID，可能是整个订单对象，也可能是序号。只有几个字的描述，完全没说何时该用这个工具。

Anthropic 工程博客的一篇文章建议使用无歧义的参数名，比如用 `user_id` 而不是 `user`。这里同理，`order_id` 比 `order` 清楚得多。

**检查：**把定义念给一位从没见过 Acme API 的同事听。如果对方问“order 是什么？”，模型也会同样误解。

## 第 2 步：合并端点，名称加服务前缀

很多人的第一反应是每个端点对应一个工具。Anthropic 的文档建议反过来：把相关操作合并成更少的工具，用一个 action 参数区分，因为工具更少、能力更强，模型选择时需要权衡的就更少。

同一份文档还建议在名称前加服务前缀，例如 `github_list_prs` 或 `slack_send_message`，这样工具库变大后选择依然清晰。

用到 Acme 上，三个端点合并成一个名为 `acme_orders` 的工具，其 `action` 取三个值之一：`get`、`search` 或 `cancel`。如果 Agent 以后增加了 CRM 系统的工具，`acme_` 前缀能让人一眼分清。

**检查：**列出 Agent 目前拥有的所有工具。如果要仔细读两个工具才能看出区别，就合并或重命名。

## 第 3 步：像给新同事交代工作那样写描述

Anthropic 建议，写描述就像向团队新人解释这个工具，把内部人员习以为常的背景都讲清楚。其文档列出了应包含的内容：工具做什么，何时用、何时不用，每个参数的含义，以及注意事项。

每个工具至少写 3-4 句，工具复杂就写更多。注意每个 JSON 字符串必须在一行内；描述中需要换行时，使用转义符 `\n`。

```json
{
  "name": "acme_orders",
  "description": "在 Acme 系统中查询、查找或取消配送订单。用户提供了订单 ID 时，使用 action='get'；只有收件人电话号码时，使用 action='search'。仅当用户明确表示要取消时才使用 action='cancel'，且只适用于尚未出库的订单。\n\n不要用此工具回答运费或赔偿申请相关的问题。订单 ID 格式为 ORD- 加 8 位数字。",
  "input_schema": {
    "type": "object",
    "properties": {
      "action": { "type": "string", "enum": ["get", "search", "cancel"] },
      "order_id": { "type": "string", "description": "订单 ID，格式为 ORD-12345678。get 和 cancel 必填。" },
      "recipient_phone": { "type": "string", "description": "收件人电话号码，仅限数字。用于 search。" }
    },
    "required": ["action"]
  }
}
```

订单 ID 格式、“尚未出库”规则和排除赔偿申请，都是为本例虚构的。在真实客户那里，这类规则要靠你从人那里问出来，它们通常存在于运营团队的脑子里，而不在 API 文档里。

**检查：**描述里有没有一句以“不要用……”开头的话？

## 第 4 步：为难以填写格式的输入加示例

对于输入复杂或对格式敏感的工具，Anthropic 的 API 提供可选字段 `input_examples`。每个示例都必须符合 `input_schema`，不符合会返回 400 错误。示例还会额外消耗提示词 token，所以只在某种格式确实经常填错时才用。下面的片段做了简化：

```json
"input_examples": [
  { "action": "get", "order_id": "ORD-20481234" },
  { "action": "search", "recipient_phone": "0901234567" }
]
```

**检查：**发送请求。如果收到 400 错误，很可能是某个示例与 schema 不符，比如字段名写错，或 action 取值不在 enum 中。

## 第 5 步：响应和错误同样是提示词

API 返回的一切都会回到模型的上下文中。Anthropic 工程博客建议工具只返回高价值信息，并建议对大体量数据做分页、过滤和截断。同一篇文章还指出，可以改写错误信息，明确说明需要修正什么，帮助模型在下一次调用时调整。

下面的封装做了简化。它区分了两种不同的失败：ID 格式错误（在封装层拦截，不调用 API），以及 ID 格式正确但不存在（API 返回 404）。

```python
import re

# 简化版：模型与客户 API 之间的封装层
ORDER_ID_PATTERN = re.compile(r"^ORD-\d{8}$")

def run_acme_orders(args):
    if args["action"] in ("get", "cancel"):
        order_id = args.get("order_id", "")
        if not ORDER_ID_PATTERN.match(order_id):
            return ("order_id 格式错误：必须是 ORD- 加 8 位数字，"
                    "例如 ORD-20481234。请再次向用户询问订单 ID。")
    resp = call_customer_api(args)  # 你自己的 HTTP 函数
    if resp.status == 404:
        return ("ID 格式正确，但没有找到对应订单。\n\n"
                "如果用户有收件人电话号码，"
                "请改用 action='search' 再次调用。")
    order = resp.json()
    return {"order_id": order["id"], "status": order["status"],
            "eta": order["eta"]}  # 丢弃模型用不到的内部字段
```

与一句光秃秃的“404 Not Found”相比，这里的每条信息都把模型引向不同的路径：ID 格式错误就重新询问，订单不存在就改用电话号码查找。把响应精简到三个字段，模型就不必在几十个内部字段里翻找。

**检查：**做两次测试调用，一次用格式错误的 ID，一次用格式正确但不存在的 ID。模型在两种情况下的下一次调用应该不同，而不是拿同一个错误 ID 反复重试。

## 第 6 步：别凭感觉，跑评测

Anthropic 指出，即使是对描述的细微改进，也可能大幅提升效果。这一点是双向的：改一句话可能让效果变好，也可能弄坏一个原本正常的用例。

实用的做法是从客户的客服记录中整理出约 20 个问题，事先为每个问题记下正确的工具、action 和参数。每次修改描述后，重跑整套问题，统计答对的数量。

**要点:** 描述就是代码：改了它，就要重跑测试。

## 要避开的坑

一个常见错误是用 OpenAPI 自动生成工具后原样使用。这恰好会导致 Anthropic 文档警告的情况：几十个工具，每个端点一个，描述照搬开发者注释，短到模型无法区分。另一个错误是参数名仍叫 `id`、`user` 或 `data`，且不说明格式。

也不要把 API 的原始 JSON 连同错误原样返回，然后奇怪模型为什么总在重复同一个错误调用。

## 这项技能在客户现场是什么样子？

在现场，难点很少是 JSON 语法，而是坐下来和运营团队一起，问出“订单出库后还能取消吗？”这类问题的答案，因为这些答案正是描述里“何时不用”那句话的内容。

如果你的目标是前线部署工程师（FDE）岗位，留意那些提到工具调用、Agent 集成或直接对接客户 API 的岗位描述。

简历上别只写“将 LLM 与内部 API 集成”。要写清你把多少个端点合并成了多少个工具，以及每轮修改描述后，评测集上的准确率如何变化。这样一组前后对比的数字，能让招聘方看到你能做客户愿意付钱的工作。

下次 Agent 调错 API 时，先别急着换模型。打开描述，像新同事入职第一天那样读一遍。

**本周动手试试:**

- 挑一个你在用的 API，按本文模板写一份工具定义，描述至少 4 句，并写清何时不应使用该工具。
- 整理 20 个真实用户问题，为每个问题记下正确的工具和参数，然后在每次修改描述前后统计模型答对了多少。
- 改写该 API 最常见的三条错误信息，让人一读就知道下一次调用必须修正什么。

## 信源

- [What are Tools? - Hugging Face Agents Course](https://huggingface.co/learn/agents-course/en/unit1/tools)

- [What is Tool Calling in Agents? (Paragon)](https://www.useparagon.com/blog/ai-building-blocks-what-is-tool-calling-a-guide-for-pms)

- [Function Calling with LLMs | Prompt Engineering Guide](https://www.promptingguide.ai/applications/function_calling)

- [Define tools - Claude API Docs](https://platform.claude.com/docs/en/docs/agents-and-tools/tool-use/implement-tool-use)

- [Writing effective tools for agents — with agents (Anthropic Engineering)](https://www.anthropic.com/engineering/writing-tools-for-agents)
