MCP 选错工具，先检查描述是否含糊

MCP 工具都注册好了，schema 也合法，Agent 还是可能选错：用户要更新发票，它却调用了创建接口。作者把问题指向一个容易被忽略的地方：模型挑工具时，要靠服务端提供的名称和描述辨别用途，接口能正常调用，不代表模型能正确选择。

这篇值得读的地方，是把「优化工具描述」从文档润色变成了接口设计问题。不过，作者给出的是排查思路和经验判断，没有提供错误率或模型对照数据，不能据此认定所有误调用都能靠改描述解决。

工具描述为什么会把 Agent 带偏

作者列出了三种常见问题，自动从 OpenAPI 生成 MCP server 时尤其容易出现。

第一种是重复方法名。getInvoice 的描述只有「Get invoice」，没有说明什么情况下应该调用，也没增加任何决策信息。

第二种是相邻工具描述雷同。列表和搜索都像是在「找发票」，用户的自然语言请求又不一定包含接口名称，模型就缺少区分依据。

第三种是没有写出边界。创建与更新、草稿与发布，动作相近，但调用条件不同。如果描述不解释差别，就把判断工作留给了模型。

原文用下面这段示意说明，两个描述可以语法正确，却无法帮助选择：

// what the model has to choose from (weak) { name: "list_invoices", description: "List invoices" }, { name: "search_invoices", description: "Search invoices" } // Both look like "find invoices"; the agent picks arbitrarily.

要看的是两个 description：它们只复述了动作，没有交代列表与搜索各自适用的条件。这是工具定义的示意，并非完整的可执行配置。

作者认为，这类问题容易被误诊为模型能力不足。模型即使更强，也需要服务端提供足够的区别信息。不过，原文把相似描述下的选择称为「猜测」，属于解释性判断，没有展示实际调用记录。

好描述要告诉模型何时选旁边那个工具

作者建议用 1-2 句话回答三个问题：工具做什么、什么时候用、什么时候不用。

描述最有价值的部分，往往是它与相邻工具的分界条件。

这里的「分界条件」并不玄：请求里是否有 ID，是否需要过滤条件，是否会改变资源状态，都可能决定应该调用哪个操作。具体条件必须来自真实接口行为，不能为了让描述显得明确而自行添加。

「不要使用」也有作用。它可以把模型从容易混淆的工具引向另一个工具，而不只是介绍当前工具能做什么。原文特别强调这一点，但没有给出修改后的完整工具定义，读者仍需结合自己的 API 补齐。

描述也不是越长越好。作者建议把简短触发语留在描述里，把结构化参数示例放进输入 schema。这样，描述负责选择动作，schema 负责表达输入结构和示例，避免重复细节掩盖真正的区别。

如果两个操作连使用意图都无法区分，就应考虑是否合并暴露，而不是继续堆描述。

为什么要回到 OpenAPI 修改，而不是只改 MCP 层

从 OpenAPI 生成 MCP server 的团队，容易出现两份说明：规范里一份，生成后的工具描述又手动维护一份。

问题在于，接口行为和参数以后可能变化。只修 MCP 层，重新生成时可能丢失修改，也可能留下与真实 API 不一致的描述。因此，作者主张在 OpenAPI 源头补充操作说明，让生成器把用途、参数信息和使用边界带入工具定义。

这套做法有一个前提：生成器确实会读取并输出这些内容。原文没有说明具体生成器，也没有提供配置方式，落地时需要检查最终暴露给模型的描述。

作者提出的复查流程很直接：

1. 列出全部工具，遮住名称，只读描述，判断能否知道何时使用。
2. 找出相近工具，写明彼此的区分条件。
3. 重跑同一个用户请求，再测试之前失败的模糊表达。
4. 把修正落回 OpenAPI，确认重新生成后仍然有效。

这套流程的重点是验证「选中了哪个工具」，接口能返回成功还不够。

我的判断

我认同把描述当作工具契约的一部分。API 文档通常帮助人理解接口，MCP 描述还承担了引导模型选择动作的职责。复用 OpenAPI 文本可以减少维护成本，但前提是这些文本包含决策信息。

相比直接换模型，先检查相邻工具有没有清楚的边界，是合理的排查顺序。它改动范围小，也方便用同一批请求比较结果。

但「最便宜的可靠性杠杆」仍是作者的经验判断。原文没有交代模型、工具数量、测试样本或修改前后的准确率。描述改善能否解决某次误调用，需要复测；即使选对工具，也仍需检查参数和执行结果。

另外，描述必须忠实于接口。如果真实 API 的职责就重叠，文字只能缓解歧义，不能代替接口整理。作者提出合并意图相同的工具，这比无限加长说明更值得考虑。

能拿来做什么

• 维护 Node MCP server 时，先检查列表与搜索、创建与更新、草稿与发布等相近操作，为每组写出真实的选择条件。
• 如果工具由 OpenAPI 生成，就在规范源文件中修改说明，并检查生成后的工具文本是否保留了这些条件。
• 把曾经选错工具的用户原话留作回归用例，修改描述后重跑，同时检查所选工具及输入参数。
• 给日常 AI 编程工具写描述时，用 1-2 句话明确用途和边界，把结构化参数示例放入输入 schema，避免把说明写成方法名的扩写。