SEP-1303 解读：将 MCP 工具输入校验错误作为 Tool Execution Error 返回，让模型自主纠错

人工智能AI Agent工具调用【免费下载链接】specificationSpecification and documentation for the Model Context Protocol项目地址https://gitcode.com/gh_mirrors/specification2/specification点击查看免费下载导读本文深度解读 Model Context ProtocolMCP官方提案 SEP-1303当工具的输入参数无法通过业务校验如日期格式错误、值超出范围时服务端应将其作为isError: true的 Tool Execution Error 返回而非 JSON-RPC 协议级错误。这一变更的核心价值在于错误信息会进入大语言模型LLM的上下文窗口使模型能够基于错误反馈自动修正参数并重试从而显著提升任务完成率、降低人工干预。读完本文你将理解两类错误机制的边界划分、SEP-1303 的具体修改内容以及如何在 MCP Server 实现中落地这一行为。背景为什么校验错误必须对模型可见MCP 中tools/call的错误报告存在两种机制Protocol Errors协议错误以标准 JSON-RPC 错误响应返回如-32602 Invalid params由 MCP Client 在应用层捕获。Tool Execution Errors工具执行错误放在tools/call的 result 中以isError: true标记随正常 JSON-RPC 响应一起返回。关键区别在于只有 Tool Execution Errors 会被转发回模型。LLM 依靠上下文窗口中的错误反馈来学习并纠正下一次调用协议错误被 Client 拦截后模型根本看不到错误内容只能盲目重试反复失败。SEP-1303 正是为解决这一信息断层而提出其最终目标Status: Final2025-08-05 创建Issue #1303是把工具参数校验失败统一归入 Tool Execution Errors让错误信息进入模型的上下文窗口。问题场景一个航班订票工具的校验困境提案给出了一个极具代表性的例子航班订票工具使用zod对出发日期做业务校验departureDate: z.string() .regex(/^\d{2}\/\d{2}\/\d{4}$/, date must be in dd/mm/yyyy format) .superRefine((dateStr, ctx) { const date parseDateFr(dateStr); if (date.getTime() Date.now()) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: Dates must be in the future. Current date is formatDateFr(new Date()), }); } return true; }) .describe(Departure date in dd/mm/yyyy format);这里存在一个根本性的表达能力缺口工具的 inputSchemaJSON Schema只能描述正则层面的语法约束无法表达日期必须晚于今天这类运行时业务规则。因此即便模型给出的日期语法完全合法、通过了 JSON Schema 校验仍然可能在语义上不合法例如过去日期。当这种业务校验失败被当作 Protocol Error 返回时会产生连锁问题模型收不到日期被拒的原因模型反复提交同样类型的错误参数提案举例某些客户端在用户只提供日/月或相对日期时会一致地发送 2024 年日期并在毫无反馈的情况下把同一个tools/call重试 3 次本可以自我纠正的任务最终失败用户被迫手动介入体验受损。提案的收益让模型看得见错误将输入校验错误转为 Tool Execution Error 后收益是直接的更高的任务完成率模型能在无需人工干预的情况下自我纠正校验错误更好的用户体验失败减少、任务完成更快充分利用模型能力现代 LLM 擅长理解错误消息并据此调整行为减少 API 调用模型在第一次错误反馈后就自我修正显著降低盲目重试次数。规范变更消除两类错误的边界歧义当前行为SEP 提出时的规范状态SEP-1303 指出当时的 工具错误处理规范 给出的指引存在歧义Invalid arguments 应作为 Protocol ErrorInvalid input data 应作为 Tool Execution Error。从 2025-06-18 版规范docs/specification/2025-06-18/server/tools.mdx可以看到当时 Protocol Errors 明确包含Invalid arguments而 Tool Execution Errors 包含Invalid input data。这两个类别语义重叠、边界模糊导致不同实现各自为政有价值的错误反馈常常丢失。提案的修改SEP-1303 提出两项明确修改从 Protocol Errors 中移除 invalid arguments 类别所有工具参数校验失败统一归入 Tool Execution Errors即将invalid arguments与invalid input data合并为新的input validation errors类别。提案给出的规范文本更新如下## Error Handling Tools use two error reporting mechanisms: 1. **Protocol Errors**: Standard JSON-RPC errors for issues like: - Unknown tools - Server errors 2. **Tool Execution Errors**: Reported in tool results with isError: true: - API failures - Input validation errors - Business logic errors行为对比协议错误 vs 工具执行错误修改前Protocol Error模型不可见// Model submits past date request: { ... method: tools/call, params: { name: book_flight, arguments: { departureDate: 12/12/2024 // Past date } } } // Server returns Protocol Error response: { ... error: { code: -32602, message: Invalid params } } // Model retries blindly with another past date // This cycle repeats until failure修改后Tool Execution Error模型可见// Model submits past date request: { ... method: tools/call, params: { name: book_flight, arguments: { departureDate: 12/12/2024 // Past date } } } // Server returns Tool Execution Error (visible to model) response: { ... result: { content: [ { type: text, text: Dates must be in the future. Current date is 08/08/2025 } ], isError: true } } // Model understands the error and corrects itself request: { method: tools/call, params: { name: book_flight, arguments: { departureDate: 12/12/2025 // Future date } } }前后对比清晰地展示了核心差异修改后模型看到的是Dates must be in the future. Current date is 08/08/2025这条可操作的、语义化的错误消息而非一条冷冰冰的-32602 Invalid params从而能够一步到位地修正为正确日期。规范落地从 2025-06-18 到 2026-07-28 的演进验证SEP-1303 的修改最终被纳入后续正式规范。在 2026-07-28 版工具规范 中错误处理章节已按 SEP 精神重写Protocol Errors被明确限定为模型不太可能自行修复的、请求结构本身的问题未知工具Unknown tool畸形请求不满足 CallToolRequest schema 的请求服务器错误。 其返回形式仍是标准 JSON-RPC 错误例如-32602 Unknown tool: invalid_tool_name。Tool Execution Errors被明确界定为包含模型可用来自我纠正并重试的可操作反馈API 失败输入校验错误如日期格式错误、值超出范围——即 SEP-1303 新增合并的input validation errors类别业务逻辑错误。 返回形式为result中携带isError: true如{ jsonrpc: 2.0, id: 4, result: { resultType: complete, content: [ { type: text, text: Invalid departure date: must be in the future. Current date is 08/08/2025. } ], isError: true } }同时规范明确了客户端义务的强弱梯度客户端MAY将协议错误提供给模型但成功恢复的可能性较低客户端SHOULD将工具执行错误提供给模型以支持自我纠正。Schema 层面的约束从 schema/2026-07-28/schema.ts 中CallToolResult.isError字段的注释可以看到与 SEP-1303 完全一致的表述工具产生的任何错误都应放在 result 对象内并以isError: true标记而不是作为 MCP 协议级错误响应返回——否则 LLM 将无法看到错误发生并自我纠正而找不到工具服务器不支持工具调用等异常情况才应作为 MCP 错误响应返回。向后兼容性澄清而非破坏SEP-1303 明确声明该变更向后兼容不改变协议结构本身只是澄清既有模糊行为保留所有现有错误类型与格式在不破坏现有实现的前提下改善行为。采用澄清后行为的 Server将为模型提供更好的自我恢复能力同时继续兼容所有现有 Client。实现建议Server 端如何落地结合 SEP 与 安全考量章节 的要求Server 实现者在落地时应注意在工具函数内部捕获业务校验失败将其转换为result.content中的文本描述并设置isError: true错误消息要可操作明确说明失败原因与当前有效条件例如日期必须晚于今天当前日期是 08/08/2025让模型无需猜测即可修正仅对真正属于请求结构的问题未知工具、JSON-RPC 参数畸形才返回协议级错误-32602等服务端必须校验所有工具输入Security Considerations 中 Server 的 MUST 项校验失败走 Tool Execution Error 通道正是这一要求的自然延伸在 HTTP 传输场景下畸形请求如缺少协议字段会以400 Bad Request返回并伴随-32602见 basic/index.mdx这与工具业务校验失败属于完全不同的层级不应混淆。总结SEP-1303 是一个小而关键的规范澄清通过把工具输入校验错误从协议错误迁移到 Tool Execution Error它让 LLM 获得了自我纠错所需的上下文反馈直接改善了 MCP 生态中 Agent 任务的完成率与用户体验。该提案现已落地于 2026-07-28 版规范与 schema 注释中是 MCP Server 开发者应当严格遵循的错误处理基线。赞分享人工智能AI Agent工具调用【免费下载链接】specificationSpecification and documentation for the Model Context Protocol项目地址https://gitcode.com/gh_mirrors/specification2/specification点击查看免费下载相关推荐深入解析 Angular 错误 NG01101Wrong Async Validator Return Type异步校验器返回值类型错误深入解析 Angular 错误 NG01101Wrong Async Validator Return Type异步校验器返回值类型错误 导读 NG011前端Web框架CANN opbase 错误码 EZ0007 全解Invalid_Input_Dtype 输入数据类型校验错误CANN opbase 错误码 EZ0007 全解Invalid_Input_Dtype 输入数据类型校验错误 导读 EZ0007Invalid_Input人工智能算子库CANNAscendFay 数字人框架配置完整指南改对两个文件一次跑通Fay 数字人框架配置完整指南改对两个文件一次跑通 你在 system.conf 里填了 API 密钥重启后数字人还是不回话别急着怀疑密钥本身。先弄清上一篇终极黑苹果游戏性能调优指南告别卡顿拥抱流畅下一篇TrueNAS Middleware API完整参考开发者必备手册创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考