# 3.4 工具描述的编写技巧

> 🎯 **本节目标**：掌握让 LLM "听懂"工具的描述编写方法——这是 Agent 工程中 **投入产出比最高** 的技能之一。

---

## 为什么这一节单独拿出来讲？

因为**描述质量直接决定了 Agent 的智商**，而大多数开发者在这里花的时间远远不够。

一个真实的数据点：

> 同样的 GPT-4.1 模型 + 同样的工具代码：
> - 模糊描述 → 工具调用准确率 ~60%
> - 精心优化的描述 → 工具调用准确率 ~90%+
>
> 差距来自哪里？完全来自 `description` 字段的写法。

LLM 选择工具时看不到你的函数实现——它只能看到你写的 `description`。**这段文字就是 LLM 理解工具的唯一窗口。**

---

## 六要素检查清单

### 1️⃣ 一句话功能说明（最重要）

LLM 扫描工具列表时首先看的就是第一句话。

一句话功能说明要避免两个极端：

| 写法 | 问题 | 更好的写法 |
|---|---|---|
| “处理文本” | 太模糊，不知道何时调用 | “总结用户提供的长文本，输出 3 条核心观点” |
| “基于 Transformer 的 NLP 管道” | 太技术化，和调用决策无关 | “从商品评论中提取用户抱怨的主要问题” |

工具描述首先服务于模型的“选择判断”，不是服务于人类炫技。

**公式：动词 + 操作对象 + 核心能力边界**

### 2️⃣ 适用场景（何时用）

适用场景要写清楚“什么时候应该调用”。例如股票行情工具可以说明：

- 获取当前股价和涨跌幅。
- 查询市值、市盈率等基本面指标。
- 比较多只股票的实时行情。

这样模型遇到“苹果现在多少钱”“特斯拉今天涨了吗”时，才知道该调用它。

### 3️⃣ 不适用场景（何时不用的）

> 这是最容易被忽略、但效果最显著的要素。

不适用场景同样重要，因为它能减少误调用。

例如 `send_email` 工具应该明确：

- 不用于写邮件草稿。
- 不用于查询收件箱。
- 不用于总结邮件内容。
- 仅在用户明确要求发送，并提供收件人和正文后调用。

对高风险工具来说，“何时不用”往往比“何时用”更关键。

**原理**：明确告诉 LLM "什么时候不该用"，能大幅降低误调用率。这在工具数量增多时尤为关键。

### 4️⃣ 参数描述

不只是写类型，还要写**格式要求和示例值**：

参数描述要让模型知道每个参数应该填什么，而不只是写类型。

| 参数 | 不充分描述 | 更好的描述 |
|---|---|---|
| `symbol` | 股票代码 | 股票代码；美股用 `AAPL`，A 股用 `600519.SH` |
| `date` | 日期 | 查询日期，格式为 `YYYY-MM-DD`，默认今天 |
| `limit` | 数量 | 返回结果条数，范围 1～20，默认 5 |

描述越具体，模型生成的参数越稳定。

### 5️⃣ 返回值说明

告诉 LLM 工具返回什么格式的数据，方便它解读结果并组织回答：

返回值说明能帮助模型正确解释工具结果。建议写清楚：

| 信息 | 作用 |
|---|---|
| 返回字段 | 模型知道每个字段代表什么 |
| 单位 | 避免把美元、人民币、百分比混淆 |
| 为空时的含义 | 区分“没查到”和“系统错误” |
| 后续建议 | 告诉模型如何把结果转成用户可读答案 |

### 6️⃣ 限制与注意事项

限制与注意事项要直接写在描述里，尤其是高风险工具。

例如 SQL 查询工具应明确：

- 只允许查询，不允许写入、删除或修改数据。
- 单次最多返回固定条数。
- 禁止访问敏感表。
- 查询失败时返回可解释错误，而不是让 Agent 猜测。

这些限制会成为模型选择和执行工具时的边界。

---

## 多工具场景：如何区分相似工具

当 Agent 有多个功能相近的工具时，描述中要**强调差异化特征**：

多个相似工具并存时，描述的重点是“边界差异”。

| 工具 | 适合 | 不适合 |
|---|---|---|
| `search_web` | 查找公开网页摘要和链接 | 深入阅读网页全文 |
| `browse_page` | 打开指定网页并提取内容 | 泛泛搜索未知资料 |
| `query_knowledge_base` | 查询企业内部知识 | 获取互联网最新消息 |

如果边界不清，模型会在相似工具之间随机选择，导致调用链不稳定。

注意每个描述中都包含了 **"不用于什么"** 来避免混淆。

---

## 描述模板：直接可用

下面是一个通用模板，覆盖了所有要素：

可以用一个固定模板编写工具描述：

| 部分 | 要回答的问题 |
|---|---|
| 一句话功能 | 这个工具做什么？ |
| 适用场景 | 用户提出什么需求时该用？ |
| 不适用场景 | 哪些相似需求不该用？ |
| 参数说明 | 每个参数如何填写？ |
| 返回格式 | 工具会返回什么？ |
| 风险限制 | 有哪些权限、频率、安全边界？ |

写工具描述时，优先保证模型能做出正确选择，而不是追求代码形式优雅。

---

## 如何测试描述质量？

不要猜——用数据说话：

测试工具描述质量，可以准备一组“该用”和“不该用”的用户问题。

| 测试类型 | 示例 | 期望结果 |
|---|---|---|
| 应该调用 | “查一下 AAPL 当前股价” | 选择股票行情工具 |
| 不该调用 | “帮我解释什么是股票” | 直接回答，不调用工具 |
| 边界场景 | “写一封邮件给客户，但先别发” | 不调用发送工具 |
| 参数缺失 | “帮我订机票” | 先追问日期和城市 |

如果模型经常误选工具，优先修改描述中的适用/不适用边界。

测试用例应该覆盖三种情况：
1. **正确调用**：明显需要该工具的输入
2. **正确跳过**：不需要该工具的输入
3. **边界模糊**：容易误判的边缘案例

---

## 小结

| 要素 | 作用 | 常见错误 |
|------|------|---------|
| 一句话功能 | LLM 的第一判断依据 | 写成技术术语而非自然语言 |
| 适用场景 | 引导正向使用 | 缺失或太笼统 |
| **不适用场景** | **防止误调用（效果最显著）** | 大多数人忘记写 |
| 参数描述 | 减少参数格式错误 | 只有类型没有示例 |
| 返回值格式 | 帮助 LLM 解读结果 | 完全缺失 |
| 注意事项 | 防止危险操作 | 安全相关工具常遗漏 |

> 💡 **终极建议**：每写完一个工具描述，把自己代入 LLM 的角色读一遍——如果你只能看到这些文字，能不能判断什么时候该用这个工具？如果不能，继续优化。

---

*下一节：[3.5 实战：搜索引擎 + 计算器 Agent](./05_practice_search_calc.md)*
