<!-- title: 工具描述工程：部署时找回40%准确率 -->

# 工具描述工程：把API文档重写成模型能读的提示词

## 概述

当你的Agent调错工具、填错参数、幻觉出不存在的函数时，第一反应通常是换更强的模型、加更多示例、或微调。但2026年一组被反复印证的发现指向了一个更便宜、更可移植的杠杆——**工具描述本身怎么写**。把人类导向的API文档在**部署时**用LLM重写成Agent优化的描述，能找回20%–40%的函数调用准确率；ICLR 2026的"推理陷阱"论文更揭示了一个反直觉结论：增强推理能力的RL训练反而会让工具幻觉变多，说明瓶颈常常不在模型聪明度，而在描述清晰度。本文以Intuit的Trace-Free+框架、Anthropic的"用Agent优化自己的工具"方法、以及BFCL v4/AgentHallu评测为骨架，拆解工具描述工程（Tool Description Engineering）这门被多数团队当作"写文档"而低估的独立工程学科。

## 核心发现对比

| 维度 | 微调Agent | RAG工具检索 | 提示词/示例增强 | 工具描述工程 |
|------|-----------|-------------|-----------------|--------------|
| 介入时机 | 训练时 | 运行时 | 运行时 | 部署时（离线改写） |
| 准确率收益 | 高但代价大 | 选对≠调对 | 边际递减 | 恢复20%–40%损失 |
| 跨模型可移植 | 差 | 好 | 中 | **强**（描述与模型解耦） |
| 跨工具可移植 | 差 | 好 | 差 | **强**（对未见工具有效） |
| 是否需执行轨迹 | 需大量trace | 不需 | 需人工示例 | Trace-Free+免轨迹 |
| Token成本 | 0 | 检索开销 | 上下文膨胀 | 描述占用固定预算 |
| 上手门槛 | 高（GPU/数据） | 中 | 低 | 低（用LLM改写） |

---

## 深度分析

### 一、被误读的本质：工具描述不是文档，是注入模型的提示词

绝大多数团队把工具的JSON Schema当API文档来写——给人看、给自己看、给未来的维护者看。但**模型上下文窗口里那个description字段，本质上就是一段被拼进系统提示词的文本**。它和人读不读它无关，唯一重要的是：模型在决定"调不调、调哪个、参数填什么"的那一刹那，能否从这段文字里提取出正确信号。

这是"Schema即提示词"（Schema-as-Prompt）的认知翻转。一篇2026年的生产实践文章直接点破：工具注册表"不再只是文档的那一刻，就是你给Agent可调用权限的那一刻"。换句话说，当Agent可以调用工具，工具描述就从文档变成了**安全边界和爆炸半径**（blast radius）——每个参数描述的模糊，都是一个潜在的误调用入口。这也解释了为什么"写好描述"不是文档质量活，而是Agent可靠性工程的核心一环。

### 二、Trace-Free+：部署时重写找回20%–40%准确率

把上面的认知推向工程化的是Intuit AI Research的论文《Learning to Rewrite Tool Descriptions for Reliable LLM-Agent Tool Use》（arXiv 2602.20426）。它的核心贡献是**Trace-Free+**框架：在部署时（而非训练时），用学习到的策略把人类导向的API文档重写成Agent优化的工具描述，全程不需要收集运行时执行轨迹。

关键数据点：在StableToolBench和RestBench上，重写后的描述对**模型从未见过的工具**也有一致的准确率提升，且展现出强跨域能力。第三方解读给出的量化区间是——部署时重写可以找回**20%–40%**因API文档写得差而损失的函数调用准确率。这之所以重要，是因为它把"提升工具使用"从一个"改模型/微调"的重活，变成了一个"改文本/可移植"的轻活：同一份重写后的描述，可以跨模型、跨工具迁移，而微调出的Agent一旦换底座就归零。对于追求ROI的团队，这是描述工程最强的卖点。

### 三、推理陷阱：模型越会推理，工具幻觉反而越多

如果说上一个论据说明"改描述比改模型划算"，ICLR 2026的《The Reasoning Trap: How Enhancing LLM Reasoning Amplifies Tool Hallucination》则给出了一个更扎心的结论——**改模型甚至可能帮倒忙**。该研究发现，用于增强LLM推理能力的强化学习训练（正是那些让模型"更聪明"的训练），会**同时放大工具调用幻觉**。

机制上不难理解：推理能力强的模型更倾向于"脑补"——当一个工具描述模糊或工具不存在时，能力弱的模型倾向坦白承认"我没有这个工具"，而能力强的模型会基于它对世界的过度推理，自信地编造出一个看似合理的工具名或参数组合。这个发现对工程决策的含义是颠覆性的：在很多场景下，砸钱上更强的推理模型不会修复工具误调用，反而会让幻觉更隐蔽、更自信。**正确的解法是把模糊性从工具描述里消除**，让模型没有"推理空间"去脑补。这正是描述工程而非模型升级成为正解的底层逻辑。

### 四、负向描述：告诉模型"我不是谁"比"我是谁"更重要

进入实操层，描述工程最反直觉也最有效的一招是**负向标准（Negative Criteria）**。多数工具描述只写"我做什么"——`send_email`：发送邮件。但在多工具并存时，模型选错的根因往往是它只知道每个工具"是"什么，不知道彼此"不是"什么。`send_email`和`send_message`、`send_notification`、`create_draft`之间的边界，如果不写出来，模型只能猜。

负向描述的写法是在description里明确**何时不调用此工具**：

```json
{
  "name": "send_email",
  "description": "发送正式邮件到外部收件人邮箱地址。仅用于对外正式沟通。"
              "不要用于：内部即时消息（用send_message）、"
              "应用内通知（用send_notification）、仅保存草稿（用create_draft）。"
              "需要明确的收件人邮箱，不要猜测或使用默认地址。"
}
```

最后一条"参数来源规则"同样关键——明确参数从哪里取、禁止编造默认值，能直接砍掉一类参数幻觉。这三招（单一用途函数名 + 负向标准 + 参数来源规则）是CallSphere总结的2026年工具调用提示词模式里ROI最高的几个，且全部落在描述文本上，不动模型。

### 五、约束即护栏：用Schema类型系统封堵参数幻觉

描述工程不只是写自然语言，还包括把"约束"从模糊的文字下沉到**机器可校验的Schema类型系统**里。enum、数值range、required与optional、正则格式——这些不是给文档读者看的装饰，而是模型在生成参数时必须通过的硬闸门。一个`status`参数写成自由字符串，模型可能填"pending"；写成`enum:["draft","sent","archived"]`，它在解码阶段就被约束在合法集合内。

这套思路和"结构化解码驯服函数调用"一脉相承，但描述工程的独特视角在于：**约束本身就是一种压缩的、无歧义的描述**。与其在description里写"状态必须是草稿、已发送或归档之一"，不如直接用enum声明——前者是给人读的提示词，后者是给解码器读的硬约束。当描述能下沉为约束时，应优先下沉；只有当语义无法被类型表达（如"不要猜默认值"这种意图）时，才留在自然语言里。这种分层是描述工程区别于"写文档"的专业所在。

### 六、MCP时代的爆炸半径：从十个工具到几百个描述

Model Context Protocol让一个Agent可以挂载**几百个工具**，每个工具的description都作为提示词注入上下文。这在工程上彻底改变了描述质量的权重：当工具只有十个时，一个写得差的描述可能只占10%的误调用风险；当工具有三百个时，每个描述都是一扇半掩的门，描述质量直接等于**整个系统的攻击面和误调用面**。

这正是"工具Schema即爆炸半径"论述的现实落点。在MCP语境下，描述工程必须升级为一套**描述治理（Description Governance）**流程：工具描述的命名规范、负向标准模板、约束下沉规则、token预算控制（几百个描述会吃掉惊人比例的上下文窗口），以及对工具描述变更的回归评测。没有这套治理，MCP赋予的"工具自由"会迅速退化为"工具混乱"——模型在三百个相似描述里选错的概率，比在十个里选错高得多。这也是为什么Anthropic官方专门写了一篇"用Agent优化自己的工具"来应对规模化问题。

### 七、Anthropic方法：让Claude优化自己的工具

Anthropic的工程博客《Writing effective tools for agents》给出了一个可复制的闭环：**用模型来优化模型要用的工具描述**。流程是先把当前工具描述喂给Claude，让它扮演Agent尝试调用，观察哪些描述导致选错或填错，再让Claude针对这些薄弱点重写描述，最后用eval验证改写是否真的提升了调用准确率。

这个方法的价值在于它把描述工程变成了一个**数据驱动、可评测、可自动化**的过程，而不是依赖工程师拍脑袋写文档。它和Trace-Free+形成互补：Trace-Free+是离线的、学习型的批量重写；Anthropic方法是交互式的、Agent自驱的迭代优化。两者共同指向一个趋势——**描述工程正在工具化**，未来"描述优化器"会像代码格式化器一样成为Agent开发的标准组件，而手写API文档直接给模型用的时代正在结束。

### 八、评测闭环：用AgentHallu和BFCL v4量化描述收益

没有评测，描述工程就是玄学。2026年评测栈已经给出两把尺子。**BFCL v4**（Berkeley Function Calling Leaderboard）覆盖从简单函数到多轮多工具并行的全谱系，是衡量"调得准不准"的工业标尺；而**AgentHallu**则把工具幻觉拆成五个可归因的类别——Planning、Retrieval、Reasoning、Human-Interaction等，让你能定位"到底哪一类幻觉在发作"。

把这两者组合，描述工程的收益就能被精确度量：重写前跑一次BFCL + AgentHallu，重写后再跑一次，对比"选择准确率""参数准确率"和"幻觉类别分布"的变化。一个可参考的工作流是：AgentHallu定位主要幻觉类别 → 针对该类别用负向描述/约束下沉修复 → BFCL验证整体准确率提升。这个闭环让"描述工程"从经验主义走向工程主义，也让20%–40%的收益区间成为可复现而非偶然的数字。

---

## 工具描述工程闭环架构

```mermaid
flowchart TD
    A[人类导向API文档<br/>给人看] --> B[部署时重写器<br/>Trace-Free+ / Agent自驱]
    B --> C[Agent优化描述<br/>负向标准+约束下沉]
    C --> D[注入模型上下文<br/>作为提示词]
    D --> E{模型决策}
    E -->|选错/填错/幻觉| F[失败归因<br/>AgentHallu 5类]
    E -->|调用成功| G[执行工具]
    F --> H[BFCL v4 量化<br/>准确率基线]
    H -->|薄弱点反馈| B
    G --> H

    subgraph 反思[认知翻转]
        T1[旧认知: 描述=文档]
        T2[新认知: 描述=提示词+安全边界]
        T1 -.->|翻转| T2
    end

    style B fill:#ffe4b5
    style C fill:#b5e4ff
    style F fill:#ffb5b5
    style H fill:#d5ffb5
```

## 推荐方案

**场景一：工具数量<20的小型Agent。** 先做人工描述工程——为每个工具加负向标准、下沉能下沉的约束、写清参数来源规则。这是投入产出比最高的一步，零成本、当天见效。别急着上微调或RAG。

**场景二：工具数量20–200的中型系统（多数企业Agent）。** 人工写不过来，引入**Agent自驱改写**（Anthropic方法）：让模型读自己的工具集，找出薄弱描述批量重写，配合BFCL评测。同时建立描述治理规范，控制token预算。这是当前性价比最优的工业解。

**场景三：MCP驱动的几百工具超大系统。** 必须建立完整的描述治理流水线：统一命名规范 + 模板化负向标准 + 约束自动下沉 + 离线批量重写（Trace-Free+） + AgentHallu归因 + BFCL回归。把"工具描述"当作和"代码"一样需要版本管理、评测、回归的一等公民。

**场景四：遭遇"推理陷阱"——换更强模型反而幻觉变多。** 停止升级模型，转而用AgentHallu诊断幻觉类别，几乎一定是描述模糊给了模型脑补空间。此时描述工程是唯一正确的杠杆。

**一条普适原则：** 当工具调用出问题，优先怀疑描述，其次怀疑示例，最后才怀疑模型。因为描述是可移植、低成本、可评测的；而模型升级昂贵、不可移植、且在推理陷阱下可能帮倒忙。把描述工程当作Agent可靠性栈的地基，是2026年最具ROI的工程决策之一。

---

## 参考来源

1. [Learning to Rewrite Tool Descriptions for Reliable LLM-Agent Tool Use (arXiv 2602.20426)](https://arxiv.org/abs/2602.20426) — Intuit AI Research的Trace-Free+框架，部署时重写工具描述恢复20%–40%准确率，StableToolBench/RestBench验证跨工具迁移能力。
2. [Paper of the Week — Learning to Rewrite Tool Descriptions (Stochastic Sandbox)](https://stochasticsandbox.com/posts/paper-of-the-week-2026-04-30/) — 对Trace-Free+论文的量化解读，给出20%–40%准确率恢复区间及部署时vs训练时的对比。
3. [The Reasoning Trap: How Enhancing LLM Reasoning Amplifies Tool Hallucination (ICLR 2026)](https://shiporskip.io/news/iclr-2026-reasoning-trap-llm-tool-hallucination-agents-paper-2026) — 增强推理的RL训练反而放大工具幻觉的反直觉发现，论证瓶颈常在描述而非模型。
4. [Writing effective tools for AI agents — using AI agents (Anthropic Engineering)](https://www.anthropic.com/engineering/writing-tools-for-agents) — Anthropic官方方法：用Claude自我优化工具描述并做eval，应对MCP数百工具规模化。
5. [Tool Schema Design Is Your Blast Radius (Tian Pan)](https://tianpan.co/blog/2026-05-02-tool-schema-design-blast-radius-security-boundary) — 工具Schema即安全边界与爆炸半径，论述描述从文档到攻击面的认知翻转。
6. [Prompt Engineering for Tool-Calling Agents: 10 Patterns (CallSphere)](https://callsphere.ai/blog/prompt-engineering-tool-calling-agents-10-patterns-2026) — 实操模式：单一用途函数名、负向标准、参数来源规则等描述工程技巧。
7. [Berkeley Function Calling Leaderboard (BFCL) V4](https://gorilla.cs.berkeley.edu/leaderboard.html) — 工业级函数调用评测标尺，用于量化描述改写的准确率收益。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)