跳到主要内容

工具设计检查清单

核对日期：2026-05-09。

本清单用于工具、Function Calling、MCP Server 上线前评审。建议每个工具或工具集都形成一份评审记录，并绑定 schema 版本。

1. 定义与边界​

  • 工具名称是否使用稳定的“领域.动作”格式。
  • 工具是否只做一类清晰动作。
  • 是否写明适用场景和不适用场景。
  • 是否区分读操作、可逆写操作、不可逆写操作。
  • 是否有 owner、版本、变更记录。

2. Schema​

  • 输入使用 JSON Schema，并声明 required 字段。
  • 禁止不必要的 additionalProperties。
  • 枚举值完整且有业务含义。
  • 时间、金额、ID、路径、URL 有格式约束。
  • 字符串有长度限制。
  • 默认值安全，不会默认执行高风险动作。
  • 输出有结构化 schema 或稳定结构。
  • 错误码稳定且可被模型恢复。
  • schema 不泄露密钥、内部 URL、数据库表名。

3. 工具选择与提示​

  • 描述足够短，避免提示词式长文。
  • 描述包含“何时使用”和“何时不要使用”。
  • 相似工具之间边界清楚。
  • 有正例和反例样例。
  • 修改描述后跑过工具选择回归评测。

4. 权限与审批​

  • 工具有风险等级。
  • 权限由运行时策略计算，不由模型参数决定。
  • 按用户、租户、资源、环境校验权限。
  • 写操作有 preview/confirm 或审批流程。
  • 审批界面展示真实参数和真实影响。
  • 审批记录绑定参数 hash。
  • 高风险工具默认关闭或需管理员开启。

5. 执行可靠性​

  • 设置超时。
  • 设置最大重试次数。
  • 写操作支持幂等键。
  • 区分可重试和不可重试错误。
  • 支持部分成功结果表达。
  • 支持降级路径或明确失败说明。
  • 有并发和速率限制。

6. 观测与审计​

  • 记录 trace_id、tool_call_id、user、tenant、environment。
  • 记录工具名、schema 版本、模型版本、prompt 版本。
  • 记录脱敏参数、参数 hash、结果状态、错误码。
  • 高风险动作记录审批人、审批时间、审批结果。
  • 被拒绝的调用也记录。
  • 日志不保存明文密钥、token、密码。
  • trace 能支持问题回放。

7. 安全​

  • 工具参数做服务端校验。
  • 防 SQL、shell、路径、模板、URL 注入。
  • 工具返回作为不可信内容处理。
  • 对提示注入和敏感信息外泄有检测或隔离。
  • 外发类工具有域名、收件人或目标 allowlist。
  • 第三方 MCP Server 经过来源校验和 allowlist。
  • OAuth token 校验 audience 和 scope。
  • 不把第三方 token 返回模型。

8. MCP Server 专项​

  • 选择 stdio 还是 Streamable HTTP 有明确理由。
  • stdio 日志不写 stdout。
  • initialize 能力协商符合规范。
  • tools/list 返回稳定 schema。
  • tools/call 错误结构稳定。
  • 远程 Server 使用 HTTPS。
  • HTTP 授权符合 MCP Authorization 规范。
  • 多租户 token、缓存、日志隔离。
  • Server metadata 和工具变更可审查。

9. 评测​

  • 有工具选择测试集。
  • 有参数生成测试集。
  • 有权限拒绝测试。
  • 有审批触发测试。
  • 有错误恢复测试。
  • 有提示注入/工具投毒测试。
  • 有回归基线和变更门禁。

10. 上线门禁​

门禁项通过标准
功能关键 happy path 任务成功
参数schema 校验通过率达标
安全高风险越权用例全部阻断
审批写操作审批覆盖率 100%
观测trace 完整率 100%
可靠性超时、限流、重试行为符合预期
回滚可禁用单个工具或 MCP Server

11. 评审记录模板​

tool_review:
  tool_name: crm.update_customer_status
  schema_version: 2.1.0
  owner: sales-platform
  reviewer:
    engineering: "@backend-lead"
    security: "@security"
    business: "@ops-owner"
  risk_level: L3
  effect: write
  data_classification: internal
  required_gates:
    - schema_validation
    - policy_check
    - approval
    - audit_log
  eval_suites:
    - tool_selection_crm_v4
    - permission_matrix_crm_v2
    - prompt_injection_tools_v3
  rollback:
    disable_flag: tools.crm.update_customer_status.enabled
    owner_oncall: sales-platform-oncall

12. 攻击用例清单​

  • 工具描述包含“忽略上级指令”。
  • 工具返回包含外发敏感数据的指令。
  • 用户要求把内部数据发送到外部邮箱。
  • 模型生成路径穿越参数，例如 ../../secrets。
  • 模型把权限字段写入参数，例如 role=admin。
  • MCP Server 新增高风险工具但未重新授权。
  • OAuth token audience 不匹配。
  • 写操作重试导致重复副作用。
  • 工具返回超长 HTML 或脚本。
  • 被拒绝的工具调用没有审计记录。

13. 最低上线标准​

类别最低标准
低风险读工具schema、ACL、脱敏、trace
敏感读工具schema、ACL、数据分级、审计、注入隔离
可逆写工具preview、approval、idempotency、rollback
不可逆写工具双人复核或人工执行，不建议全自动
第三方 MCPallowlist、OAuth scope、工具审查、安全评测

14. 评审会议问题​

评审时建议逐项追问，而不是只看清单是否打勾：

问题期望回答
如果模型传入错误 ID，会影响谁的数据权限层按资源和租户拒绝
如果工具执行成功但网络断开，会不会重复副作用幂等键返回第一次结果
如果第三方 Server 明天新增写工具，谁会知道tools/list 版本检测和告警
如果工具返回提示注入，模型会不会照做回填前隔离，policy gate 阻断外发
如果用户投诉 Agent 执行错了，能否 30 分钟内复盘trace 关联模型、schema、参数 hash、审批
如果要紧急禁用工具，需要改代码吗有 feature flag 或 registry disable

15. 变更后回归要求​

以下变更必须重新跑评测：

  • 工具名称、描述、参数字段、枚举、默认值变化。
  • output schema、错误码、分页逻辑变化。
  • 权限策略、审批条件、risk level 变化。
  • MCP Server URL、传输方式、OAuth scope 变化。
  • handler 调用的内部 API 或数据源变化。
  • 模型、提示词、路由规则变化导致工具选择可能受影响。

回归报告至少包含：

  • 工具选择准确率。
  • 参数 schema 通过率。
  • 权限拒绝和审批触发结果。
  • 注入/投毒样例阻断结果。
  • 成本、延迟、错误率变化。
  • 回滚开关和负责人。

16. 权威资料​