<!-- title: 工具描述工程：描述决定调用成败 -->

# 工具描述工程：描述决定调用成败

## 概述

2026 年中，Function Calling 的战场已经从"模型会不会调工具"悄然上移到"工具的定义写得怎么样"。一个反直觉的结论正在工程界形成共识：**MCP server 的质量，80% 由工具 schema 决定，而不是由后端逻辑决定**。原因在于——从模型视角看，成百上千条工具定义本身就是 prompt 的一部分，常驻在上下文窗口里。Anthropic 工程博客披露，优化前工具定义吞噬了 **134K tokens**，引入 MCP Tool Search 后压到约 **5K**，降幅 85%；一个 5 server / 58 tool 的中等规模部署常态烧 **55K tokens**，光 Jira 一个 server 就 **17K**。更刺眼的是准确率崩塌：当 schema 质量下降，工具选择准确率会从 **43% 滑到 14%**；缺注解的工具占了 Claude Connector Directory 拒审量的 **30%**。本文从"工具描述工程（Tool Description Engineering）"这一被严重低估的源头环节切入，七条生产级原则 + 跨模型实测，拆解描述质量如何决定调用成败。

## 多维度对比：工具描述的六大工程维度

| 维度 | 反模式（生产事故） | 工程化做法 | 实测影响 |
|------|---------------------|------------|----------|
| 命名（name） | `customers` / `InvoiceCreate` / `send-email-v2` 混用 | verb+object，server 内统一 snake_case | 命名不一致，选择准确率塌方 |
| 描述（description） | 只写功能、几百字空话 | "what + when"，200–400 字符 | 选择混淆；token 浪费头号来源 |
| Schema 结构 | 3 层以上嵌套对象 | 尽量扁平，required/optional 显式 | parse 失败率随嵌套深度上升 |
| 行为注解（annotations） | 不填四 Hint | readOnly/destructive/idempotent/openWorld 全标 | 30% 拒审；自动审批误判 |
| 错误返回 | JSON-RPC 协议级 error | result 内 `isError:true` + 结构化消息 | 模型看不见错误→无法自愈 |
| 大载荷 | 百 MB 日志内联进 result | 返回 URI/Resource，按需拉取 | 上下文爆炸，token 成本失控 |

---

## 深度分析

### 一、工具定义即 Prompt：被低估的 Token 税

这是理解整个"工具描述工程"的起点。很多人把工具定义当成"给后端的接口文档"，但模型根本不看后端——**模型看到的，只有序列化成文本塞进上下文的那坨 JSON**。这意味着每一条工具定义都是 prompt token，每一次对话都要为它买单，而且它会稀释注意力、挤占真正有用的指令空间。

数据非常残酷。KanseiLink 与 MindStudio 的行业测量把单条工具定义钉在 **100–500 tokens**（取决于描述啰嗦程度）。一个 10 工具的中型 server，对话还没开始就 **1.5K–3K tokens** 起步；5 个 server、58 个工具直接冲到 **55K**；Jira 一个 server 单独 **17K**。Anthropic 自己的工程博客承认，内部某部署优化前是 **134K tokens 纯工具定义**——这已经逼近很多模型的有效上下文一半。

```text
# Token 税账本（工具定义层）
单工具定义:      100 - 500 tokens
10 工具 server:   1.5K - 3K
58 工具 / 5 server: ~55K
Jira 单 server:   ~17K
Anthropic 优化前:  134K  ──► MCP Tool Search 后 ~5K (-85%)
```

变现与训练营角度：这是一个极好的"降本"卖点。把客户的 134K 砍到 5K，省下的不是小钱——按主流模型每百万 token 的输入价，单次会话就能省下可观的推理成本，长会话复利更惊人。可以包装成"工具定义瘦身审计"服务或训练营模块。

### 二、命名工程：动词前置 + Server 内一致性

MCP 官方规范并不强制命名约定，但 2026 年行业已经收敛到 **snake_case 或 camelCase、verb + object**。背后的认知科学很简单：模型在做"这个工具是干什么的"分类时，**动词前置能加速意图匹配**。`search_customers` 比 `customers` 快得多地被识别为"检索类操作"。

真正不可破的红线是 **server 内一致性**。同一个 server 里混用 `database_query`（snake）和 `createInvoice`（Pascal 且语序倒装）和 `send-email-v2`（kebab + 版本后缀），会迫使模型隐式地对工具做"风格聚类"，选择准确率应声下跌。一个被反复引用的工程实测是：**schema 质量下降时，工具选择准确率从 43% 掉到 14%**——这不是 10% 的波动，是腰斩再腰斩。

```jsonc
// ✅ 良好：snake_case 统一，verb + object
{ "name": "search_customers" }
{ "name": "create_invoice"  }
{ "name": "send_email"       }

// ❌ 反模式：约定混用、缺动词、语序倒装、版本后缀
{ "name": "customers"      }  // 没动词
{ "name": "InvoiceCreate"  }  // Pascal + 倒装
{ "name": "send-email-v2"  }  // kebab + 版本号
```

### 三、描述工程：把 Few-Shot 塞进 Schema

AppScale 把这一条命名为 **"description engineering — the few-shot inside the schema"（描述工程：藏在 schema 里的 few-shot）**，定位极准。描述不是给人看的文档，是给模型做的**选择判据**。它必须同时回答两个问题：**做什么（what）+ 何时用它（when to use）**。

只写功能的描述（"returns a list of customers"）会和一堆相似工具撞车，模型分不清该用哪个。目标是 **1–3 句、200–400 字符**，把四要素压缩进去：Action（做什么）、Input prerequisite（输入前置条件，如鉴权范围）、Output expectation（返回什么、有无上限）、When to pick（相比相似工具何时选这个）。冗长的多段式描述被 2026 年业界点名为 **token 浪费头号来源**。

```jsonc
// ✅ 良好：四要素压缩，含"何时用"的判别信息
"description": "Search customers. Supports query/limit/offset.
 Returns max 100 results — pagination required. For a single
 customer by ID, use get_customer_by_id instead. Read-only."

// ❌ 反模式：只写功能、空话连篇
"description": "This tool returns a list of customers from our
 comprehensive customer database management system, which has
 been built with industry-leading technology..."
```

这里有一个关键的工程直觉：**描述里那一句"For X, use Y instead"是性价比最高的一行字**。它本质是教模型做工具间的负向区分，能直接消灭"选对类型、选错具体工具"的塌方。

### 四、Schema 扁平化：嵌套深度即 Parse 失败率

JSON Schema 理论上支持任意深度的嵌套和复杂校验，但作为 MCP 工具的 `inputSchema`，铁律是**越扁平越好**。嵌套越深有三重代价：token 更多、模型认知负荷更高、**参数 parse 失败率上升**。

当业务上确实需要复杂对象层级时，有两条出路：一是**把嵌套对象拍平为顶层参数**（`filters.date_range.start` → `start_date`）；二是**拆成多个专用工具**——业界经验是"三个具体工具在选择准确率上通常胜过一个通用工具"。这和 REST API 设计里"窄而专的端点比胖端点好用"是同一个道理，只是迁移到了 LLM 的语境。

```jsonc
// ❌ 反模式：3 层嵌套，filters.date_range.start
{
  "type": "object",
  "properties": { "filters": { "type": "object",
    "properties": { "date_range": { "type": "object",
      "properties": { "start": {"type":"string"}, "end":{"type":"string"} }}}}}}
}

// ✅ 良好：扁平，required 显式声明
{
  "type": "object",
  "properties": {
    "start_date": {"type":"string","format":"date"},
    "end_date":   {"type":"string","format":"date"},
    "tags":       {"type":"array","items":{"type":"string"}}
  },
  "required": ["start_date","end_date"]
}
```

### 五、工具注解：四 Hint 与 30% 拒审

工具注解（annotations）是 2025 年引入、2026 年标准化的元数据，用来**声明工具的行为特征**。四个子字段：`readOnlyHint`（只读不改）、`destructiveHint`（难以撤销）、`idempotentHint`（同输入同结果，可安全重试）、`openWorldHint`（触及外部 API/DB/网络）。公开数据显示，**缺失注解占了 Claude Connector Directory 拒审量的 30%**——这是一个被严重忽视的上线红线。

注解的价值在于让宿主 App 做正确的**自动/手动审批路由**：只读工具可自动放行，破坏性工具必须人工确认。但要记住一条关键警示：**注解是 hint（提示），不是 contract（契约）**。MCP 选择 hint 而非可执行契约，是因为跨不可信 server 强制契约不现实；客户端仍要跑自己的安全检查。

还有一个微妙陷阱：一个叫 `search` 的工具，如果顺手把查询写进了分析库做埋点，它就**不能**标 `readOnlyHint:true`——只要有写副作用，就失去只读资格。同理，"破坏性"不止是删数据：覆盖文件、吊销 token、关闭 issue，只要难撤销，都算破坏性。

### 六、错误信封：`isError` vs 协议级错误——自愈的分水岭

这是 MCP 错误设计里最大的坑，也是直接决定 Agent 能否**自愈**的分水岭。工具执行错误必须返回在 `result` 对象内部（`isError: true` + 结构化消息），而**不是**作为 JSON-RPC 协议级 error。原因直白：如果错误走协议层，模型**看不到错误内容**，只知道"某个东西失败了"；如果错误在 result 内，模型能读到"哪里错了、该怎么补救"，从而尝试恢复。

```jsonc
// ❌ 反模式：协议级 error，模型看不见内容
{ "jsonrpc":"2.0","id":1,
  "error":{"code":-32603,"message":"Database connection failed"} }

// ✅ 良好：result 内 isError + 结构化恢复提示
{ "jsonrpc":"2.0","id":1,
  "result":{ "isError":true,
    "content":[{"type":"text","text":
     "Database connection failed. Retry-After: 5s. Transient error —
      retry with exponential backoff (3 attempts recommended)."}]}}
```

注意那条结构化消息里塞了 **Retry-After 和重试策略建议**——这是把"自愈剧本"写进错误返回。结合 ToolBench 上 Tool-MVR 创下的 **58.9% 错误纠正率（ECR）**，可以看出：模型的自愈能力高度依赖错误返回里有没有可执行的恢复线索。错误信封写得对，自愈率就高；写成协议错误，自愈能力直接归零。

### 七、大载荷 URI 化 + Tool Search：34–64% 降耗

2026 年被反复强调的两条降本实践。第一条是**大载荷走 URI，不内联**：文件检索、日志拉取、数据集查询这些会随记录数膨胀的端点，绝不能把几 MB 数据塞进 result body——那等于直接灌进上下文烧 token。正确做法是返回一个 Resource URI，按需再 `read_resource` 拉取。

```jsonc
// ✅ 良好：返回 URI，按需拉取（5.2MB 不进上下文）
{ "result":{ "content":[{"type":"resource","resource":{
    "uri":"logs://2026-05-19/full","mimeType":"text/plain",
    "description":"100K log lines (5.2MB). Use read_resource to fetch."}}]}}
```

第二条是 **Tool Search（懒加载）**。这个由 Anthropic 内部工具开创、后由 Spring AI 在 2025 年 12 月 MCP 集成中形式化的模式，解决了一个规模化顽疾：把几百条工具定义全塞进上下文既贵又 degrade 推理质量。做法是先只给模型一个"搜索工具"的能力，模型按需查询相关工具定义，只有命中的才展开进上下文。生产基准显示，这带来了 **34–64% 的总 token 消耗下降**（取决于模型和检索策略）。这正是 Anthropic 把 134K 砍到 5K 的核心机制。

### 八、跨模型描述敏感度：BFCL V4 的实测座次

工具描述质量的影响，最终会落在跨模型的实测座次上。最权威的 Berkeley Function Calling Leaderboard（BFCL）已迭代到 V4（2025 年 7 月发布），评分公式发生根本转向：

```
Overall = Agentic×40% + Multi-Turn×30% + Live×10%
        + Non-Live×10% + Hallucination×10%
```

40% 权重压在 Agentic 行为上，意味着"单次调用准确但多跳推理拉胯"的模型不再算 SOTA。V4 代表性成绩：**Claude Opus 4.1 第 2 名 70.36%、Claude Sonnet 4 第 3 名 70.29%，均超过 GPT-5 的 59.22%（第 7）**。在衡量 Agent 执行可靠性的 AN Score 上，Anthropic 8.4 > Google 7.9 > OpenAI 6.3。

这些差距里有相当一部分来自**对工具描述的敏感度**：Anthropic 因 agent-centric 训练侧重，对结构化工具调用更稳；而 BFCL V4 的关键发现指出，顶级模型仍然在**长对话记忆、动态决策（知道何时不该用工具）、格式敏感（API schema 换个呈现方式就崩）**上挣扎。最后一条尤其值得警惕——它说明同一套工具描述在不同模型上的表现可能剧烈漂移，**描述工程必须做跨模型回归测试**，不能只在一个 provider 上验证就上线。

```mermaid
flowchart TD
    A[用户意图] --> B{Tool Search 懒加载}
    B -->|按需检索| C[仅命中工具定义进上下文<br/>134K → 5K tokens]
    C --> D[模型读描述做选择<br/>name/description/schema]
    D --> E{选择准确?}
    E -->|命名一致 + what/when 描述<br/>注解齐全| F[✅ 选对工具]
    E -->|混用命名 / 功能型空话<br/>缺注解| G[❌ 选择塌方 43%→14%]
    F --> H[参数填充<br/>扁平 schema]
    H --> I{执行}
    I -->|成功| J[大载荷走 URI<br/>不内联]
    I -->|失败| K[isError 信封<br/>+ 恢复剧本]
    K --> L[模型自愈重试<br/>ECR 58.9%]
    G --> M[拒审 30% / 误调用]
    J --> N[对话继续]
    L --> N
```

---

## 推荐方案：分场景的工具描述工程清单

**场景一：新建 MCP server / 工具集（预防性）**
直接套用 KanseiLink 的七原则上线前 checklist：全 server 统一 verb+object 命名；描述 200–400 字符覆盖四要素；inputSchema 拍平；四个 Hint 全标；错误走 `isError` 信封；大载荷走 URI；边界处加输入校验。目标：**10 个工具总定义 token < 3K，单 server < 20K**。

**场景二：存量 server 降本审计（高 ROI）**
先量"工具定义 token 总量"，凡超 20K/server 的优先瘦身。三步走：① 引入 **Tool Search 懒加载**（预期 34–64% 降耗）；② 把冗长描述压成四要素短句；③ 嵌套 schema 拍平 + 拆分通用工具为专用工具。Anthropic 134K→5K 的案例就是这条路径的标杆。

**场景三：多 provider 部署（兼容性优先）**
不要裸用任何一家的原生格式（OpenAI 的 strict JSON Schema、Anthropic 的 tool_use、Gemini 的 function calling 互不兼容）。引入一层 **per-provider transformer** 做 schema 翻译，并接受少量能力损耗换可移植性。描述层务必做**跨模型回归**——BFCL V4 的"格式敏感"发现警告我们，一套描述换个 provider 可能就从 70% 掉到不及格。

**场景四：安全敏感（金融/医疗/运维）**
注解不是契约，**客户端必须自跑安全检查**：能力令牌（capability token）做 per-tenant 工具白名单；破坏性工具强制人工审批闸门；每个 tool-call span 发 OpenTelemetry GenAI 属性做审计。幂等键 + 注解配合，覆盖重试安全。

**变现/训练营评估**：工具描述工程是 2026 年性价比最高的 Agent 培训主题之一——门槛适中（不涉及训练）、立竿见影（token 成本与准确率双改善）、可量化（token 数、BFCL 分、拒审率都能打分）。可包装为"工具定义瘦身审计 + 跨模型回归测试"两日营，或嵌入企业 MCP 上线的交付流程作为强制 gate。

---

## 参考来源

1. [MCP Tool Schema Design Guide 2026 — 7 Principles](https://kansei-link.com/en/insights/mcp-tool-schema-design-guide-2026) — KanseiLink 关于命名、描述、扁平 schema、注解、错误返回、URI 载荷、边界校验的七条生产级原则与 token 测量数据（134K→5K、55K/58 工具、Jira 17K、43%→14%）
2. [Tool Use and Function Calling in AI Agents — Standards, Benchmarks, and Emerging Patterns](https://zylos.ai/research/2026-04-07-tool-use-function-calling-standards-benchmarks/) — Zylos Research 对 BFCL V4 评分公式与座次（Opus 4.1 70.36%、Sonnet 4 70.29%、GPT-5 59.22%）、AN Score、MCP-AgentBench（33 server/188 tool/600 query）、Tool-MVR ECR 58.9%、Tool Search 34–64% 降耗的系统综述
3. [Tool-Calling Schema Design for LLM Agents — 2026 Production Pattern](https://appscale.blog/en/blog/ai-service-pattern-tool-calling-schema-design-llm-agents-2026) — AppScale 提出"description engineering = few-shot inside the schema"、per-provider transformer、capability token、错误信封、五阶段成熟度阶梯等生产模式
4. [Tools — Model Context Protocol Specification](https://modelcontextprotocol.io/specification/draft/server/tools) — MCP 官方规范对 tools 原语、inputSchema、annotations（readOnlyHint/destructiveHint/idempotentHint/openWorldHint）、isError 信封、Resources/URI 的权威定义
5. [Function Calling, Tool Use, MCP: How to Pick the Right One in 2026](https://www.mantissaai.com/blog/function-calling-tool-use-mcp-pick-2026) — 对 function calling / native tool use / MCP 三条路径差异、适用场景与 provider 兼容性现状的横向对比

> [!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)