附录 E：Tool Definition 模板

Tool 是 Agent 可以调用的动作能力。好的 Tool 不是“把 API 暴露给模型”，而是为模型设计稳定、清晰、可恢复、可治理的行动接口。

Tool Definition JSON 模板

{
  "name": "read_file_range",
  "displayName": "Read File Range",
  "description": "Read a specific line range from a repository file. Use when the Agent needs a focused code snippet instead of the full file.",
  "version": "1.0.0",
  "riskLevel": "low",
  "idempotent": true,
  "sideEffect": "none",
  "requiresApproval": false,
  "permissions": [
    "repo:read"
  ],
  "inputSchema": {
    "type": "object",
    "required": ["repositoryId", "path", "startLine", "endLine"],
    "properties": {
      "repositoryId": {
        "type": "string",
        "description": "Repository identifier."
      },
      "path": {
        "type": "string",
        "description": "File path relative to repository root."
      },
      "startLine": {
        "type": "integer",
        "minimum": 1
      },
      "endLine": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["repositoryId", "path", "startLine", "endLine", "content", "truncated"],
    "properties": {
      "repositoryId": { "type": "string" },
      "path": { "type": "string" },
      "startLine": { "type": "integer" },
      "endLine": { "type": "integer" },
      "content": { "type": "string" },
      "truncated": { "type": "boolean" },
      "sourceRef": { "type": "string" }
    }
  },
  "errorModel": {
    "FILE_NOT_FOUND": "The file does not exist. Try search_code first.",
    "RANGE_TOO_LARGE": "The requested range is too large. Request a smaller range.",
    "PERMISSION_DENIED": "The user does not have permission to read this file."
  },
  "examples": [
    {
      "input": {
        "repositoryId": "order-service",
        "path": "src/main/java/com/company/order/state/OrderStateMachine.java",
        "startLine": 70,
        "endLine": 100
      },
      "output": {
        "repositoryId": "order-service",
        "path": "src/main/java/com/company/order/state/OrderStateMachine.java",
        "startLine": 70,
        "endLine": 100,
        "content": "...",
        "truncated": false,
        "sourceRef": "git://repo/order-service/file/src/main/java/.../OrderStateMachine.java#L70-L100"
      }
    }
  ]
}

Tool 设计检查

• [ ] 名称是否明确表达动作？
• [ ] 描述是否说明何时使用？
• [ ] 输入是否最小且可校验？
• [ ] 输出是否结构化？
• [ ] 是否避免返回完整原始大结果？
• [ ] 是否提供 sourceRef？
• [ ] 错误是否可恢复？
• [ ] 是否声明风险级别和审批要求？
• [ ] 是否记录审计事件？

风险分级建议