MCP工具描述写得含糊，模型选错工具甚至干脆不调用，描述质量到底该怎么写？

——以“可判别性”为主线的工具描述工程方法论

摘要

Model Context Protocol（MCP，模型上下文协议）把外部能力以“工具”形式暴露给大模型，工具描述（tool description）因此成为模型决策的唯一先验输入。工程实践中反复出现两类失败：模型选错工具，或干脆不发起调用。本文提出一条贯穿全文的分析主线——工具描述的本质是“可判别性”供给，即描述必须在有限 token 预算内，让模型在候选工具集合上做出稳定、可复现的区分决策。围绕这条主线，本文依次拆解语义层（是什么）、语用层（何时用）、结构层（怎么用）三层信息缺失的成因，给出可量化的描述质量维度与评测方法，提出“判别性最小完备描述”写作规范与工程化流水线，并结合国内外协议演进与近三年学术研究，讨论描述层治理的边界条件与前沿方向。文中所有数据均标注来源，模拟与整合数据单独说明。

目录

一、问题的提出：从一次“静默失败”说起

先看一个在 MCP 集成中极具代表性的现象。某团队为客服 Agent 接入了三个工具：search_ticket、query_order、get_user_info。三者的描述分别是“搜索工单”“查询订单”“获取用户信息”。上线后监控显示：当用户说“我上周买的那个东西还没到，帮我看看”时，模型有相当比例直接回复“我无法查询物流”，既不调用 query_order，也不调用 search_ticket。这不是模型能力不足，而是描述没有告诉模型“订单查询包含物流状态”这一事实。

这类失败在工程上被称为“静默失败”（silent failure）：模型没有报错，只是选择了不调用或调用了错误的工具，系统看起来“正常”，但任务完成率显著下降。它比异常更危险，因为缺乏显式信号，往往要等到用户投诉或人工抽检才被发现。本文认为，绝大多数静默失败可以在描述层被前置消解，前提是我们把描述当作一个需要工程化治理的接口契约，而不是随手写的一句自然语言注释。

需要先厘清一个边界：本文讨论的“描述质量”不涉及模型本身的推理能力上限，也不承诺描述写好就一定能提升任务成功率。描述的作用是降低决策歧义，它影响的是模型在候选集合上的选择分布，而非模型的知识边界。把描述工程定位为“决策前的信息供给”，是全文论证的起点。

二、背景与问题定义：MCP 工具调用的决策链路

2.1 MCP 的协议定位与工具抽象

MCP 由 Anthropic 于 2024 年 11 月开源发布，定位是“为 LLM 应用提供标准化的上下文与能力接入方式”。其核心抽象包括 Resources（资源）、Prompts（提示模板）与 Tools（工具）。其中 Tools 通过 tools/list 返回工具清单，每个工具包含 name、description 与 inputSchema（JSON Schema）三个关键字段。模型在决定是否调用、调用哪个工具时，能“看到”的正是这三者序列化后的文本。

这意味着一个常被忽视的事实：工具描述不是给人看的文档，而是给模型看的决策输入。它和 prompt 一样参与上下文计算，一样受 token 预算约束，也一样会因为措辞差异导致输出分布漂移。把描述当作“注释”来写，是绝大多数描述质量问题的根源。

2.2 决策链路拆解：描述在哪个环节起作用

把一次工具调用拆成四个环节，可以更精确地定位描述的作用点：

本文评述：上表中，环节①与②是描述质量问题的高发区，也是本文的核心关注对象。环节③更多依赖 JSON Schema 的规范性，环节④则与返回值的结构化设计相关。把四者混为一谈，会导致“描述写得越长越好”的错误结论——事实上，过长的描述会挤占上下文预算，反而降低召回与判别效率，这一点在第五节会用数据说明。

2.3 问题定义：什么叫“描述含糊”

“含糊”不是一个可操作的概念。本文给出一个可检验的定义：若在给定候选工具集合 T 与一组真实用户意图 U 的条件下，描述 D 使模型在 (u, T) 上的选择分布与“正确工具”标签的一致率显著低于理论上限，则称 D 在该意图分布上含糊。这个定义把“含糊”转化为一个可测量的量——一致率，从而为后续的评测方法奠定基础。

需要强调，一致率的上限受模型能力约束，因此评测必须采用“同模型、同 prompt、仅改描述”的对照设计，才能把描述质量的贡献从模型能力中剥离出来。这是本文评测方法论的第一条原则。

三、分析主线：工具描述的“可判别性”框架

3.1 可判别性的定义

本文提出“可判别性”（discriminability）作为贯穿全文的分析主线。其定义是：在候选工具集合 T 上，描述集合 D 使模型对任意意图 u 都能稳定地选出唯一正确工具 t* 的能力。可判别性不是单个描述的属性，而是整个工具集合的属性——一个描述单独看很清楚，但和另一个工具的描述高度相似时，可判别性依然很低。

这个视角的转换很重要：它把描述写作从“逐个工具的文档撰写”变成“工具集合的差异设计”。工程上，这意味着描述评审必须以“集合”为单位进行，而不是逐个工具签字确认。本文认为，这是当前 MCP 工具治理中最容易被忽略、也最容易见效的改进点。

3.2 可判别性的信息论直觉

从信息论角度看，模型在候选集合上做选择，本质是在估计条件概率 P(t | u, D)。可判别性高，意味着这个分布在正确工具上高度集中；可判别性低，意味着分布接近均匀。描述的作用是提供“区分性特征”，降低选择的不确定性。可以用一个简化的互信息视角来理解：

I(t; D | u) = H(t | u) - H(t | u, D)

其中：
  H(t | u)      —— 仅凭意图 u 时，工具选择的不确定性（基线）
  H(t | u, D)   —— 给定描述 D 后，剩余的不确定性
  I(t; D | u)   —— 描述带来的“判别信息量”

本文评述：这个公式不是要工程同学去算互信息，而是提供一个判断标准——描述的价值在于它减少了多少不确定性，而不在于它写了多少字。一段 200 字但只重复工具名的描述，I 值接近 0；一段 40 字但点明“与相邻工具差异”的描述，I 值可能很高。这解释了为什么“把描述写长”往往无效，甚至有害。

3.3 可判别性的三个必要条件

基于上述框架，本文归纳出可判别性的三个必要条件，它们构成后续写作规范的理论骨架：

条件一：覆盖性（Coverage）。描述必须覆盖该工具被正确调用的意图词汇空间。若用户说“物流”，而描述只写“订单”，覆盖性不足，召回环节即失败。覆盖性要求描述包含同义词、上位词与典型场景词。

条件二：区分性（Distinctiveness）。描述必须在候选集合中与相邻工具形成明确差异。若两个工具的描述都以“查询”开头且未说明边界，区分性不足，判别环节即失败。区分性要求描述显式声明“不做什么”或“与谁不同”。

条件三：可执行性（Actionability）。描述必须让模型知道调用后能得到什么、需要什么前置条件。若描述未说明“需要用户 ID”，参数化环节即失败。可执行性要求描述与 inputSchema 形成互补而非重复。

这三个条件缺一不可，且存在张力：过度追求覆盖性会导致描述膨胀，挤压区分性；过度追求区分性可能引入不必要的否定表述，增加认知负担。工程上的目标不是三个条件都最大化，而是在 token 预算约束下取得平衡。第六节给出的 DMCD 规范正是这一平衡的操作化。

四、三层信息缺失：语义、语用与结构

4.1 语义层缺失：工具“是什么”说不清

语义层缺失表现为描述停留在工具名的同义复述。例如工具名 get_weather，描述写“获取天气”。这等于没有提供任何新信息——模型从工具名已经能推断出这一点。语义层缺失的典型症状包括：描述与工具名高度重合、缺少输入输出语义、缺少数据来源与时效说明。

笔者认为，语义层缺失的深层原因是“开发者视角”与“模型视角”的错位。开发者写描述时默认读者了解系统上下文，而模型没有任何系统上下文。一个可操作的检验方法是：把描述单独抽出来，遮住工具名，看是否还能推断出这个工具的功能。如果不能，说明语义层信息不足。

4.2 语用层缺失：工具“何时用”没交代

语用层缺失是静默失败的首要成因。它表现为描述没有说明触发条件、适用场景与不适用场景。回到第一节的例子，“查询订单”没有说明“包含物流状态”，导致模型在物流意图上召回失败。语用层缺失的另一个常见形态是“工具间关系缺失”：多个工具存在先后依赖（如先查用户再查订单），但描述未声明依赖关系，模型可能跳过前置步骤直接调用。

本文评述：语用层信息在传统 API 文档中由“使用示例”和“注意事项”承载，而 MCP 的工具描述字段往往被当作一句话简介来填。这是协议能力与工程实践之间的落差。弥补这一落差不需要改协议，只需要在描述中显式加入“适用场景”与“前置条件”两个小节。

4.3 结构层缺失：工具“怎么用”不完整

结构层缺失表现为 inputSchema 的字段缺少 description、缺少示例值、缺少约束说明（如枚举范围、格式要求）。虽然 JSON Schema 本身支持 description 与 examples 关键字，但实践中大量 MCP Server 只声明类型不写说明。这直接导致参数化环节的失败率上升。

结构层缺失还有一个隐蔽形态：描述与 schema 重复。例如描述里写“参数 id 是用户 ID”，schema 里也写同样的话，信息冗余但不增加判别力。正确的分工是：描述负责“何时用、与谁不同”，schema 负责“字段含义与格式”，两者互补。

五、描述质量的可量化维度与评测方法

5.1 四个可量化维度

为了让“描述质量”可管理，本文提出四个可量化维度，每个维度都对应可自动或半自动计算的指标：

上述目标区间为本文基于工程经验给出的建议值（模拟数据，非实测统计），团队应根据自身工具规模与模型版本校准。区分度的 0.25 阈值尤其需要按嵌入模型调整，不同嵌入模型的余弦距离尺度差异较大。

5.2 评测方法：对照实验设计

描述质量评测的核心是控制变量。本文推荐如下实验设计：

第一步，构造意图集。从真实日志或客服语料中采样 N 条用户意图（建议 N ≥ 200），人工标注每条意图对应的正确工具。标注需双人交叉，分歧样本剔除或仲裁。

第二步，固定模型与 prompt。同一模型版本、同一系统提示、同一温度设置（建议 temperature=0 以保证可复现）。

第三步，仅改描述。分别用旧描述与新描述跑同一意图集，记录选择准确率、不调用率、错误工具分布。

第四步，显著性检验。用配对检验（如 McNemar 检验）判断改进是否显著，避免小样本波动被误读为改进。

本文评述：很多团队做描述优化时只跑几条 case 就下结论，这在统计上不可靠。200 条意图、配对检验、固定温度，是让结论“经得起科学检验”的最低要求。若资源有限，可先用 50 条做快速迭代，但上线前必须补足样本量。

5.3 自动化工具链建议

覆盖度与区分度可以自动化：用嵌入模型计算工具描述两两相似度矩阵，找出区分度低于阈值的“危险对”；用意图词表与描述做词面或语义匹配，估算覆盖度。一致性可用规则校验（如描述中提到的字段是否在 schema 中存在）。这些检查可以接入 CI，作为 MCP Server 发布的门禁。

拓展阅读：MCP 官方规范文档（modelcontextprotocol.io/specification）与 JSON Schema 官方指南（json-schema.org）是描述与 schema 写作的基础参考。

六、写作规范：判别性最小完备描述（DMCD）

6.1 DMCD 的四段式结构

基于第三节的三个必要条件，本文提出“判别性最小完备描述”（Discriminative Minimal Complete Description，DMCD）写作规范。它把描述拆成四个语义段，每段承担明确的判别职责：

[功能句] 一句话说明工具做什么，包含核心动词与对象。
[场景句] 说明何时应调用，列出 2–4 个典型意图触发词。
[边界句] 说明何时不应调用，或与哪个相邻工具区分。
[约束句] 说明前置条件、权限、时效、返回内容概要。

四段式的顺序不是随意的：功能句解决语义层，场景句解决语用层的召回，边界句解决语用层的判别，约束句解决结构层的可执行性。这个顺序也符合模型阅读的注意力分布——开头的信息权重更高。

6.2 改写示例：从含糊到可判别

以第一节的 query_order 为例，改写前后对比如下：

改写后的描述约 120 字，覆盖了物流、发货、收货等意图词（覆盖性），显式声明了与 search_ticket、create_refund 的边界（区分性），并说明了前置条件（可执行性）。本文评述：这个长度在多数场景下是合理的，但它并非固定模板——工具集合越大、相邻工具越相似，边界句就需要越具体；反之可以压缩。

6.3 常见反模式清单

在评审中，以下反模式应被直接打回：

反模式一：同义复述。描述与工具名信息量相同，如 send_email 写“发送邮件”。

反模式二：万能描述。描述声称能做很多事，导致与多个工具重叠，如“处理用户相关的一切操作”。

反模式三：内部黑话。使用只有内部团队懂的缩写或代号，模型无法映射到用户语言。

反模式四：与 schema 重复。描述里逐字段解释参数，挤占预算却不增加判别力。

反模式五：过度否定。用大量“不要”“禁止”堆砌边界，反而让模型对工具用途产生负面联想。边界句应聚焦“与谁不同”，而非罗列禁忌。

七、工程化落地：描述治理流水线

7.1 五阶段流水线

描述治理不应是一次性的人工润色，而应嵌入研发流程。本文建议五阶段流水线：

7.2 线上监控的两个关键指标

离线评测无法覆盖长尾意图，线上监控是必要补充。本文建议至少监控两个指标：不调用率（用户表达了明确任务意图但模型未发起任何工具调用的比例）与错误工具集中度（错误调用中，前三个被误选工具占比）。前者反映召回问题，后者反映判别问题。两个指标同时上升，通常意味着新加入的工具与既有工具描述重叠。

本文评述：这两个指标的妙处在于它们不需要人工标注正确工具，只需在调用日志上做统计，适合作为长期运行的“体检指标”。但它们是滞后指标，不能替代离线评测的前置把关。

7.3 版本管理与回归

描述应纳入版本控制，与工具代码同仓管理。每次描述变更都应触发离线评测回归，评测集随线上日志持续扩充。建议为每个工具维护“描述变更历史 + 对应评测结果”的对照表，便于回溯“哪次改动导致了准确率下降”。

拓展阅读：Anthropic 工程博客关于工具设计与 MCP 的实践文章（anthropic.com/engineering）提供了工具命名与描述的一手经验，可作为规范制定的参考。

八、案例与数据：从失败样本到改进闭环

8.1 一个模拟实验的设计与结果

为验证 DMCD 规范的有效性，本文设计了一个模拟实验（数据为模拟数据，非真实生产统计）。实验设置：8 个工具（含 3 对高相似工具），200 条标注意图，固定模型与 temperature=0，分别测试旧描述（工具名同义复述）与 DMCD 描述。

需要强调，以上为模拟数据，仅用于说明方法论的预期效果量级，不代表任何真实系统的实测结果。真实效果受模型版本、意图分布、工具数量影响，团队应自行复现。值得注意的是，描述 token 增加了约 5 倍，但准确率提升集中在高相似对上——这印证了第三节的判断：描述的价值在于区分性，而非长度本身。

8.2 国内外相关研究与实践

工具选择与描述质量并非 MCP 独有议题。在 MCP 之前，OpenAI 的 Function Calling、Toolformer 等工作已触及“模型如何选择外部工具”的问题。Toolformer（Schick 等，2023）展示了模型可通过自监督学习决定何时调用 API，但其关注点是调用时机的学习，而非描述文本的设计。本文评述：Toolformer 的路线是“让模型学会用工具”，而描述工程是“让工具更容易被模型用对”，两者互补而非替代。

近三年，工具检索与选择成为研究热点。ToolLLM（Qin 等，2023）构建了大规模工具调用数据集并训练模型在大量 API 中检索；ToolBench 等基准推动了工具选择的标准化评测。2024 年后，随着 MCP 生态扩张，社区开始出现针对 MCP Server 描述质量的讨论与检查工具。本文认为，这些工作共同指向一个趋势：工具描述正在从“文档属性”演变为“可评测的接口属性”，未来可能出现类似 OpenAPI lint 的 MCP 描述规范检查器。

在协议层面，MCP 规范持续演进，2025 年版本对工具注解（annotations）等字段做了扩展，为描述之外的元信息提供了承载空间。这意味着描述不必承担全部判别职责，部分结构化信息（如只读、幂等、破坏性提示）可交由注解字段表达。本文评述：这是协议设计的正确方向——把“给模型看的自然语言”与“给系统看的结构化元数据”分离，各自优化。

九、对比与局限：描述不是万能的

9.1 描述工程的边界条件

必须诚实地指出描述工程的局限。第一，描述无法弥补工具设计本身的缺陷。若两个工具功能高度重叠，再好的描述也只能缓解误选，不能根治；正确做法是合并或重构工具。第二，描述受上下文预算约束。工具数量达到数十上百时，描述总 token 会显著挤占上下文，此时应引入工具检索（tool retrieval）做前置筛选，而非无限扩写描述。第三，描述效果依赖模型能力。小参数模型对长描述的利用率可能低于大模型，规范需按模型校准。

本文评述：把描述工程定位为“必要但不充分”的治理手段，是避免过度承诺的关键。工程团队应同时关注工具粒度设计、检索前置、schema 规范三条线，描述只是其中一条。

9.2 与其他治理手段的对比

这张对比表的价值在于帮助团队做优先级排序：先做成本最低的描述优化与 schema 规范化，工具数膨胀后再引入检索前置，功能重叠严重时才动工具粒度。本文认为，多数团队的问题集中在第一、二行，而非需要大动干戈的重构。

十、结论与展望

回到标题的问题：MCP 工具描述到底该怎么写？本文的答案是——以“可判别性”为目标，在 token 预算约束下，用四段式结构提供覆盖性、区分性与可执行性三类信息。描述不是文档，是决策输入；描述质量不是文笔问题，是接口契约问题；描述治理不是一次性润色，是嵌入 CI 的持续工程。

展望未来，本文判断三个方向值得关注。其一，描述规范的标准化：类似 OpenAPI lint 的 MCP 描述检查器可能出现，覆盖度与区分度成为发布门禁。其二，描述与检索的协同：当工具规模膨胀，描述将同时服务于“给模型读”与“给检索器匹配”，写作规范需兼顾两种消费方式。其三，自动化描述生成与评测闭环：基于日志与意图集自动生成候选描述、自动评测、自动回归，把描述治理从人工评审推向半自动化。

最后需要重申本文的克制立场：描述工程能显著降低静默失败，但它不是万能药。工具设计、检索前置、schema 规范、模型能力，任何一环的短板都可能让描述优化事倍功半。把描述放在正确的系统位置上看待，才是工程上成熟的态度。

主要参考文献

说明：本文参考文献与资料检索覆盖 2022–2025 年，近三年文献占比超过 50%。文中模拟实验数据已明确标注为模拟数据；涉及数据集（如意图-工具标注集）的预处理细节为：日志脱敏、意图去重、双人交叉标注、分歧仲裁剔除，样本量 200 条。引用请以原始文献为准。