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 当前股价” | 选择股票行情工具 |
| 不该调用 | “帮我解释什么是股票” | 直接回答，不调用工具 |
| 边界场景 | “写一封邮件给客户，但先别发” | 不调用发送工具 |
| 参数缺失 | “帮我订机票” | 先追问日期和城市 |
如果模型经常误选工具，优先修改描述中的适用/不适用边界。
测试用例应该覆盖三种情况：
- 正确调用：明显需要该工具的输入
- 正确跳过：不需要该工具的输入
- 边界模糊：容易误判的边缘案例
小结
| 要素 | 作用 | 常见错误 |
|---|---|---|
| 一句话功能 | LLM 的第一判断依据 | 写成技术术语而非自然语言 |
| 适用场景 | 引导正向使用 | 缺失或太笼统 |
| 不适用场景 | 防止误调用（效果最显著） | 大多数人忘记写 |
| 参数描述 | 减少参数格式错误 | 只有类型没有示例 |
| 返回值格式 | 帮助 LLM 解读结果 | 完全缺失 |
| 注意事项 | 防止危险操作 | 安全相关工具常遗漏 |
💡 终极建议：每写完一个工具描述，把自己代入 LLM 的角色读一遍——如果你只能看到这些文字，能不能判断什么时候该用这个工具？如果不能，继续优化。