Claude Code Tool use

---

0. 定位声明

适用版本：Claude API（claude-sonnet-4-6 / claude-opus-4-6 / claude-haiku-4-5）；
          Claude Code CLI（v2.0+）；Agent SDK（TypeScript / Python）
前置知识：HTTP REST API 基础；JSON Schema 规范；对话式 AI 的 prompt/completion 概念；
          了解 Agent 与 Function Calling 的基本概念有助于理解本文
不适用范围：本文不覆盖 Prompt Caching 的细节；不覆盖 Anthropic 商业企业专属权限策略；
            不适用于 Claude 2.x 及更早版本（tool use 协议不同）

---

1. 一句话本质

Claude Code 的 Tool use 是什么？

你给 Claude 一份"工具说明书"，告诉它有哪些工具可以用（比如搜索网页、执行代码、读写文件）；Claude 自己判断什么时候该用哪个工具、怎么用，用完之后你把结果告诉它，它再继续工作，直到完成你交代的任务。

换句话说：AI 决策 → 人/系统执行 → 结果反馈 → AI 继续，这个循环就是 Tool use 的全部本质。

---

2. 背景与根本矛盾

2.1 历史背景

大语言模型（LLM）在 2022–2023 年快速普及后，业界迅速发现一个天花板：模型的知识是静态的，但现实世界是动态的。问今天的股价、查数据库、发邮件——这些操作语言模型天然做不到，因为它只能"说话"，不能"动手"。

OpenAI 于 2023 年 6 月为 GPT-4 推出 Function Calling，Anthropic 随后推出 Tool use，二者解决同一根本矛盾：让 LLM 具备与外部世界交互的能力，同时维持模型本身的安全可控边界。

Claude Code 将 Tool use 进一步产品化，预置了文件系统、Shell、浏览器、代码执行等核心工具，使开发者不再需要从零搭建工具调用循环。

2.2 根本矛盾（Trade-off）

对立约束	说明
自主性 vs 可控性	让 Claude 自己决定调用哪个工具（提升效率），还是每次都等人类确认（保证安全）？Claude Code 通过 Permission System 解决：读操作默认允许，写操作按策略确认
能力边界 vs 上下文开销	工具越多，Claude 能做的事越多，但工具定义本身消耗 token。5 个 MCP 服务器 × 平均约 12 个工具 × 每工具约 800 token ≈ 55,000 token 仅用于工具声明，严重压缩对话空间
并行效率 vs 执行顺序	多工具并行调用提升速度，但某些任务有依赖关系，必须串行

---

3. 核心概念与领域模型

3.1 关键术语表

术语	费曼式定义	正式定义
Tool（工具）	你告诉 Claude “你可以打电话给这个号码”	开发者在 API 请求中以 JSON Schema 格式声明的可调用函数契约
Tool use / Function Calling	Claude 说"我现在要打这个电话，号码是 XXX"	模型生成 tool_use 类型的内容块，指定工具名称和参数
Tool result	你把电话里对方说的话告诉 Claude	开发者将工具执行结果以 tool_result 内容块返回给模型
Agentic loop	Claude 打完电话听完回复后继续思考，直到把任务做完	多轮 API 交互形成的"模型→工具调用→结果反馈→模型"循环
Tool choice	控制 Claude 必须用/可以用/不能用工具	tool_choice 参数：auto（默认）/ any（必须选工具）/ tool（指定工具）/ none（禁用）
MCP（Model Context Protocol）	一套标准插座规范，让 Claude 能接任何厂商做的工具	开放标准协议，使 AI 工具统一接入外部数据源和服务
Built-in Tool	Anthropic 已经帮你预制好的工具，开通即用	由 Anthropic 在服务端维护的原生工具，如 web_search、code_execution、bash
Client-side Tool	工具的代码跑在你自己服务器上，你自己实现	开发者自定义、自行执行的工具函数

3.2 领域模型

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code / API                         │
│                                                             │
│  ┌──────────┐    tool_use request    ┌──────────────────┐  │
│  │          │ ──────────────────────▶│  Tool Registry   │  │
│  │  Claude  │                        │  ┌─────────────┐ │  │
│  │  Model   │                        │  │ Built-in    │ │  │
│  │          │ ◀──────────────────────│  │ bash        │ │  │
│  └──────────┘    tool_result         │  │ code_exec   │ │  │
│                                      │  │ web_search  │ │  │
│  Context Window:                     │  │ text_editor │ │  │
│  ┌────────────────────────────────┐  │  └─────────────┘ │  │
│  │ system_prompt                  │  │  ┌─────────────┐ │  │
│  │ user_message(s)                │  │  │ Client-side │ │  │
│  │ [assistant: tool_use block]    │  │  │ Custom Fn   │ │  │
│  │ [user: tool_result block]      │  │  └─────────────┘ │  │
│  │ [assistant: text / tool_use]   │  │  ┌─────────────┐ │  │
│  │ ...                            │  │  │ MCP Servers │ │  │
│  └────────────────────────────────┘  │  │ (300+ types)│ │  │
│                                      │  └─────────────┘ │  │
│                                      └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘

工具定义结构（JSON Schema）：

{
  "name": "get_stock_price",
  "description": "获取指定股票代码的当前价格。返回 USD 计价的实时价格。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "股票代码，如 AAPL、GOOGL"
      }
    },
    "required": ["ticker"]
  }
}

---

4. 对比与选型决策

4.1 内置工具 vs 自定义工具 vs MCP 工具

维度	Built-in Tool	Client-side Tool	MCP Tool
实现方	Anthropic 托管	开发者自行实现	第三方/社区
接入成本	极低（声明即用）	中（需实现执行逻辑）	中（配置 MCP Server）
可用工具	bash, code_exec, web_search, computer_use, text_editor	任意自定义	300+ 生态集成
执行环境	Anthropic 沙箱	开发者服务器	MCP Server 进程
额外计费	部分工具有（如 web_search 按搜索次数）	无额外费用	无额外费用
适用场景	快速原型、标准任务	私有数据、业务逻辑	企业系统集成

4.2 Claude Code Tool use vs OpenAI Function Calling

维度	Claude Code Tool use	OpenAI Function Calling
并行调用	✅ 原生支持（单轮多工具）	✅ 支持
强制工具	✅ tool_choice: any	✅ tool_choice: required
Structured Output	✅ strict: true（beta）	✅
内置工具	✅ bash/code_exec/web_search 等	✅ code_interpreter/web_search
MCP 支持	✅ 原生 MCP Connector	⚠️ 有限支持
Programmatic Tool Calling	✅ 代码化工具编排（beta）	❌
Computer Use	✅	❌
上下文管理	Compaction 自动压缩	无内置

4.3 选型决策树

需要 AI 调用外部能力？
├── 是标准任务（搜索/执行代码/文件操作）？
│   └── 直接用 Built-in Tools → bash/code_execution/web_search
├── 是私有业务逻辑（查数据库/调内部 API）？
│   └── 实现 Client-side Tools
├── 需要接入现有企业系统（Jira/Slack/GitHub）？
│   └── 配置 MCP Server（300+ 生态工具）
└── 需要在成千上万个工具中动态检索？
    └── 使用 Tool Search Tool（beta）

---

5. 工作原理与实现机制

5.1 静态结构：核心数据结构

工具调用的消息格式（tool_use block）：

{
  "type": "tool_use",
  "id": "toolu_01XFDUDYJgADygGyG4d5Agjx",
  "name": "get_stock_price",
  "input": {
    "ticker": "AAPL"
  }
}

工具结果反馈（tool_result block）：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01XFDUDYJgADygGyG4d5Agjx",
  "content": "当前 AAPL 价格：$213.45（更新于 2026-03-06 15:30 UTC）"
}

为什么用 JSON Schema 描述工具？ 因为 JSON Schema 是业界最成熟的类型约束语言，Claude 在训练时就学习了大量 JSON Schema 数据，理解 Schema 并生成符合结构的参数对模型而言是自然任务而非额外负担。

5.2 动态行为：Agentic Loop 时序

开发者                    Claude API              工具执行层
   │                           │                       │
   │──① POST /v1/messages──────▶│                       │
   │   (tools定义 + user消息)    │                       │
   │                           │──内部推理──▶           │
   │                           │                       │
   │◀──② 返回 stop_reason:──────│                       │
   │     tool_use              │                       │
   │     (tool_use block)      │                       │
   │                           │                       │
   │──③ 执行工具─────────────────────────────────────▶│
   │                           │                       │
   │◀──④ 工具结果────────────────────────────────────│
   │                           │                       │
   │──⑤ POST /v1/messages──────▶│                       │
   │   (含 tool_result block)   │──内部推理──▶           │
   │                           │                       │
   │◀──⑥ 返回 stop_reason:──────│                       │
   │     end_turn              │                       │
   │   (最终文本回答)            │                       │

关键 stop_reason 说明：

stop_reason	含义	开发者应对
tool_use	模型需要调用工具	解析 tool_use block，执行工具，返回 tool_result
end_turn	模型完成任务	提取文本输出，呈现给用户
max_tokens	超出 token 限制	考虑压缩上下文或增大 max_tokens
stop_sequence	遇到停止序列	检查业务逻辑

5.3 完整代码示例（Python，运行环境：Python 3.10+，anthropic SDK ≥ 0.40）

import anthropic

client = anthropic.Anthropic()

# 工具定义
tools = [
    {
        "name": "get_weather",
        "description": "获取指定城市的当前天气。返回温度（摄氏度）和天气描述。",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名称，如 Beijing、Shanghai"
                }
            },
            "required": ["city"]
        }
    }
]

def execute_tool(tool_name: str, tool_input: dict) -> str:
    """模拟工具执行层（实际生产中接真实 API）"""
    if tool_name == "get_weather":
        city = tool_input["city"]
        # 生产中这里调用天气 API
        return f"{city}: 18°C，晴转多云"
    return "工具未找到"

def run_agent(user_message: str):
    messages = [{"role": "user", "content": user_message}]
    
    while True:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=tools,
            messages=messages
        )
        
        # 将 assistant 回复加入历史
        messages.append({"role": "assistant", "content": response.content})
        
        if response.stop_reason == "end_turn":
            # 提取最终文本
            for block in response.content:
                if hasattr(block, "text"):
                    print("Claude:", block.text)
            break
        
        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            
            # 将工具结果加入对话
            messages.append({"role": "user", "content": tool_results})

run_agent("北京和上海今天天气怎么样？")

5.4 并行工具调用（Parallel Tool Use）

Claude 可以在单次响应中同时请求多个工具，显著提升效率：

// Claude 的单次响应可能包含多个 tool_use block
[
  {
    "type": "tool_use",
    "id": "toolu_001",
    "name": "get_weather",
    "input": {"city": "Beijing"}
  },
  {
    "type": "tool_use", 
    "id": "toolu_002",
    "name": "get_weather",
    "input": {"city": "Shanghai"}
  }
]

# 并行执行工具（实际生产中使用 asyncio 或线程池）
import asyncio

async def execute_tools_parallel(tool_blocks):
    tasks = [execute_tool_async(b.name, b.input) for b in tool_blocks]
    results = await asyncio.gather(*tasks)
    return [
        {"type": "tool_result", "tool_use_id": b.id, "content": r}
        for b, r in zip(tool_blocks, results)
    ]

5.5 关键设计决策解析

决策 1：为何选择"模型请求，外部执行"而非"模型直接执行"？

若让模型直接执行代码（如早期 Code Interpreter 的内嵌方案），安全边界极难控制，恶意 prompt 可绕过任意限制。当前设计将执行权保留在开发者/沙箱侧，模型只能"申请"，执行层才是"决策者"，符合最小权限原则。

决策 2：为何用 JSON Schema 而非自然语言描述工具参数？

自然语言描述模糊性高，参数类型、边界条件不明确，Claude 生成的参数容易出现类型错误（如字符串传给数值字段）。JSON Schema 提供机器可验证的精确约束，结合 strict: true 模式可实现 100% Schema 合规。

决策 3：为何上下文历史中必须保留完整 tool_use + tool_result 对？

Claude 依赖完整对话历史重建推理上下文。若仅保留 tool_result 而删除 tool_use，模型会"忘记"自己为什么调用了工具，导致幻觉或逻辑跳跃。这是 agentic loop 中最常见的错误之一。

---

6. Claude Code 内置工具详解

Claude Code CLI 预置了以下核心工具，开箱即用：

工具名	功能	权限级别	典型用途
bash	执行 Shell 命令	高（需确认危险操作）	运行测试、构建项目、Git 操作
text_editor	读取/写入/查看文件	中（写操作需确认）	代码编辑、配置修改
web_search	搜索互联网	低（默认允许）	查文档、搜索解决方案
web_fetch	抓取网页内容	低	读取在线文档
code_execution	在沙箱执行 Python	中（沙箱隔离）	数据分析、验证算法
computer_use	控制 GUI（截图/点击）	高（实验性）	自动化桌面任务
memory	跨会话记忆存储	低	保存项目上下文

Claude Code 权限系统

┌─────────────────────────────────────────┐
│         Claude Code 权限决策树           │
│                                         │
│  操作类型                               │
│  ├── 只读操作（ls, cat, grep）          │
│  │   └── 默认允许，无需确认             │
│  ├── 写操作（文件修改、创建）            │
│  │   └── 首次询问，可 "Always Allow"    │
│  ├── 破坏性操作（rm -rf、sudo）          │
│  │   └── 每次确认，不可记住             │
│  └── 网络操作                           │
│      └── 按策略配置                     │
└─────────────────────────────────────────┘

settings.json 配置示例（~/.claude/settings.json）：

{
  "permissions": {
    "allow": [
      "bash:git *",
      "bash:npm test",
      "bash:pytest *"
    ],
    "deny": [
      "bash:rm -rf *",
      "bash:sudo *"
    ]
  }
}

---

7. 高可靠性保障

7.1 工具调用可靠性机制

Structured Outputs / Strict Mode（Beta）：

# 启用 strict 模式，保证工具参数 100% 符合 Schema
tools = [{
    "name": "create_order",
    "description": "创建订单",
    "input_schema": { ... },
    "strict": True  # 开启后，Claude 的参数输出保证完全符合 Schema
}]

重试策略（生产推荐）：

import time
from anthropic import RateLimitError, APIStatusError

def call_with_retry(client, **kwargs, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.messages.create(**kwargs)
        except RateLimitError:
            wait = 2 ** attempt  # 指数退避：1s, 2s, 4s
            time.sleep(wait)
        except APIStatusError as e:
            if e.status_code >= 500:
                time.sleep(2 ** attempt)
            else:
                raise
    raise Exception("Max retries exceeded")

7.2 可观测性：关键监控指标

指标	说明	正常阈值	告警阈值
tool_use 调用成功率	工具调用后收到有效 tool_result 的比率	≥ 99%	< 95%
Agentic loop 轮次	单任务平均 API 调用轮次	2–8 轮	> 15 轮（可能死循环）
context_window 使用率	已用 token / 最大 token	< 75%	> 90%（触发截断风险）
工具执行延迟 P99	工具侧执行时间	< 2s	> 10s
stop_reason=max_tokens 比率	因 token 超限中断的比率	< 1%	> 5%
tool_result 错误率	返回错误状态的工具结果比率	< 2%	> 10%

7.3 容错设计

• 工具超时：对每个工具调用设置超时（推荐 30s），超时后返回错误 tool_result 而非挂起
• 工具错误处理：错误信息通过 tool_result 的 is_error: true 字段返回，让 Claude 自动重试或降级
• 上下文压缩（Compaction）：Claude Code CLI 在上下文达到 ~95% 时自动触发压缩，保留关键信息

---

8. 使用实践与故障手册

8.1 典型生产配置

完整的 Agentic Tool Use 生产示例（Python 3.10+，anthropic SDK ≥ 0.40）：

import anthropic
import json
from typing import Any

client = anthropic.Anthropic(
    # api_key 从环境变量 ANTHROPIC_API_KEY 读取
    max_retries=3,
    timeout=60.0  # 全局超时 60 秒
)

TOOLS = [
    {
        "name": "query_database",
        "description": (
            "查询业务数据库。返回 JSON 格式的记录列表。"
            "字段：id(int), name(str), amount(float), status(str: pending|completed|failed)"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "sql": {
                    "type": "string",
                    "description": "只读 SELECT 语句，禁止 INSERT/UPDATE/DELETE"
                },
                "limit": {
                    "type": "integer",
                    "description": "返回条数上限，默认 100，最大 1000",
                    "default": 100
                }
            },
            "required": ["sql"]
        }
    }
]

def execute_tool(name: str, inputs: dict) -> Any:
    """工具执行层 - 生产环境需对 SQL 做安全审查"""
    if name == "query_database":
        sql = inputs["sql"].strip().upper()
        if not sql.startswith("SELECT"):
            return {"error": "只允许 SELECT 查询", "is_error": True}
        # 实际连接数据库...
        return [{"id": 1, "name": "Order-001", "amount": 1500.0, "status": "completed"}]

def run_agent_task(task: str, max_rounds: int = 20) -> str:
    messages = [{"role": "user", "content": task}]
    
    for round_num in range(max_rounds):
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=TOOLS,
            tool_choice={"type": "auto"},
            messages=messages
        )
        
        messages.append({"role": "assistant", "content": response.content})
        
        if response.stop_reason == "end_turn":
            return next(
                (b.text for b in response.content if hasattr(b, "text")), ""
            )
        
        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    is_error = isinstance(result, dict) and result.get("is_error")
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": json.dumps(result, ensure_ascii=False),
                        **({"is_error": True} if is_error else {})
                    })
            messages.append({"role": "user", "content": tool_results})
        else:
            break
    
    raise RuntimeError(f"Agent 超过最大轮次 {max_rounds}，任务未完成")

8.2 故障手册

【故障 1：工具参数类型错误（Invalid Tool Input）】
- 现象：工具接收到的参数类型与预期不符（如数字字段收到字符串）
- 根本原因：工具 Schema 描述不够清晰，Claude 误解字段类型
- 预防措施：在 description 中明确标注类型、范围、单位；启用 strict:true 模式
- 应急处理：在执行层加类型转换和校验，错误通过 is_error:true 的 tool_result 反馈

【故障 2：Agentic Loop 无限循环】
- 现象：Claude 反复调用同一工具，轮次超过 15+，任务永不结束
- 根本原因：工具始终返回错误或空结果，Claude 陷入重试循环
- 预防措施：设置 max_rounds 上限（推荐 20）；工具失败后返回明确错误原因+建议
- 应急处理：中断 loop，返回当前最佳答案并上报异常

【故障 3：上下文窗口溢出（Context Overflow）】
- 现象：stop_reason=max_tokens，响应被截断，任务中断
- 根本原因：工具返回结果过大（如数据库查出 10,000 条记录）；对话轮次过多
- 预防措施：工具结果强制分页（建议单次 ≤ 2000 tokens 约 1500 汉字）；
           启用 Prompt Caching；使用 Claude Code 的 Compaction 功能
- 应急处理：实现滑动窗口，只保留最近 N 轮 + 系统 prompt；使用 /compact 命令

【故障 4：工具调用被拒绝（Permission Denied）】
- 现象：Claude Code 中执行某命令时提示 Permission Denied
- 根本原因：操作不在 settings.json allow 列表中
- 预防措施：提前在 CLAUDE.md 或 settings.json 中声明项目所需权限
- 应急处理：使用 --allowedTools 标志明确授权，或在会话中输入 y/always 确认

【故障 5：MCP 工具超时/断连】
- 现象：调用 MCP Server 工具时长时间等待或报连接错误
- 根本原因：MCP Server 进程崩溃、网络超时、资源耗尽
- 预防措施：为 MCP Server 配置健康检查；工具层设置 30s 超时
- 应急处理：重启 MCP Server 进程；检查 ~/.claude/mcp_servers.json 配置

8.3 边界条件与局限性

• 工具数量上限：单次请求建议工具数 ≤ 64 个；超过后每个工具的 token 消耗急增（每个工具定义约 200–1000 token），实测 5 个 MCP Server 共 58 工具可消耗约 55,000 token
• 并行工具的依赖问题：Claude 无法自动识别工具间的数据依赖，需开发者在 description 中明确说明
• 工具结果大小：单个 tool_result 建议 ≤ 100KB；超大结果会压缩上下文，导致早期信息被遗忘
• Computer Use 的可靠性：⚠️ 存疑 — Computer Use 工具目前处于 Beta 阶段，在复杂 GUI 场景（多弹窗、动态渲染）下可靠性不稳定，不建议直接用于生产关键路径

---

9. 性能调优指南

9.1 Token 消耗优化

调优目标：在保证工具调用准确性的前提下，将每轮 API 请求的 token 消耗降低 30%–50%。

策略	效果	操作方法
精简工具 description	节省 30–60% 工具定义 token	去除冗余描述，使用结构化格式代替散文
Prompt Caching	重复请求节省 90% 工具定义 token	对 tools 数组启用 cache_control: {"type": "ephemeral"}
Tool Search（beta）	千级工具场景节省 95%+	用 tool_search_tool 动态检索工具，不再全量加载
工具结果分页	避免上下文溢出	工具返回加 total/page/has_more 字段
Programmatic Tool Calling（beta）	减少中间工具结果积累	让 Claude 写代码批量处理，结果只返回摘要

9.2 延迟优化

策略	降延迟效果	适用场景
并行工具调用	减少 N-1 次网络往返（N 为工具数）	无数据依赖的多工具任务
选用 Haiku 模型	响应速度比 Sonnet 快 3–5x	简单工具路由、低复杂度任务
Streaming（SSE）	首 token 到达时间减少 50%+	需实时展示进度的场景
工具执行异步化	工具执行不阻塞主线程	Python asyncio / Node.js async

9.3 关键参数速查表

参数	默认值	生产推荐值	调整风险
max_tokens	无默认（必填）	4096–8192	过小导致截断，过大增加成本
tool_choice	auto	auto（保持默认）	强制 any 会增加不必要工具调用
temperature	1.0	工具调用场景建议 0–0.3	过高导致工具参数不稳定
max_retries（SDK）	2	3	过高可能放大 Rate Limit 影响
timeout（SDK）	600s	60s	过低在复杂任务中误超时

---

10. 演进方向与未来趋势

10.1 Programmatic Tool Calling（代码化工具编排）

现状（2025–2026）：Anthropic 推出了"让 Claude 通过写代码来调用工具"的新范式（beta）。Claude 生成 Python 代码，在 code_execution 沙箱中批量调用工具，结果只有摘要进入上下文。

实际影响：Claude for Excel 已用此方案处理数千行电子表格，传统 tool_use 方案因 token 爆炸根本无法处理此类场景。这标志着工具调用从"一次一个"迈向"批量编程式"，显著扩展了可处理数据规模的上限。

10.2 Tool Search + 大规模工具生态

现状：MCP 生态在 5 个月内从 10 万次下载增长到 800 万次（80 倍增长），300+ 集成已成为事实标准。

演进方向：Tool Search Tool 允许 Claude 在数千个工具中动态检索，而非全量加载到上下文。这使"万级工具"成为技术上可行的方案。

实际影响：企业内部工具平台（内部 API 目录、数据湖工具集）将可接入 Claude，而无需担心 token 上限——这对大型企业的 AI 转型具有战略意义。

---

11. 面试高频题

【基础理解层】（考察概念掌握）

Q：什么是 Tool use？为什么 LLM 需要它？
A：Tool use 是让 Claude 能够调用外部函数/服务的机制。LLM 的训练数据是静态的，
   无法获取实时信息（天气、股价）、操作外部系统（发邮件、写数据库）。Tool use
   通过"模型声明需求，外部执行，结果反馈"的循环突破这一限制。
考察意图：验证对 LLM 能力边界的理解，以及 Tool use 的本质价值。

Q：tool_use 和 tool_result 分别是什么？在对话历史中如何组织？
A：tool_use block 是 Claude（assistant role）在响应中声明"我要调用某工具，参数是XXX"；
   tool_result block 是开发者将执行结果以 user role 返回给 Claude。
   对话历史中必须保持 tool_use → tool_result 的完整配对，不能只保留结果。
考察意图：考察对消息格式和对话状态管理的理解。

Q：stop_reason 有哪几种？各代表什么？
A：end_turn（模型完成）、tool_use（需要工具）、max_tokens（token 超限）、
   stop_sequence（遇到停止序列）。tool_use 时开发者需要执行工具并继续循环。
考察意图：验证是否理解 agentic loop 的控制流。

---

【原理深挖层】（考察内部机制理解）

Q：为什么工具描述（description）对准确性至关重要？如何写出高质量描述？
A：Claude 通过 description 判断"什么时候调用这个工具、传什么参数"。
   描述不清晰 = 工具选择错误或参数错误。高质量描述应包含：
   1. 工具的确切功能（做什么）；
   2. 返回值的格式和字段（返回什么）；
   3. 边界条件（什么情况下不适用）；
   4. 参数的取值范围和单位。
考察意图：考察对 prompt engineering 在工具场景的应用理解。

Q：并行工具调用有什么优缺点？如何处理工具间的数据依赖？
A：优点：减少 API 往返次数，提升效率（N 个独立工具从串行 N 轮变为 1 轮）。
   缺点：Claude 无法自动识别依赖关系；若工具 B 依赖工具 A 的结果，Claude 可能错误并行。
   处理方式：在 description 中明确说明"必须在 get_user_id 返回结果后才能调用此工具"。
考察意图：考察对多工具场景下的控制流设计能力。

Q：什么是 Programmatic Tool Calling？相比传统 tool_use 有什么优势？
A：让 Claude 通过生成 Python 代码（在 code_execution 沙箱中运行）批量调用工具，
   而非传统的"一次调用一个工具"模式。优势：
   1. 支持循环/条件判断等复杂控制流；
   2. 中间结果不积累在上下文中，节省 token；
   3. 可处理传统方案因 token 爆炸无法处理的大数据量场景。
考察意图：考察对前沿 agentic 架构的了解。

---

【生产实战层】（考察工程经验）

Q：在生产中，如何防止 Agentic Loop 无限循环？
A：1. 设置 max_rounds 硬上限（推荐 20）；
   2. 工具层对错误给出明确原因和停止建议；
   3. 监控每个 session 的 API 调用次数，超阈值告警；
   4. 区分"工具失败"和"任务无法完成"，后者直接终止并反馈原因。
考察意图：考察对生产稳定性和成本控制的工程经验。

Q：context 窗口快满时应该怎么处理？
A：1. 事前：控制工具返回结果大小（分页，每次 ≤ 2000 token）；
      启用 Prompt Caching 复用工具定义；
   2. 实时：监控 usage.input_tokens / max_tokens 比率，超过 75% 触发压缩；
   3. Claude Code：使用 /compact 命令或自动 Compaction；
   4. 实现滑动窗口：只保留 system prompt + 最近 N 轮 + 关键工具结果。
考察意图：考察大规模 agentic 应用的上下文管理经验。

Q：如何评估工具调用的质量？用什么指标？
A：关键指标：工具选择准确率（正确工具/总调用）、参数正确率、首次调用成功率、
   平均 loop 轮次（反映任务效率）、token 效率（有效输出 token / 总消耗 token）。
   评估方法：构建 golden dataset，对比模型工具调用与预期答案的差异；
   生产中监控 tool_result.is_error 比率和 stop_reason=max_tokens 比率。
考察意图：考察 AI 产品工程化评估能力。

---

12. 文档元信息

验证声明

本文档内容经过以下验证：
✅ 与官方文档一致性核查：
   - Tool use 概述：https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
   - Claude Code 概述：https://code.claude.com/docs/en/overview
   - Advanced Tool Use：https://www.anthropic.com/engineering/advanced-tool-use
   - 模型列表：https://platform.claude.com/docs/en/about-claude/models/overview

⚠️ 以下内容未经本地环境验证，仅基于文档推断：
   - 第 8.3 节：Computer Use 在复杂 GUI 场景下的稳定性描述（标注了存疑）
   - 第 9.1 节：Programmatic Tool Calling 的 token 节省比例（来自 Anthropic 工程博客，
     未在本地复现）
   - MCP 生态数据（300+ 集成、800万次下载）来自第三方资料，可能已更新

知识边界声明

本文档适用范围：
  - Claude API：claude-sonnet-4-6 / claude-opus-4-6 / claude-haiku-4-5
  - Claude Code CLI：v2.0+（基于 GitHub CHANGELOG 推断）
  - anthropic Python SDK：≥ 0.40；Node.js SDK：≥ 0.30
  - 运行环境：Linux / macOS / Windows（Git for Windows）

不适用场景：
  - Claude 2.x 及更早版本（tool_use 协议不同）
  - Anthropic 企业专属功能（如特定部署的安全策略）
  - Amazon Bedrock / Vertex AI 上的 Claude（部分功能可能有差异）

参考资料

官方文档（最高优先级）：
  - Tool use 概述：https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
  - How to implement tool use：https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use
  - Claude Code 官网：https://code.claude.com
  - Structured Outputs：https://platform.claude.com/docs/en/build-with-claude/structured-outputs
  - MCP Connector：https://platform.claude.com/docs/en/agents-and-tools/mcp-connector
  - Models Overview：https://platform.claude.com/docs/en/about-claude/models/overview

工程博客：
  - Advanced Tool Use（Programmatic Tool Calling）：
    https://www.anthropic.com/engineering/advanced-tool-use

源码与社区：
  - Claude Code GitHub（含 CHANGELOG）：https://github.com/anthropics/claude-code
  - MCP 官方文档：https://modelcontextprotocol.io

延伸阅读：
  - SWE-bench（软件工程 Agent 基准）：https://www.swebench.com
  - LAB-Bench（多模态 Agent 基准）：https://lab-bench.org
  - Claude Code CLI 深度实践指南：https://introl.com/blog/claude-code-cli-comprehensive-guide-2025

---