# 工具描述即提示词：六层栈实测 ## 概述 工具调用不准，多数团队第一反应是"换更强的模型"。但 2026 年的多份生产数据指向同一个被忽视的杠杆：**工具的 Schema 本身就是提示词的一部分**。模型不会"读文档查手册"，它在每一次推理时，都把全部工具定义当作上下文逐 token 读进去——一个工具定义 100–500 token，五个服务器 58 个工具就烧掉约 55K，仅 Jira 一个连接器就被测到 17K。Anthropic 工程博客披露，优化前工具定义吃掉 134K token，引入 Tool Search 懒加载后降到约 5K，工具选择准确率同时从 43% 滑到 14% 的"质量塌方"被逆转。本期把工具描述工程拆成**六层栈**——命名、描述、入参、标注、出参、错误——逐层对应 BFCL V4 与 ToolScan 基准里的真实错误码，用六组生产数据说清：哪一层最贵、哪一层最致命、哪一层一行注释就能堵住。 ## 六层栈对比总表 | 层级 | 失效表现 | 对应基准错误码 | Token 成本 | 一行修复 | |------|----------|----------------|-----------|----------| | 命名层（name） | 召唤不存在的工具、动词缺失 | IFN | 低 | 统一 `动词+对象` | | 描述层（description） | 选错相似工具、语义值跑偏 | IAN / IAV | 高（200–400 字） | "做什么+何时用" | | 入参层（inputSchema） | 深嵌套解析失败、类型错 | IAT / IFE | 中 | 压平 + strict | | 标注层（annotations） | 审批/护栏误判、目录被拒 | 编排层 IAC | 极低 | 补全四个 hint | | 出参层（output） | 推理漂移、级联误判 | RAC / 级联 | 复利增长 | 语义字段名 + 截断 | | 错误层（error） | 无限循环、静默失败 | IAC / IFE | — | `isError` 入 result | --- ## 第一层 · 命名层：动词前置，一致性压过一切 MCP 规范并不强制命名风格，但 2026 年行业已经收敛到 `snake_case` 或 `camelCase` 加上 `动词+对象`。从模型视角，动词前置能加速"这个工具干什么"的分类——`search_customers`、`create_invoice`、`send_email` 是好命名；`customers`（无动词）、`InvoiceCreate`（PascalCase+语序倒装）、`send-email-v2`（kebab+版本后缀）是坏命名。 真正不可妥协的不是选哪种风格，而是**同一服务器内必须一致**。把 `database_query` 和 `createInvoice` 混在一个服务里，模型会隐式地把它们分到不同"心智类别"，选择准确率直接下滑。这一层对应 ToolScan 基准里的 **IFN（Incorrect Function Name）**——模型幻觉出一个根本不存在的工具，比如在只有 `writeRecord` 时调 `updateRecord`。命名层是六层里最便宜的一层：改个名字几乎零成本，却能挡掉一类最荒谬的失败。 ```json // ✅ 命名层修复：动词+对象，全服务统一 snake_case { "name": "search_customers" } { "name": "create_invoice" } { "name": "delete_invoice" } // ❌ 混用风格，IFN 高发 { "name": "customers" } { "name": "InvoiceCreate" } { "name": "send-email-v2" } ``` **优缺点**：优点是修复成本接近零、收益立竿见影；缺点是一旦服务由多团队共建，命名漂移会随时间复发，需要 lint 守住。**变现评估**：可作为训练营"工具诊断第一课"的钩子，半小时就能让学员看到准确率曲线变化，转化率高。 ## 第二层 · 描述层：200–400 字符，"做什么"加"何时用" 这是六层里**最贵也最被低估**的一层。描述必须同时包含"工具做什么"和"何时该用它"两件事。模型靠描述做工具选择，只写"返回客户列表"的功能型描述，会和相似工具撞车。2026 年生产指南把目标长度定在 1–3 句、200–400 字符，把四要素压进去：动作、输入前提（鉴权/前置）、输出预期（类型/上限）、何时选它（相对相似工具的差异）。 冗长的多段描述被一致认定为头号 Token 浪费源。更要命的是描述写得不好会直接制造 **IAV（Incorrect Argument Value）**——这是七类错误里最危险的一类，因为它**能通过 schema 校验**：类型对、字段名对，但语义错。`priority: "low"` 在该用 `"urgent"` 时，是合法 JSON，会无报错执行。Klavis AI 对 BFCL 的分析结论是：顶级模型单工具清晰意图能到 90%+，但多轮、歧义场景掉到 50–70%，差距就长在描述层。 ```json // ✅ 四要素压缩在 200–400 字符 "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. Cannot create or update (read-only)." // ❌ 功能型 + 冗长泛泛而谈 "description": "This tool returns a list of customers from our comprehensive customer database management system..." ``` **优缺点**：优点是单点杠杆极大，描述重写常能换来两位数百分点提升；缺点是"好描述"没有客观标尺，需要评测集反向验证。**变现评估**：这是"工具提示词工程"产品化的核心卖点，可包装成 SaaS 的"Schema 体检"功能，按工具数计费。 ## 第三层 · 入参层：压平优先于炫技 JSON Schema 支持任意深嵌套与复杂校验，但 MCP 工具入参的铁律是"**尽可能扁平**"。嵌套越深，三件事同时恶化：token 更多、模型认知负载更高、解析失败率更高。当一个复杂对象层级看起来不可避免时，有两条出路——把嵌套对象拆解成顶层简单参数，或拆成多个具体工具。行业经验是：**三个具体工具的选择准确率，通常胜过一个泛化工具**。 入参层对应 **IAT（Incorrect Argument Type）**与 **IFE（Invalid Format Error）**。好消息是这两类可以被 OpenAI `strict: true` 或同类结构化输出几乎彻底消灭——官方称开启后达到 100% schema 遵从率，靠的是基于语法的 token 掩码（约束解码）。代价是必须 `additionalProperties: false`、所有字段标 required、可选字段用 `null` 联合类型，且新 schema 首次请求有语法编译的延迟惩罚。 ```json // ❌ 深嵌套 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"] } ``` **优缺点**：优点是 strict 模式让 IAT/IFE 接近归零；缺点是它**只保结构不保语义**，模型仍可挑错工具、传语义错的合法值、漏调关键工具。**变现评估**：可做成"strict 模式迁移"咨询，按 schema 复杂度报价，迁移失败案例极多，需求真实。 ## 第四层 · 标注层：四个 hint，30% 目录被拒的元凶 工具标注（annotations）2025 年引入、2026 年标准化，是声明工具行为的元数据，四个子字段：`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`。公开数据显示，**缺失标注占了 Claude Connector Directory 拒绝的 30%**。这一层 token 成本极低，却直接决定宿主 App 的自动/手动审批分流——一个 `readOnlyHint:true` 的搜索工具可以免审批，一个 `destructiveHint:true` 的删除工具必须人工确认。 关键陷阱是：**标注是 hint 不是 contract**。MCP 选择 hint 而非强制契约，是因为在不可信服务器间强制执行契约不现实，客户端仍要自跑安全检查。一个名叫 `search` 却顺手把查询写进分析库的工具，**绝不能**设 `readOnlyHint:true`——哪怕主目的是读，有写副作用就 disqualified。同理"破坏性"不等于"删数据"：覆盖文件、吊销令牌、关闭 issue 都算。 ```json // 搜索工具（只读 + 幂等 + 外部世界） { "name":"search_customers", "annotations":{ "readOnlyHint":true,"destructiveHint":false, "idempotentHint":true,"openWorldHint":true } } // 删除工具（破坏性 + 非幂等） { "name":"delete_invoice", "annotations":{ "readOnlyHint":false,"destructiveHint":true, "idempotentHint":false,"openWorldHint":true } } ``` **优缺点**：优点是成本几乎为零却解锁自动审批、显著降低护栏摩擦；缺点是"hint 非 contract"的语义落差容易让团队误以为标了就安全。**变现评估**：可作为 MCP 服务器"上架合规"服务，按通过率收费，AEO 评级（AAA–D）是天然卖点。 ## 第五层 · 出参层：工具返回值是推理底物，不是 API 管道 这一层是六层里**复利成本最狠**的一层。绝大多数团队在设计 agent 时，把精力花在工具选择和系统提示词上，几乎没人认真想"工具该返回什么"。但工具响应的形状，决定了 agent 能否对它推理、吃掉多少上下文、会不会在多步链里级联崩溃。底层机制很简单：LLM 是 next-token 预测器，返回 `{"uuid":"d3fa...","mime_type":"image/png"}` 时模型得推断含义，返回 `{"name":"profile-photo.png","image_url":"https://..."}` 时模型可直接推理。 字段命名的影响力超出多数工程师预期：`ts` 需要推断，`created_at` 自解释；同一工具这次返回 `urgency`、下次返回 `priority`，会直接打断 agent 已建立的推理模式。2026 年的研究把破坏推理的六种反模式列得很清楚：裸 JSON、成功响应里埋错误（HTTP 200 + `{status:"error"}`）、可空性歧义、过度冗长、信息不足、字段类型漂移。**输出 token 比输入 token 贵 4–6 倍**，且多轮 agent 循环里上下文成本约以 `n(n+1)/2` 增长——第一轮多塞的 1000 token，此后每一轮都要重付。一个 20 工具的服务，无论实际调用哪个工具，每次请求都注入 2–4K schema 开销，在无声地稀释每一步推理。 Shopify 的 Sidekick（服务数百万商户）正是卡在约 50 个工具的墙上，系统提示词堆成特殊 case 大杂烩，最后靠 **Just-in-Time Instructions**（把相关工具指引随工具结果一起加载，而不是塞进系统提示词）破局。 ```json // ❌ 裸 UUID + 不透明类型，模型只能猜 { "id": "d3fa...", "t": "img", "urgency": 2 } // ✅ 语义标识符，可直接推理 { "ticket_id":"T-4821","title":"Payment timeout in checkout", "created_at":"2026-06-23T10:00:00Z","status":"open" } ``` **优缺点**：优点是出参精修能同时降本和提准，复利效应随轮次放大；缺点是"该返回什么"没有上限，需要 Pydantic 出参契约 + AWS ToolSimulator 在边界校验。**变现评估**：可做成"工具出参体检 + 截断策略"工具，按节省 token 计费，ROI 极易量化。 ## 第六层 · 错误层：`isError` 入 result，错误绝不走协议层 错误层是六层里**最致命**的一层，因为它直接喂出无限循环和静默失败两种生产事故。MCP 错误设计的最大陷阱是：工具执行错误必须以 `isError:true` 加结构化消息放进 `result` 对象，**而不是**走 JSON-RPC 的协议级 `error` 字段。原因很直白——错误若走协议层，模型根本看不到错误内容，只知道"某个东西失败了"；错误若在 `result` 里，模型能读到"哪儿坏了"并尝试恢复。 2026 年 1 月的一份生产分析记录了最常见的无限循环失败：agent 调工具→结果不清→本地看 retry 合理就重试→但它不知道自己已经是第 15 次。三条根因覆盖 90% 的循环：缺 `max_turns`、终止条件永不为真、系统提示词没有明确的"你完成了"信号。配套实践是大负载走 URI（Resource）而不是 inline——返回 10 万行日志会直接灌进上下文烧 token，正确做法是返回 `logs://date/full` 的资源句柄，按需 `read_resource`。 ```json // ❌ 协议级 error，模型只知"失败"，进循环重试 { "jsonrpc":"2.0","id":1, "error":{ "code":-32603,"message":"Database connection failed" } } // ✅ isError 入 result + 可操作恢复指引 { "jsonrpc":"2.0","id":1,"result":{ "isError":true,"content":[{ "type":"text", "text":"Database connection failed. Retry-After: 5s. Transient — retry with exponential backoff (3 attempts)." }]}} ``` 更隐蔽的是 **IAC（Insufficient API Calls）**——静默杀手。模型结束回合、返回一个看似合理的回复，却始终没调用那个关键工具：在合规外联系统里，它处理了负面回复、生成了客气回复，却**忘了调 opt-out 执行工具**。一切看起来都对，违规不可见，直到有人审计数据。`strict` 模式挡不住它，因为它压根没报错。**优缺点**：优点是 `isError` + 恢复指引能把可重试错误转为自愈；缺点是 IAC 类漏调无法靠 schema 解决，必须在编排层做"关键工具必调"断言。**变现评估**：可包装成"agent 可靠性加固"训练营压轴课，因为这一层直接决定生产敢不敢上线。 ## 基准映射：BFCL V4 与 ToolScan 给六层栈的体检报告 把六层栈对到 BFCL V4（截至 2026 年初的行业基准）和 ToolScan（ICLR 2025，把失败归成七类错误码），能看到各层的"贡献度"。BFCL V4 上 Claude Opus 4.1 以 70.36% 排第二、Claude Sonnet 4 以 70.29% 排第三、GPT-5 以 59.22% 排第七——但 Klavis AI 的拆解指出，**简单单工具场景顶级模型都能到 90%+，差距全在多轮与歧义**。换句话说，模型本身的工具调用底子够用，生产事故大量出在六层栈的工程质量上，而非模型能力。 ToolScan 的七类错误里，三类可被 `strict` 模式压平（IAT/IAN/IFE，对应入参层与描述层的语法面），两类最危险的需要描述层和编排层联手治：**IAV**（语义值合法却错误，过校验、可执行）和 **IAC**（漏调关键工具、静默违规）。还有一类 **RAC**（重复调用同一工具，对应出参层信息不足导致模型反复确认）。UC Berkeley 对 1,600+ 多 agent 执行 trace 的分析进一步印证：参数畸形、类型不匹配、必填缺失等 schema 问题，是最常见的根因，但它们最终以"agent 推理失败"的面目出现，让大家误以为是模型蠢。 工具数量这一轴，Anthropic 自己的数据最硬：**准确率在 30–50 个工具之后显著下滑**，他们为此造了 Tool Search，让每次只加载 3–5 个相关工具，工具定义在上下文里减少 85%+。实测提升：Opus 4.0 从 49% → 74%，Opus 4.5 从 79.5% → 88.1%，**单点架构改动换来 25 个百分点以上**。结论很锋利：工具超过 30 个就必须上过滤层，否则准确率掉到抛硬币。这一发现把"描述层 + 命名层"的工程价值再放大——因为你迟早要靠它们做工具检索的召回排序。 ## 推荐方案：按场景配六层加固清单 | 场景 | 优先加固层 | 关键动作 | 预期收益 | |------|-----------|----------|----------| | <10 工具内部助手 | 命名层 + 错误层 | 统一命名、`isError` 入 result | 消除 IFN 与循环 | | 10–30 工具 SaaS | 描述层 + 标注层 | 200–400 字符描述、补全四 hint | 选择准确率 + 免审 | | 30+ 工具平台 | 全六层 + Tool Search | 懒加载 + 出参截断 | +25pp、token -85% | | 高合规外联/金融 | 错误层 + 编排断言 | "关键工具必调"守门 | 堵 IAC 静默违规 | | 多模型混部 | 入参层 strict | `additionalProperties:false` | 隔离版本回归 | 落地节奏建议三步：第一步花半天过**预发布清单**（命名一致、描述四要素、入参扁平、四 hint 齐全、错误入 result、大负载走 URI、边界校验落地、单服务 token 控制在 3K 内/10 工具、20K 内/服务）；第二步接入 Pydantic 出参契约 + AWS ToolSimulator 在边界做契约测试，把 schema 问题挡在 agent 之前；第三步对超 30 工具的系统上 Tool Search 类过滤层。一句话总结：**工具调用不准时，先改描述，再换模型**——因为那份被你当作"API 文档"的 Schema，模型正把它当提示词逐字读。 ## 参考来源 1. [MCP Tool Schema Design Guide 2026 — KanseiLink](https://kansei-link.com/en/insights/mcp-tool-schema-design-guide-2026) — 七条生产级 Schema 设计原则，含 134K token、55K/58 工具、30% 目录拒审等硬数据 2. [Tool Output Schema Design: How Your Tool Responses Shape Agent Reasoning — Tian Pan](https://tianpan.co/blog/2026-05-05-tool-output-schema-design-agent-reasoning) — 出参即推理底物，六反模式、n(n+1)/2 复利成本、三层契约 3. [LLM Function Calling in Production: What the Benchmarks Actually Say — Hamed Taheri](https://www.hamedtaheri.com/articles/llm-function-calling-in-production/) — BFCL V4 排名、ToolScan 七错误码、Anthropic 30–50 工具墙与 Tool Search 提升 4. [Berkeley Function Calling Leaderboard (BFCL) V4 — UC Berkeley Gorilla](https://gorilla.cs.berkeley.edu/leaderboard.html) — 行业工具调用评测榜单，simple/parallel/multi-turn 分场景 5. [Tool Use and Function Calling in AI Agents: Standards, Benchmarks — Zylos.ai](https://zylos.ai/research/2026-04-07-tool-use-function-calling-standards-benchmarks/) — 跨厂商工具调用标准与基准综合分析 > [!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 等场景全覆盖。