首页 › ai-agents › 工具描述工程：描述决定调用成败

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

概述

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 纯工具定义——这已经逼近很多模型的有效上下文一半。

# 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% 的波动，是腰斩再腰斩。

// ✅ 良好：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 浪费头号来源。

// ✅ 良好：四要素压缩，含"何时用"的判别信息
"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 的语境。

// ❌ 反模式：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 内，模型能读到"哪里错了、该怎么补救"，从而尝试恢复。

// ❌ 反模式：协议级 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 拉取。

// ✅ 良好：返回 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 上验证就上线。

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 — 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 — 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 — AppScale 提出"description engineering = few-shot inside the schema"、per-provider transformer、capability token、错误信封、五阶段成熟度阶梯等生产模式
  4. Tools — Model Context Protocol Specification — 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 — 对 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学通信知识星球海报-扫码加入

📎 本分类最新文章