AI Agent 工具调用的参数校验边界

AI Agent 工具调用的参数校验至少有三层：schema 检查形状，业务规则检查值是否合理，服务端权限检查当前身份是否允许访问目标资源。模型生成了合法 JSON，并不意味着工具可以立即执行；权限不能由模型填写的角色字段决定，失败也不能伪装成空结果。

以一个虚构的只读工单查询工具为例：调用方提交工单编号和返回条数，工具只允许查询当前账号所属项目。以下是设计分析，不是真实事故复盘、攻击演示或已执行测试。

从“参数合法却不该执行”拆开故障假设

假设页面提示查询成功，却显示了不属于当前项目的工单。沿调用记录分析时，首先区分三种“通过”：参数解析通过、资源授权通过、业务执行成功。它们不是一个布尔值。

一种可能的设计缺陷是：实现只检查工单编号为字符串，随后按编号直接读取，没有把可信身份限定的项目范围带入查询。即使 schema 没有任何语法错误，也拦不住这种授权缺失。这里只解释可能根因，不据此推断某个真实服务存在问题。

schema 表达输入契约，不替代业务含义

可以把这个工具的公开输入限定为工单编号 ticket_id 和返回条数 limit：前者为非空且长度受限的字符串，后者为有上限的整数。是否允许省略 limit、默认值由哪层补齐，都要明确写进服务实现，而不只写在工具描述里。

JSON Schema 的 properties 不会自动让字段变成必填；需要用 required 声明。希望拒绝额外字段时，可在适用的对象定义中使用 additionalProperties: false。这里说的是 JSON Schema 能力，具体模型服务或SDK支持哪些关键字，应按所用实现确认，不能照搬为通用兼容承诺。参见 官方对象字段规则。

对于业务约束，仍需自行定义工单编号如何匹配、limit 上限如何执行以及查询范围。不要一边默默把字符串转换成数字，一边在错误返回里声称“严格校验”；转换规则若确有必要，应成为可解释的公开契约。

资源权限来自可信上下文

工具名称、schema 以及模型发来的参数都不是登录会话。可信身份应来自服务端已经验证的会话或授权凭据，而不是请求体里的 user_id、tenant_id、is_admin 等自报字段。

对工单查询，本例建议让权限策略把可信身份映射为项目范围，再让工单资源查询显式受该范围约束。不接受模型通过切换项目参数来扩大权限；若业务允许指定项目，服务端仍要判断该项目是否属于此身份的可访问集合。

还要让运行工具的服务身份只具备完成任务所需的能力。只读查询不应顺带拥有删除工单的权限；模型提示词中的“仅查询”不构成底层访问控制。默认拒绝和按请求检查权限的原则，可参考 OWASP 授权指南。

若资源不存在与资源无权访问需要统一对外响应，以避免泄露资源存在性，也应作为明确的产品策略；内部脱敏审计可以记录真实分支，但不要把其他项目名称或完整凭据返回给模型。

失败返回要告诉调用方能否继续

建议工具服务在内部区分参数错误、权限拒绝、资源不可用、暂时性依赖失败与结果未知。下面的名称是本例自定义状态，不是某个 Agent 平台的标准字段。

本例是只读查询；若以后扩展为有副作用的工具，重试前还需要独立的幂等设计。不要让 Agent 把所有异常都视为“再试一次”，更不要把数据库异常吞成空列表并返回成功。

若实现 MCP，协议错误和工具执行错误有不同表达，后者可在工具结果中使用 isError: true。不要把表中自定义业务状态直接冒充 JSON-RPC 错误码；应在协议约定允许的结果结构中映射，保持调用标识对应。参见 MCP 工具规范中的错误处理与安全要求。

用反例清单防止同类问题

读者落地时可在隔离测试环境准备以下反例：缺少工单编号、超长编号、limit 类型错误、超出上限、额外角色字段、其他项目资源，以及依赖超时。分别说明预期拒绝点、是否调用数据依赖和对外返回类型，不以“模型回答看起来正常”作为全部依据。

日志建议只保留调用标识、工具名、契约版本、拒绝类别和耗时等必要信息，参数需按数据分级脱敏。不要为了方便排错，把全部会话、完整令牌和工单正文默认写进日志。

工具描述写了不能越权是否足够？不够，描述帮助模型理解使用方式，真正的授权由服务端实施。

schema通过后还需要检查limit吗？需要确保实际执行层使用了受限值；只把规则发给模型而没有在服务端执行，不等于完成约束。

失败是不是都要交给模型自行修复？不是。可修正输入错误可以反馈字段信息，权限拒绝应停止，结果未知要核对状态，不能用统一重试掩盖区别。