北京
MCP（Model Context Protocol）工具定义，是智能体与外部工具之间的唯一接口。但接口写得好不好，目前几乎没有标准化的检查手段。SitePoint 团队最近开源了一个 TypeScript CLI 检查器，用五个维度的加权评分，把"定义质量"这件事从玄学变成了可量化的数字。
为什么要较真这件事？因为 LLM 在选择工具时，能看到的信号只有三个：name、description 和 inputSchema。描述写得含糊、参数类型缺失、约束条件没声明，模型就只能靠猜。猜的结果就是幻觉调用、路由错误的工具请求，以及白花花的 Token 消耗。
五个维度，对应五种故障模式
这个检查器把质量拆成五个加权维度，每个维度对应一类典型问题：
- Schema 有效性（30%）：用 Ajv 做元验证，捕获会导致运行时崩溃的结构性 JSON Schema 错误
- 描述质量（25%）：用长度和行动动词启发式规则，对模糊或填充式开头扣分
- 参数完整性（25%）：检查每个属性是否都有类型和描述，且 required 是否声明
- 命名规范（10%）：强制使用 kebab-case / snake_case 的动词-名词格式
- 约束丰富度（10%）：标记无约束的字符串——这是格式错误智能体输入最常见的来源
权重分配不是拍脑袋。Schema 错误直接导致运行失败，所以权重最高；描述和参数是模型决策的主要依据，各占四分之一；命名和约束属于锦上添花，但缺失会显著增加误用概率。
按比例扣分，不做一刀切
这套验证机制最聪明的地方，在于惩罚是按比例缩放的，而不是二元制的通过/失败。举个例子：一个工具定义了十个属性，只有一个缺类型描述，它付出的代价会远小于十个属性全部缺失的情况。
这种设计避免了断崖式评分——不会因为一个小瑕疵就把整个定义判死刑，同时保留了可操作的粒度。团队能清楚地看到，扣分到底扣在哪个属性上，而不是面对一个笼统的"不合格"。
三个阈值，直接对接 CI/CD
最终分数映射到三个状态阈值，每个都有明确的行动含义：
- PASS（≥75）：生产就绪，可以放心交给智能体调用
- WARN（50–74）：功能基本可用，但存在显著差距，建议修复
- FAIL（<50）：存在智能体误用的真实风险，必须打回重写
这套阈值设计得很务实。它不是为了给开发者添堵，而是给团队一个清晰的 CI/CD 质量门禁集成点。代码合并前跑一遍检查器，分数不达标就不放行，比事后在线上发现幻觉调用要便宜得多。
为什么说这是必要而非可选
SitePoint 团队在文章里点破了一个核心事实：MCP 工具定义是智能体与工具之间的唯一接口，定义质量直接决定智能体的可靠性。原文里有一句话说得挺直白："写得糟糕的定义会直接导致智能体幻觉、路由错误的工具调用和 Token 浪费，因为模型在努力解读模糊的 Schema。"
另一个值得注意的观察是："在实践中，无约束的字符串是最常见的格式错误智能体输入的源头之一。"这解释了为什么约束丰富度虽然只占 10% 权重，却被单独列为一个维度——它防的是最高频的坑。
最后那句比喻也挺妙："一张图片可能在技术上响应正确，但仍然看起来很糟。"工具定义同理——Schema 合法不代表定义好用，模型能不能准确理解并调用，才是真正的质量标准。
这套检查器把"定义质量"从主观感受变成了可执行的数字门槛。对于正在把智能体推向生产的团队来说，这算是一个成本极低但收益明确的工程质量工具。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
