tool-schema-design

工具架构设计

让模型更容易选择安全且符合预期的调用，而不是含糊不清或具有破坏性的替代方案。

适用场景

• 添加或修订函数调用、MCP、插件或内部 Agent 工具。
• 将过载的 API 操作拆分为模型可用的操作。
• 减少错误的工具选择、格式错误的参数或虚构的字段。
• 记录授权、确认、幂等性和错误行为。

输入

收集受支持的用户意图、后端操作语义、所需凭据、操作者和租户范围、副作用、可逆性、延迟、速率限制、故障模式以及特定提供方的架构约束。获取有代表性的有效和无效请求。

输出约定

生成：

1. 工具边界决策和重叠分析。
2. 面向模型的名称和描述，明确说明适用和不适用条件。
3. 有效的参数架构，包括约束、示例和未知字段策略。
4. 副作用、确认、授权、幂等性、超时和错误约定。
5. 正向、边界、对抗性和工具选择测试。
6. 验证结果以及任何特定提供方的限制。

工作流

1. 为每个工具定义一种连贯的用户意图。将权限、副作用或必填字段不同的模式拆分为独立工具；避免工具集过小且名称难以区分。
2. 选择稳定的动词开头名称。编写描述，说明工具的功能、何时调用、何时不调用，以及它会更改哪些状态。
3. 根据用户意图设计参数，而不是照搬后端 SDK。只要求不可或缺的字段，对有限选项使用枚举，设置数值和长度范围，并说明格式和单位。有关组合和变更模式，请阅读 schema-patterns.md。
4. 如果运行时支持，则拒绝未知字段。使用单独的工具或明确的架构分支来表示条件结构，而不是仅依赖文字说明。
5. 将操作者身份、授权范围和可信租户上下文保留在服务端。不要要求模型提供运行时已知的机密或声明。
6. 在 JSON 结构之外定义执行语义：只读还是有变更、确认级别、幂等键、重试安全性、超时、部分成功和补偿操作。
7. 返回精简的结构化结果和稳定的机器可读错误代码。区分无效输入、授权被拒、需要确认、冲突、速率限制、依赖项故障和未知故障。
8. 使用相邻工具测试工具选择，并使用有效、缺失、额外、边界、恶意和过期输入测试执行。

将架构接入运行时之前，请使用 python3 scripts/validate_tool_schema.py tool.json --strict。结构错误始终会导致验证失败。严格模式还会针对审查发现的问题报错，例如自由格式的命令执行、由调用方控制的权限标志、凭据参数、任意 URL/路径接口、允许未知字段以及缺少有用的边界。structurally_valid 仅描述 JSON 结构；即使 strict_pass: true，也不代表已通过语义安全、授权、沙箱、提供方兼容性或实现认证。

安全与权限

• 在工具实现中强制执行授权；绝不要依赖模型描述充当安全边界。
• 对购买、发送消息、部署、删除、更改权限或其他影响重大的变更操作，要求明确确认。
• 除非用例和沙箱有此需要，否则不要暴露机密参数、原始凭据、不受限的 Shell 命令或任意 URL 和文件路径。
• 优先使用允许列表、限定范围的标识符、试运行、幂等键和可逆操作。
• 将工具输出放回模型上下文之前，应将其视为不可信输入。

验证

• 使用目标提供方解析并验证架构，而不只是依赖捆绑的结构／启发式验证器或通用 JSON Schema 验证器。
• 确认已声明所有必填字段、所有枚举值均可触达、数组定义了项的形状，并且对未知字段的处理方式与实现一致。
• 运行对比提示词，分别测试应选择此工具、相邻工具或不选择任何工具的情况。
• 验证被拒绝和需要确认的调用不会产生副作用。
• 对比实现行为、返回的错误和文档，检查是否存在偏差。

故障处理

• 如果提供方支持的架构功能不同，则缩减至受支持的子集，并在运行时验证中记录失去的约束。
• 如果工具选择存在歧义，则明确名称和描述，或合并无法区分的工具；不要依赖提示词顺序。
• 如果格式错误的调用仍然存在，则简化嵌套结构、移除冗余字段，并添加架构边界和服务端验证。
• 如果变更操作超时，则在重试前通过幂等键查询操作状态。
• 如果后端行为与约定冲突，则对影响重大的操作采取默认拒绝策略，并在发布前修复适配器。

示例

对于“让助手重新安排日历事件”，应将事件查询与变更操作分开；将变更操作命名为 reschedule_calendar_event；要求提供不透明的事件 ID、带时区的开始和结束时间戳，以及幂等键；将账户身份保留在服务端；拒绝未知字段；在会通知与会者时要求确认；返回预览或更新后的事件以及稳定的状态；并测试缺少时区、结束时间早于开始时间、事件已过期、日历未经授权、重复重试，以及与“创建事件”相近的提示词。