04 - 工具系统

模型看到的 Read 工具完整定义长这样：

{
  "name": "Read",
  "description": "Reads a file from the local filesystem. ...",
  "input_schema": {
    "type": "object",
    "properties": {
      "file_path": {
        "type": "string",
        "description": "The absolute path to the file to read"
      },
      "limit": {
        "type": "integer",
        "description": "The number of lines to read. Only provide if the file is too large to read at once."
      },
      "offset": {
        "type": "integer",
        "description": "The line number to start reading from."
      },
      "pages": {
        "type": "string",
        "description": "Page range for PDF files (e.g., \"1-5\")."
      }
    },
    "required": ["file_path"]
  }
}

• description 里写使用时机和副作用比写"功能描述"更有价值，模型决定是否调用时主要靠它
• required 严格，缺了字段 API 侧会直接拒绝，不进模型
• 可选参数的 description 应当说明"什么时候需要填"

模型响应：

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_A", "name": "Read", "input": { "file_path": "a.ts" } },
    { "type": "tool_use", "id": "toolu_B", "name": "Read", "input": { "file_path": "b.ts" } },
    { "type": "tool_use", "id": "toolu_C", "name": "Grep", "input": { "pattern": "TODO" } }
  ]
}

客户端并发执行完之后的回填：

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_A", "content": "export function a() { ... }" },
    { "type": "tool_result", "tool_use_id": "toolu_B", "content": "export function b() { ... }" },
    { "type": "tool_result", "tool_use_id": "toolu_C", "content": "src/a.ts:12: // TODO: refactor" }
  ]
}

关键点：三个 tool_result 打包在同一条 role:user 消息的 content[] 里，不是三条独立消息。顺序可以不一致，用 tool_use_id 配对。

{
  "type": "tool_result",
  "tool_use_id": "toolu_01ABCD",
  "content": "ENOENT: no such file or directory, open 'missing.md'",
  "is_error": true
}

模型看到 is_error: true 后会：

1. 在输出里解释发生了什么
2. 决定是重试（换参数）、换工具（Glob 找一下文件）、还是放弃并向用户报告

不要在客户端层面吃掉工具错误——模型需要错误信息做判断。