给 AI Agent 设计工具调用契约，再开放函数

模型提出工具调用，真正决定是否执行的是你的应用。因而一份工具契约必须有两面：模型可见的接口帮助它判断何时调用、怎样填写参数；执行端强制落实的规则负责检查身份、条件、外部效果和返回状态。描述写得好不能代替权限校验；后端限制再严，如果描述模糊，模型仍可能在错误时刻调用。

每个有意义的操作单独写契约。“管理客户账户”藏着太多不同后果；“读取这个账户可用的服务政策”和“为已批准工单预约一次上门服务”则可以分别测试。下面的做法把工具定义和真正执行它的系统连起来。若工具来自外部 MCP Server，还要先用第三方 Server 准入清单核查整台连接实际暴露的能力与数据路径。

先把模型可见的接口收窄

名称只表达一个动作。描述写清什么时候该调用、会拿到什么证据、什么时候不该调用。必填参数要有类型、单位、允许的取值和明确含义。调用者不应猜测日期是本地时间还是 UTC，编号属于客户还是工单，字段缺省是否意味着“所有”。

可信上下文不要交给模型填写。应用可以从登录会话绑定真实使用者、租户与已批准范围。模型生成的 user_id 只是待核验数据，不能证明它就是该用户。执行端仍要检查必填字段、范围、对象之间的关系和多余参数，才能调用底层服务。

契约字段	必须回答的问题
输入结构	哪些字段必填，有什么类型、取值范围及相互依赖？
前置条件	执行前，记录状态或资料版本必须满足什么条件？
授权	执行端检查哪个身份、租户范围和针对本次动作的审批？
外部效果	会改变什么，谁能看见，哪些后果无法撤回？
重复调用	怎样识别同一次业务意图，识别有效期多长？
结果状态	成功、拒绝、普通失败和远端状态未知怎样区分？
复核轨迹	如何还原请求、检查、效果与结果，同时避免泄露秘密？

把具体结构放在文字说明旁边

下面是只读案例的平台中立示意。不同平台支持的结构写法可能不同，应按实际接口调整；执行端检查仍要由应用完成。

{
  "name": "get_approved_policy_excerpt",
  "description": "仅用于已批准的保修政策问题；返回适用来源片段，不直接替用户做决定。",
  "parameters": {
    "type": "object",
    "properties": {
      "policy_id": { "type": "string", "description": "当前账户中的政策编号" },
      "jurisdiction": { "type": "string", "description": "适用地区代码" },
      "effective_on": { "type": "string", "description": "YYYY-MM-DD 格式的日期" }
    },
    "required": ["policy_id", "jurisdiction", "effective_on"],
    "additionalProperties": false
  }
}

登录员工和账户没有放在模型提供的参数中，因为服务器会从会话绑定它们。一次写入超时可以示意为 { "status": "unknown", "code": "REMOTE_TIMEOUT", "operation_id": "visit-42", "next_action": "lookup" }。这个结果指出下一步要查询，而不是假定写入失败。

写明外部效果和重复调用规则

只读工具也要限制资料范围。写入工具则要写清目标对象和可见后果。例如预约服务可能同时占用一个时段并向客户发通知；即使底层只调用一次 API，也产生两个效果。契约要规定何时需要人工批准，以及批准绑定哪些具体参数。客户或日期改变后，旧批准不能继续使用。

同一业务意图的重复写入，应由应用生成稳定的操作标识。执行端要说明去重有效期，以及同一标识搭配不同参数时会怎样处理。仅仅传了 idempotency_key，不代表下游真的不会重复执行；必须验证底层服务或适配层的实际行为。超时后若不确定远端是否已执行，应返回明确的 unknown 状态和查询线索。不要把“未知”写成普通“失败”，诱导下一次写入。

结果状态可以收敛为 succeeded、rejected、failed、unknown。每个结果带稳定的机器可读错误码、简短说明和下一步允许的动作。缺少审批与参数格式错误不同；它们也都不同于“请求可能已被远端接收”的超时。部分成功时，不能只返回一句“成功”。

案例一：只读的政策片段查询工具

get_approved_policy_excerpt 回答维修人员对设备保修政策的疑问。参数包含政策编号、适用地区和生效日期；真实员工身份和可访问的账户范围由应用绑定。检索前，执行端确认员工可以查看该账户，且所选政策版本在指定日期有效。结果给出短片段、版本、生效区间和引用位置，而不是由工具凭空生成一段泛化答案。

模型可见的说明写清：只有查询已批准政策时才调用；没有符合条件的内容，就返回“无适用片段”。测试集中包括普通查询、过期版本、其他账户的编号，以及没有匹配政策的日期。即使模型很确信另一个账户的编号，执行端也必须拒绝。轨迹保存政策版本与权限判断，不再额外复制一份完整的受限文档。

案例二：预约一次上门服务的写入工具

schedule_equipment_visit 接收已批准工单编号、时段编号和发给客户的简述。应用绑定客户，并生成稳定的操作标识。执行端检查工单是否批准、时段是否仍有空位、调用者是否有预约权限，以及审批凭据是否正好对应这个客户、时段和简述。契约写出的效果是一笔预约和一条确认通知。

合格结果应包含预约编号、通知状态和操作标识。假设预约成功，但通知服务超时：结果要写明预约已完成、通知为 unknown，不能再次提交预约。后续查询应使用通知线索核实状态。测试还应包括重复请求、拿旧审批改时段、时段已满，以及预约成功后发生超时。这些情况才真正检验接口行为，而不只是检验参数表是否漂亮。

从模型和执行端两侧复核

给每份定义配一条真实或模拟调用轨迹：模型请求、规范化参数、后端校验、身份与审批判断、下游操作编号、实际效果和返回结果。隐藏令牌和隐私输入，同时保留足以让授权复核者还原判断的标识。写清工具负责人，以及结构或行为变化时何时要升版本。

让一位复核者只看描述，判断该不该调用；让另一位看执行契约，预测参数无效、重复、越权与超时时会发生什么。两人理解不一致，就说明接口仍靠没有写出的假设运转。多个工具调用可能同时出现时，还要写清依赖和效果顺序；彼此独立的读取，与对同一记录的两次写入不能一概而论。

常见问题

有 JSON Schema 就足够了吗？

不够。它主要描述参数结构，不能单独证明用户身份、当前记录状态、审批、下游去重能力或超时的含义。不同提供商支持的结构特性也有差异，仍要测试实际接入效果。工具参数之外，面向用户或下游系统的最终回答可用输出协议检查表单独选择格式并设计解析失败出口。

错误消息应该给模型看，还是给运维人员看？

返回稳定错误码和模型可使用的安全短句，再附上仅供授权人员查询的轨迹编号。不要把凭据、隐私资料或内部原始异常直接送回模型上下文。

不适用边界

本页设计的是单个可调用操作，不能替代系统级权限策略、事故恢复或安全评审。涉及付款、医疗判断、生产环境修改等高影响动作时，契约经过审查也不等于自动执行已获得授权。若底层服务无法判断某次效果是否发生，应让人先核实，不能假装重试一定安全。