导语：在 AI Agent 通过 MCP 调用外部工具时，参数校验和错误回传决定了工具链是否可靠、可修复、可追踪。一个成熟的 MCP 工具不只是“能被调用”，还要在参数错误、业务失败、权限异常等场景下，把问题以模型和客户端都能理解的方式返回。🚦
一、为什么参数校验是 MCP 工具调用的第一道防线
MCP，即 Model Context Protocol，核心目标是让 AI 应用以统一方式连接外部工具、数据源和服务。按照 MCP 工具规范，服务端可以通过 tools/list 暴露工具名称、描述和 inputSchema，客户端再通过 tools/call 发起调用；工具入参通常由 JSON Schema 描述，便于模型理解参数结构，也便于服务端做基础校验，参考 MCP Tools 规范。
参数校验的价值主要体现在三点：第一，防止模型生成的参数格式不符合预期，例如把字符串传成数组；第二，避免非法业务输入进入后端系统，例如日期格式正确但日期已经过期；第三，降低安全风险，例如限制文件路径、SQL 条件、API 查询范围等。对于 AI 工具调用来说，模型并不总能一次给出完美参数，因此校验机制必须同时服务于“拦截错误”和“帮助模型修正错误”。🧩
二、MCP 工具参数校验通常分为三层
1. Schema 层校验
Schema 层是最基础的校验，通常检查字段是否存在、类型是否正确、枚举值是否合法、字符串格式是否匹配等。例如天气查询工具要求 location 为必填字符串，订单查询工具要求 orderId 符合固定格式。这一层适合写在工具的 inputSchema 中，让模型在调用前就知道参数要求。
2. 业务规则校验
业务规则往往无法完全用 JSON Schema 表达。例如“出发日期必须晚于当前日期”“用户只能查询自己有权限访问的项目”“金额不能超过账户余额”等。这类校验应放在工具实现内部完成，并返回清晰、可操作的错误信息。MCP 社区关于输入校验错误的讨论也强调，模型只有看到校验反馈，才可能自行修正参数并重试，参考 SEP-1303。
3. 安全边界校验
安全校验是最容易被忽视的一层。AI 生成参数时可能包含越权资源 ID、危险路径、过宽的查询条件或不合规的操作指令。开发者应采用白名单、权限检查、最小授权、参数长度限制、敏感字段过滤等方式，避免工具成为绕过系统安全策略的入口。🔐
三、错误回传的关键：区分“模型可修复错误”和“协议级错误”
在 MCP 工具调用中，错误并不应该一概当作系统失败处理。更合理的做法是区分两类错误：一类是模型可以根据提示修正的工具执行错误，另一类是客户端或协议层需要处理的协议错误。MCP Python SDK 文档指出，普通异常通常会被包装为工具执行结果，并通过 is_error 标记让模型读取；而 MCPError 这类协议错误会作为 JSON-RPC 错误传递给客户端，参考 MCP Python SDK 错误处理文档。
这一区分非常重要。假设模型调用“查询图书作者”工具，传入了不存在的书名。此时更适合返回工具执行错误，例如“未找到该书名，请提供准确标题”，因为模型可以据此换一个参数重试。如果服务端直接返回协议错误，错误可能被宿主应用截获，模型看不到具体原因，也就失去了自我修正的机会。
四、实用的错误回传设计建议
- 错误信息要具体：不要只返回“参数错误”，应指出哪个字段错误、当前值是什么、期望格式是什么。
- 避免泄露敏感信息：不要把数据库 SQL、访问令牌、内部路径、堆栈详情直接返回给模型。
- 给出可执行修正建议：例如“date 应使用 YYYY-MM-DD 格式，并且必须晚于今天”。
- 错误类型要稳定：可以在内部定义 validation_error、not_found、permission_denied、rate_limited 等类型，便于日志分析和客户端处理。
- 不要把错误当成功结果返回：如果工具执行失败，应使用错误标记或异常机制，而不是返回一段看似正常的文本。⚠️
五、推荐的工具调用处理流程
- 客户端通过 tools/list 获取工具清单和 inputSchema。
- 模型根据用户意图选择工具并生成 arguments。
- 服务端先执行 Schema 校验，拦截缺字段、类型错误、枚举错误等问题。
- 服务端继续执行业务校验和权限校验。
- 如果是模型可修复问题，返回工具执行错误，并提供清晰原因。
- 如果是协议错误、鉴权失败、工具不存在或请求结构异常，则交由客户端按协议错误处理。
- 记录结构化日志，包含工具名、错误类型、请求 ID、耗时和脱敏后的参数摘要。
一个好的 MCP 工具错误回传，不是为了“报错”，而是为了让 AI Agent 能继续完成任务。错误信息越清晰，模型越有机会自动修正参数，用户体验也越接近真实的智能协作。
六、落地时容易踩的坑
第一个坑是只依赖 inputSchema。Schema 能解决结构问题，但解决不了所有业务语义问题。第二个坑是错误提示过于模糊，导致模型反复用相同参数重试。第三个坑是把所有异常都包装成协议错误，使模型看不到可修复反馈。第四个坑是错误信息过度暴露内部实现，给安全留下隐患。🛠️
更稳妥的方式是：让 Schema 负责“参数形状”，让业务代码负责“参数含义”，让权限系统负责“能不能做”，让错误回传负责“下一步怎么修”。这样 MCP 工具既能保持协议层清晰，也能让模型在调用失败后具备继续推理和修复的空间。
总结
MCP 工具调用中的参数校验与错误回传，是 AI 工具链可靠性的核心组成部分。实践中应坚持分层校验、明确错误类型、区分工具执行错误与协议错误，并为模型提供可理解、可修正、不过度泄露信息的反馈。只有这样，AI Agent 才能从“调用工具”升级为“稳定地使用工具完成任务”。✅
