规范增强提案（SEP）
SEP-1303：将输入验证错误作为工具执行错误

SEP-1303：将输入验证错误作为工具执行错误

社区译文；来源： MCP 29affa6b

本 SEP 已达到 Final 状态，并作为已接受设计的历史记录保留。 定稿后对协议所做的更改不会反映在此处。权威要求请参阅当前规范 及其变更日志。
字段值
SEP1303
标题将输入验证错误作为工具执行错误
状态Final
类型标准跟踪
创建日期2025-08-05
作者@fredericbarthelet
发起人无
PR#1303

摘要

本 SEP 提议将工具输入验证错误作为 Tool Execution Error，而不是 Protocol Error 处理。这项变更能让语言模型在其上下文窗口中收到验证错误反馈，使模型能够自行纠正并在无需人工干预的情况下成功完成任务，从而显著提高任务完成率。

动机

语言模型可以从工具输入验证错误消息中学习，并据此使用修正后的参数重试 tools/call，但前提是它们能在上下文窗口中收到错误反馈。Protocol Error 会由 MCP 客户端在应用层捕获。只有 Tool Execution Error 会作为 JSON-RPC 响应转发回模型。按照当前规范，模型无法看到这些错误消息，因而无法自行纠正，导致反复失败和糟糕的用户体验。

问题陈述

设想一个航班预订工具，它使用以下 zod 验证 schema 来验证出发日期：

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");

工具预期输入的 JSON Schema 只能描述正则表达式约束。日期是否已过去这一实际程序检查无法在此用 JSON Schema 表达。 即使模型提供的日期在语法上正确并通过 JSON Schema 验证，也无法保证该日期是在未来。当验证错误被触发并作为 Protocol Error 返回时：

  1. 模型收不到说明日期为何被拒绝的错误消息
  2. 模型会多次重复同一错误（例如，当用户只指定日期和月份或相对日期时，Cursor 通常会持续发送 2024 年的日期，并在完全不知道工具调用为何失败的情况下重复发送同一个 tools/call 请求 3 次）
  3. 尽管模型只要获得适当反馈便有能力自行纠正，任务仍会失败
  4. 用户会感到沮丧，并且必须手动干预

本提案的优势

  1. 提高任务完成率：模型可以自行纠正验证错误，无需人工干预
  2. 改善用户体验：减少失败并更快完成任务
  3. 发挥模型能力：现代 LLM 擅长理解并响应错误消息
  4. 减少 API 调用：模型在第一次出错时便能自行纠正，从而减少重试次数

规范

当前行为

工具错误规范目前给出了含糊的指导：

  • “Invalid arguments” 应作为 Protocol Error 处理
  • “Invalid input data” 应作为 Tool Execution Error 处理

这种歧义导致不同实现采用不一致的处理方式，致使有价值的错误反馈丢失。

提议的变更

通过以下变更澄清规范：

  1. 从 Protocol Errors 中移除“invalid argument”类别。
  2. 所有工具参数验证失败都应使用 Tool Execution Errors（将 invalid argument 和 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

实现

变更前（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
    }
  }
}

向后兼容性

这项变更向后兼容，因为它：

  • 不改变协议结构
  • 只是澄清现有的含糊行为
  • 保留所有现有错误类型和格式
  • 在不破坏现有实现的情况下改善行为

实现澄清后行为的服务器将为模型提供更好的自恢复能力，同时继续与所有现有客户端协同工作。

参考资料

SEP-1302：在 MCP 治理中正式定义工作组与兴趣组SEP-1319：将请求载荷与 RPC 方法定义解耦