要调试 AI agent 选错工具的问题，先还原模型当时看到的确切工具列表和上下文，再在不执行工具的情况下测试选择。许多故障源于名称、描述、参数结构重叠或上下文缺失，但 trace 也可能表明工具选择正确，只是返回了错误结果。
明确失败阶段前，不要修改提示词。
当前 MCP 工具规范会向客户端公开名称、描述、输入 schema 和可选输出 schema。这些都是可观察的契约，因此在归因于模型内部推理前应先检查它们。
准确划分故障类型
- 选择错误： 另一项可见工具更符合任务。
- 参数错误： 工具正确，但 ID、enum、权限范围或必填字段错误。
- 调用过早： Agent 在收集必要上下文或取得审批前调用了正确工具。
- 结果误导： 工具正确调用后端，但返回了含糊、过期或格式错误的响应。
- 执行不安全： 选择有效，但工具背后的授权、幂等性或审批失败。
这些情况需要不同改动。提供商响应在异步任务完成前就返回 ok 时，重命名工具无法解决问题。
获取确切的 trace 与工具集
记录模型及其版本、系统提示词、检索上下文、对话前缀、完整可见工具列表、工具定义、所选名称、参数、结果、策略决策和下游结果。
必须检查完整列表。只读两个可疑文件，可能漏掉插件或会话公开的第三项工具。故障运行中不可用的工具不可能解释当时的选择。
Agent 可观测性指南介绍了如何用一条 trace 将工具选择关联到后端影响。
并排比较相似工具
[
{
"name": "list_files",
"description": "List entries directly inside one directory.",
"inputSchema": { "directory": "string" }
},
{
"name": "search_files",
"description": "Find files whose path or content matches a query across a directory tree.",
"inputSchema": { "directory": "string", "query": "string" }
}
]
这些描述给出了不同输出和触发条件，schema 则进一步强化差异。“处理文件”和“查找文件”这种宽泛描述会迫使模型自行猜测边界。
检查共享动词、名词、描述、示例、必填字段和结果结构。如果两项工具表达的是同一用户意图，只是提供商实现不同，应尽可能公开一项语义化工具，并在内部选择提供商。
让参数贴合任务语言
使用 order_id、customer_id 和 deployment_id，而不是三个含义不同的 id 字段。添加 enum、格式、范围和描述。租户和用户范围应从经过身份验证的上下文推导，而不是由模型提供。
如果工具需要 agent 可能尚未获得的信息，应说明前置条件并返回稳定的上下文缺失错误。可以提供独立读取工具取得标识符，而不是接受猜测的自由文本。
MCP 工具设计指南介绍了输入约束和结构化错误。
在责怪选择前检查结果
结果应告诉 agent 发生了什么，以及下一步允许做什么。返回稳定状态、资源或操作 ID，以及轮询或审批要求。不要返回完整提供商 payload 或宽泛的成功字符串。
对于异步工作，应区分 accepted、running、completed 和 failed。创建仍在等待时就返回“已创建”，可能导致 agent 过早调用下一项工具。
构建仅测试选择行为的评估
固定模型、提示词、工具列表和相关上下文，只要求选择工具和参数，不允许执行。包含：
- 每项工具明确的正向用例；
- 最相似工具的近似用例；
- 缺少必要上下文的请求；
- 不应调用任何工具的请求；
- 检索内容中的恶意指令；
- 原始失败请求和脱敏版本。
重复运行非确定性用例并报告试验次数。每次只修改一个契约元素，再重跑同一组用例，以判断名称、描述、schema 或上下文改动是否有效。
修改范围最小的失败契约
可以重命名含糊工具、收窄描述、增加前置条件、约束参数、拆分混合读写操作，或合并无法区分的工具。无关工具导致冲突时，应减少任务可见的工具集。
系统提示词适合表达确实跨工具的工作流策略。如果歧义来自契约，不要为每次历史错误不断添加一次性规则。
只有选择通过后才重新启用执行
然后在隔离环境中测试有效、无效、未授权、重复、中断和受策略门禁控制的调用。模型选择正确工具，并不代表工具本身安全。
下方的提示词会在建议改动前还原并分类故障，同时保持执行关闭，因此可用于调试破坏性工具而不制造第二次事故。