工具描述为什么突然成了 Agent 工程的瓶颈 过去两年,MCP 协议快速从一项小众标准,演变成了 Agent 工具调用的事实上层基础设施。但伴随着这种爆发,业界也开始面对一个尴尬的事实:绝大多数 MCP 工具的描述质量,远低于 Agent 实际使用的需要。一份覆盖 856 个工具、103 个 MCP server 的实证研究指出,97% 的工具描述都至少存在一处质量缺陷,56% 的工具描述没有清
工具描述为什么突然成了 Agent 工程的瓶颈
过去两年,MCP 协议快速从一项小众标准,演变成了 Agent 工具调用的事实上层基础设施。但伴随着这种爆发,业界也开始面对一个尴尬的事实:绝大多数 MCP 工具的描述质量,远低于 Agent 实际使用的需要。一份覆盖 856 个工具、103 个 MCP server 的实证研究指出,97% 的工具描述都至少存在一处质量缺陷,56% 的工具描述没有清晰说明这个工具做了什么,89% 的工具描述从未告诉 Agent 应该在什么场景下使用或者不使用。
这种状况在 Agent 真正接入 MCP 工具之前看起来无害,但一旦模型开始用这些工具,问题就立刻显现。一个常见的现象是:Agent 在面对多个候选项时,不知道应该调哪个;或者调了一个明显不是最优的工具,却要花额外的几步来弥补;又或者在不该调某个工具的时候调了它,造成执行路径和用户预期不一致。这些问题都不是模型本身造成的,根源是工具描述没把"我是谁、什么时候该用我"这件事传达清楚。
在这种背景下,2026 年下半年开始出现一批专门给 MCP 工具定义打分的开源规范和审计工具,试图把"工具描述质量"从主观感受变成可量化、可比较、可在 CI 里卡阈值的工程指标。这件事的工程意义远超它看上去的范围:它正在把 Agent 工具生态从"任何人都能"接受谁发布的工具,推进到"必须有质量基线"才能被接受。
TDQS 的核心思路:六维加权 + 五级评级
TDQS 全称 Tool Definition Quality Score,是 Glama 这个 MCP 注册表在用的开放质量评估规范。它把每个工具的定义拆成六个加权维度来打分,每个维度 1 到 5 分。这六个维度分别是:目的清晰度(占 25%)、使用指南(20%)、行为透明度(20%)、参数语义(15%)、简洁结构(10%)、语境完备度(10%)。这六个维度合起来回答一个问题:工具描述是不是把"我做什么、什么时候用、什么时候不用、参数怎么填、行为怎么走、描述够不够"说清楚了。
评分出来后,再按五级 tier 把分数翻译成字母:A 是大于等于 3.5 分,被定义为"真正有用的定义";B 是大于等于 3.0 分,是合格线;C 是大于等于 2.0 分,有明显漏洞;D 是大于等于 1.0 分,严重不足;F 是小于 1.0 分,保留给兜底场景。B 是发布门禁的常见门槛 —— 任何 MCP server 想要进入高质量注册表,它的每个工具都需要达到 B 级或以上。
这个打分不是单看工具的描述文字,而是看"定义在 Agent 面前能否被理解"。换句话说,它评估的不是"作者写得认不认真",而是"模型读完之后能不能用对"。这种以效果为导向的评估,直接对应到另一个实证发现:写得更清楚的工具被模型选中的概率高出 2.6 倍。这个数据来自另一份对 10831 个 MCP 服务器的分析,这份研究还发现,只是重写工具描述,就能把下游任务成功率提升约 6 个百分点。这两个数字合起来,说明工具描述质量不是文档工作,是直接影响 Agent 表现的核心工程投入。
从工具到服务器:四维一致性评估
六个工具级维度之外,TDQS 还有四个服务器级维度,衡量的是工具集整体的一致性。这四个维度是 disambiguation(能否区分开同服务器里的相似工具)、naming consistency(命名是否遵循一致的约定)、tool count appropriateness(工具数量是否合宜)、completeness(工具面是否完备)。
这套设计回答了一个被低估的工程问题:即使每个工具单独写得都很好,如果服务器里有三个工具描述都"差"但内容互相覆盖,Agent 在它们之间还是选不对。这就是 disambiguation 维度的核心 —— 它评估的不是单个描述,而是描述之间的"区分度"。评估的时候用到的信息是 sibling tool names,也就是同一个服务器里其他工具的名字,因为 Agent 在选择时,通常只有这一层信息可以参考。
命名一致性评估看似小事,实际上对 Agent 工作流的影响非常大。一个服务器里的工具如果有的用驼峰、有的用 snake_case、有的用 kebab-case,Agent 在拼参数的时候容易搞错。这是工程实践里经常被忽视的细节,但 TDQS 把它上升成了可量化的指标。工具数量合宜性和工具面完备性则把"做得多不多"和"做得好不好"区分开,一个工具数量过多且重叠的服务器,即使每个单独工具都写得不错,在 disambiguation 上也会被扣分。
评分管线:四阶段、确定性优先
TDQS 在实现上把整个评分拆成四个阶段。前三个阶段负责提取上下文信号、做硬规则过滤、跑 LLM rubric,第四个阶段做后处理合并。这种设计有一个明确的原则:能确定的就用代码判定,只有不得不判的才让模型介入。具体来说,代码阶段处理参数数量、参数描述覆盖率、嵌套深度、union 分支数、注解是否填写这些结构性的事实,这些用代码提取是精确且可复现的。模型阶段只处理"描述把意图写清没"这种语义层面的事。
这种分段带来两个工程收益。第一个是成本可控:同一份定义如果没变,可以用 sha256 哈希跳过 LLM 调用直接复用上次分数。Glama 在注册表里维护了 228369 个工具评分、15036 个 MCP 服务器,但每次定义变化才触发重评,日常开销非常低。第二个是可解释:每个分数都附带维度级理由,工具维护者可以直接读出来知道"为什么是 C"以及"该怎么改到 B"。这种可解释性正是 TDQS 和黑盒打分最大的区别。
TDQS 的另一个工程取舍是,它把"工具描述"作为评分对象,而把"工具行为"排除在外。TDQS 的输入就是 MCP 客户端从 tools/list 收到的字段:name、title、description、inputSchema、outputSchema、annotations、sibling tool names。它不去实际调用工具、不去看源代码、不去验证行为正确性。这种取舍决定了 TDQS 的评估能在沙箱里完成,能在 CI 里运行,能在 MCP server 注册前跑一次。这种轻量化正是它能大规模铺开的关键。
从描述评分到协议审计:mcpscore 的另一条路
几乎和 TDQS 同期,另一个独立项目 mcpscore 也做了 MCP 质量审计工具,但它走了一条明显不同的路线。TDQS 重点评估"工具描述说什么",mcpscore 重点评估"服务器做对没有"。它把审计拆成四大类:Protocol(协议合规)、Primitives(原语)、Security & Auth(安全和鉴权)、Readiness(就绪度)。审计方式是连上一个真实的 MCP 客户端,检查协议行为和工具清单证据,所有规则都是 deterministic 的 —— 不调 LLM,不需要 API key,也不会真正调用工具。
这两条路线并不冲突,而是互补。TDQS 解决"我的工具描述好不好"的问题,mcpscore 解决"我的 MCP server 协议层对不对"的问题。一个完整的 MCP server 上线流程,理论上需要先跑 mcpscore 看协议合规,再跑 TDQS 看工具描述质量。mcpscore 给的反馈是"这个 server 不应该被注册";TDQS 给的反馈是"这个 server 可以被注册,但这个工具的描述需要改"。两者合起来,构成了 MCP server 完整的质量门禁。
mcpscore 还有一项和 TDQS 互补的设计:它把审计规则完全公开在文档里。每个审计分数都链回具体的规则说明,工具维护者可以查到"为什么扣分"。这种透明度和 TDQS 的可解释性思路同构,也说明 MCP 生态在质量评估这个新领域正在形成一套共同的工程价值观:评分要 deterministic、要可解释、要能在 CI 里卡门禁。
MCP 服务器质量评估的工程新基线
把 TDQS 和 mcpsore 放在一起看,可以看出 2026 年下半年 MCP 服务器质量评估正在收敛到五条基线。第一条基线是质量评估必须分维度可解释,不能给一个总分就完事。TDQS 的六个工具维度加四个服务器维度、mcpscore 的四类审计,都把"为什么是这个分"作为核心交付物。这种可解释性是工程改进的前提 —— 没有维度拆解,维护者拿到一个低分也不知道从哪改起。
第二条基线是质量评估必须能跑在 CI 里。TDQS 提供 npx CLI,mcpscore 提供 uvx CLI 和 GitHub Action。两个工具都支持设置 --fail-under 阈值,可以在 PR 合并时卡门禁。一个 MCP server 在合并前至少需要通过 TDQS 的 B 级 + mcpscore 的 80 分,这种双门禁正在成为社区基线。
第三条基线是质量评估必须 deterministic 或至少可复现。TDQS 用 sha256 哈希定义,mcpscore 完全不用 LLM 评分。两者都用代码做了能做的一切,只在必须语义判断的地方才动用模型。这种设计让分数可以缓存、可以 diff、可以审计。一个 MCP server 的定义变了多少,分数变了多少,整个版本历史都可以追。
第四条基线是质量评估必须把工具级和服务器级分开评估。一个工具单独写得不错不等于服务器质量好,服务器整体设计合理不等于每个工具都写得清晰。TDQS 用两个独立维度的设计应对了这一点,mcpscore 把 Security & Auth 等服务器级问题单独列出来。这种分层评估让维护者能更精细地定位问题。
第五条基线是质量评估必须考虑 Agent 选择场景。一个写得好的工具描述,在它和邻居一起出现时,可能突然不够清楚。这就是 disambiguation 维度的核心 —— 评估必须考虑"在 Agent 面前的真实环境",而不是孤立地看工具本身。mcpscore 把协议合规放在第一位也是同样的思路:评估的对象不是"写出来的代码",而是"运行时被 Agent 看到的样子"。
企业落地 Agent 工具链的实操启示
把这五条基线应用到企业内部的 MCP server 建设,可以直接得出三条实操启示。第一条是内部 MCP server 必须在发布前同时跑 TDQS 和 mcpscore 双门禁,任何一项不达标都不能进入 registry。这不是过度防御 —— 是因为 97% 的现有 MCP server 都有描述缺陷,企业自建的更容易掉到这一档里。先跑分再上线,比上线之后再补要省事得多。
第二条是工具描述的写作要从"写清楚我做什么"提升到"让 Agent 在我和其他工具之间选得对"。前者是单工具视角,后者是服务器视角。一个企业内部可能有 5 个不同的 MCP server 提供类似的能力,Agent 在它们之间选哪一个,取决于描述里关于"什么时候用我"的清晰度。TDQS 把这个清晰度量化为"Usage Guidelines"维度,占 20%,仅次于"目的清晰度"。
第三条是把 MCP 服务器质量评估嵌入到 CI 和监控里。不只在发布前卡门禁,还要在运行期持续监控,因为工具描述可能因为业务变化而失效。一个本来写得很好的"查询订单"工具,如果业务方加了"订单按地区过滤"的需求,而工具描述没更新,Agent 就会在不合适的时候调它。mcpscore 的 GitHub Action 可以在每次 PR 触发重评,这种持续门禁是质量稳定性的关键。
把这三条实操启示和 TDQS、mcpscore 的具体能力放在一起,可以看出 2026 年下半年 MCP 服务器质量评估正在把 Agent 工具生态推向一个新的工程基线:工具描述必须可量化、协议行为必须可验证、质量门禁必须嵌入 CI。这不是哪一个工具能撑起的标准,而是 TDQS 这类质量评分 + mcpscore 这类协议审计 + 社区共识共同撑起的工程基线。Agent 生态从"协议 + 工具"演进到"协议 + 工具 + 质量基线",这是 2026 年下半年最值得关注的进展。