Tool use with Claude｜閱讀重點

已閱讀檔案

：tool use 解決 Claude 無法存取即時資料與外部系統的限制；建立「Claude 請求工具 → 應用程式執行 → 回傳結果 → Claude 最終回答」流程。
：提醒系統專案概觀；用三個工具補足時間精度、日期計算與設定提醒能力。
：tool function 是實際執行外部能力的 Python function；重點是清楚命名、input validation、meaningful error messages。
：用 JSON Schema 告訴 Claude 工具的 name、description、input_schema；可用 ToolParam 增加型別安全。
：啟用 tools 後，Claude response 不再只有 text，可能包含 text block 與 tool_use block；history 必須保存完整 response.content。
：執行工具後，以 user message 送回 tool_result block；tool_use_id 必須對應原本 ToolUse block 的 id。
：多工具任務可能需要多輪工具呼叫；需把 chat function 改成回傳 full message，並建立 conversation loop。
：以 response.stop_reason == "tool_use" 判斷是否繼續執行工具；run_tools() 過濾多個 tool_use blocks 並產生對應 tool_result blocks。
：把多個 schema 放進 tools=[...]，並在 run_tool() router 中依 tool name dispatch 到正確 function。
：tool use + streaming 時會出現 InputJsonEvent / input_json；fine-grained tool calling 可降低 buffering，但會關掉 API 端 JSON validation。
：Claude 內建 text editor tool schema，但仍要由你的應用程式實作檔案操作；schema type 依模型版本不同。
：Claude 內建 web search tool；必須在 console 啟用，schema 包含 type: "web_search_20250305"、name: "web_search"、max_uses，可加 allowed_domains。

模組整體定位

這個 D 模組是「把 Claude 從文字生成模型變成可操作系統的 agent-like assistant」的核心單元。A 模組教的是如何呼叫 API 與管理 messages；D 模組進一步要求你理解：

Claude 不直接執行外部動作：Claude 只會產生 tool_use request；真正呼叫 API、查資料庫、寫檔案、設定提醒的是你的 application / server。
工具能力要雙層定義：
- tool function：實際 Python function，例如 get_current_datetime()、add_duration_to_datetime()、set_reminder()。
- tool schema：給 Claude 看的 JSON Schema，描述工具何時用、要哪些參數、參數型別是什麼。
response content 變成多區塊結構：啟用 tools 後，message.content 可能同時有 text、tool_use、tool_result、web search result / citation 等 blocks；不能再假設 message.content[0].text 永遠成立。
多輪工具迴圈是必要架構：遇到 stop_reason == "tool_use" 時，應用程式要執行工具、送回 tool_result，再呼叫 Claude；直到 Claude 不再要求工具才結束。
內建工具不等於全部免實作：web search 是 Claude 代為搜尋；text editor tool 的 schema 由 Claude 內建，但 file operation implementation 仍要由你提供。

關鍵閱讀重點

1. Tool use 解決什麼問題？

來源：

Claude 預設只能根據訓練資料回答，不能自動取得：
current events
real-time data
private database / internal API
外部系統狀態
需要副作用的操作，例如設定提醒、寫檔、查訂單
Tool use 的標準 back-and-forth flow：
1. Initial Request：你把 user question 與可用工具 schema 一起送給 Claude。
2. Tool Request：Claude 判斷需要外部資料，回傳 tool_use content block，指定 tool name 與 input。
3. Data Retrieval / Action Execution：你的 server 執行實際 function 或外部 API。
4. Tool Result：你的 server 把執行結果包成 tool_result content block 送回 Claude。
5. Final Response：Claude 根據原始問題與工具結果產生自然語言回答。
核心觀念：Claude asks; your code acts; Claude explains.

2. Reminder 專案：用工具補 Claude 的能力缺口

來源：、

專案目標：讓使用者說「Set a reminder for my doctor's appointment. It's a week from Thursday」，Claude 能算出正確時間並設定提醒。
課程列出三個需要工具補足的能力缺口：
Limited time awareness：Claude 可能知道 current date，但不一定知道 exact time。
Date calculation issues：Claude 對複雜日期加減不一定可靠，尤其是跨很多天的 future date。
No reminder capability：Claude 沒有內建設定提醒的系統能力。
對應三個 tools：
get_current_datetime：取得精確日期時間。
add_duration_to_datetime：可靠執行日期時間加減。
set_reminder：實際在系統中建立 reminder。
實務記法：不要用 prompt 硬凹 Claude 算日期與做副作用；把不可靠或不能做的部分改成工具。

3. Tool functions：實際被執行的是你的 Python function

來源：

Tool function 是一般 Python function，不是 Claude 自己內建的魔法。
範例：

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

Best practices：
Use descriptive names：function name 與 parameter name 要清楚，例如 get_current_datetime(date_format=...)。
Validate inputs：空值、不合法參數要檢查。
Provide meaningful error messages：Claude 會看到 error message，可能根據錯誤再 retry tool call。
考點：Claude 產生 tool input 不代表一定合法；server 端仍然要 validation 與 error handling。

4. Tool schemas：Claude 讀 schema，不讀你的 function body

來源：

Tool schema 是 Claude 判斷「什麼時候使用工具、怎麼填參數」的依據。
完整 tool specification 三個主要欄位：
name：工具名稱，例如 "get_current_datetime"。
description：工具用途、何時使用、回傳什麼。
input_schema：JSON Schema，描述 function arguments。
input_schema 常見 keys：
type: 通常是 "object"
properties: 每個參數的型別與說明
required: 必填參數陣列
default: 可選參數的預設值
範例：

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

命名慣例：function get_current_datetime 對應 schema 變數 get_current_datetime_schema。
型別安全：可從 Anthropic library import ToolParam：

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {...}
})

實務：schema description 不是裝飾文字，它會直接影響 Claude 是否選對工具與填對參數。

5. 啟用 tools 後的 API request

來源：、

啟用工具的方法：在 client.messages.create() 加上 tools 參數。

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema],
)

多工具時把多個 schema 放進同一個 list：

response = chat(messages, tools=[
    get_current_datetime_schema,
    add_duration_to_datetime_schema,
    set_reminder_schema
])

tools 是 schema list，不是 function list；Claude 看到的是 schema，真正 function dispatch 仍由你的程式做。

6. Multi-block messages：不能只處理文字

來源：、、

未使用工具時，常見簡化取文字方式是 message.content[0].text。
啟用 tools 後，Claude 的 assistant message 可能包含多個 blocks：
text block：Claude 對人類說明它準備做什麼。
tool_use block：Claude 給程式的工具呼叫指令。
tool_use block 重要欄位：
id：此 tool call 的唯一 ID。
name：要呼叫的 function name，例如 "get_current_datetime"。
input：參數 dictionary。
type: "tool_use"
Conversation history 必須保留完整 block 結構：

messages.append({
    "role": "assistant",
    "content": response.content
})

不能只把 assistant 的文字抽出來加回 history，否則 Claude 後續看不到自己曾發出的 tool request。

7. 執行工具與送回 `tool_result`

來源：、

取得工具輸入的簡化範例：

response.content[1].input
get_current_datetime(**response.content[1].input)

但實務上不要硬寫 content[1]；應掃描所有 blocks，找 block.type == "tool_use"。
工具執行結果要包成 tool_result block，放在 role 為 user 的 message 裡：

messages.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": response.content[1].id,
        "content": "15:04:22",
        "is_error": False
    }]
})

tool_result block 重要欄位：
type: "tool_result"
tool_use_id: 必須 match 原本 tool_use block 的 id
content: 工具輸出，通常序列化成 string，例如 json.dumps(tool_output)
is_error: 工具是否失敗，成功為 False，失敗為 True
Follow-up request 仍要傳 tools=[...]，即使你期待 Claude 下一步只是 final answer；Claude 需要 schema 理解 conversation history 裡的 tool references。

8. 多輪工具迴圈：用 `stop_reason == "tool_use"` 判斷是否繼續

來源：、

多工具任務可能需要 sequence：
1. user 問「What day is 103 days from today?」
2. Claude 先要求 get_current_datetime
3. server 回傳現在日期
4. Claude 再要求 add_duration_to_datetime
5. server 回傳計算結果
6. Claude 才回答使用者
核心判斷欄位：response.stop_reason
若 response.stop_reason == "tool_use"：Claude 正在要求工具，應執行工具並繼續 loop。
若 response.stop_reason != "tool_use"：Claude 已準備好 final response，可以跳出。

def run_conversation(messages):
    while True:
        response = chat(messages, tools=[get_current_datetime_schema])
        add_assistant_message(messages, response)
        print(text_from_message(response))

        if response.stop_reason != "tool_use":
            break

        tool_results = run_tools(response)
        add_user_message(messages, tool_results)

    return messages

工具執行器要能處理一則 assistant message 裡的多個 tool_use blocks：

def run_tools(message):
    tool_requests = [
        block for block in message.content if block.type == "tool_use"
    ]
    tool_result_blocks = []

    for tool_request in tool_requests:
        ...

9. Error handling：工具失敗也要回 `tool_result`

來源：、

工具失敗時，不應讓整個對話 silent fail；應把錯誤包成 tool_result 給 Claude。

try:
    tool_output = run_tool(tool_request.name, tool_request.input)
    tool_result_block = {
        "type": "tool_result",
        "tool_use_id": tool_request.id,
        "content": json.dumps(tool_output),
        "is_error": False
    }
except Exception as e:
    tool_result_block = {
        "type": "tool_result", 
        "tool_use_id": tool_request.id,
        "content": f"Error: {e}",
        "is_error": True
    }

考點：is_error=True 時 Claude 可以看見錯誤內容，可能改用正確參數再試。
實務：error message 要對 Claude 有診斷價值，例如 "date_format cannot be empty" 比 "bad request" 好。

10. Tool router：多工具架構的 dispatch 層

來源：、

run_tool(tool_name, tool_input) 把 Claude 的 tool name 對應到實際 function。

def run_tool(tool_name, tool_input):
    if tool_name == "get_current_datetime":
        return get_current_datetime(**tool_input)
    elif tool_name == "add_duration_to_datetime":
        return add_duration_to_datetime(**tool_input)
    elif tool_name == "set_reminder":
        return set_reminder(**tool_input)

新增工具的固定 pattern：
1. 建 tool function implementation。
2. 建 tool schema。
3. 把 schema 加進 tools=[...]。
4. 在 run_tool() 加一個 tool name 對應 case。
實務：正式系統可用 dictionary dispatch 取代大量 elif，並加入 allowlist、auth、rate limit、logging。

11. Helper functions 要支援完整 Message / blocks

來源：

原本 A 模組的 add_user_message(messages, text) / add_assistant_message(messages, text) 只適合純文字。
工具使用後，helper 要能接受 string、list of blocks、完整 Message object。

from anthropic.types import Message

def add_user_message(messages, message):
    user_message = {
        "role": "user",
        "content": message.content if isinstance(message, Message) else message
    }
    messages.append(user_message)

Chat function 也要改成回傳 full message，而不是只回傳文字：

def chat(messages, system=None, temperature=1.0, stop_sequences=[], tools=None):
    params = {
        "model": model,
        "max_tokens": 1000,
        "messages": messages,
        "temperature": temperature,
        "stop_sequences": stop_sequences,
    }

    if tools:
        params["tools"] = tools

    if system:
        params["system"] = system

    message = client.messages.create(**params)
    return message

顯示 final answer 時，再額外萃取 text blocks：

def text_from_message(message):
    return "\n".join(
        [block.text for block in message.content if block.type == "text"]
    )

12. Tool use + streaming：`InputJsonEvent` 與 fine-grained tool calling

來源：

使用 streaming 時，一般文字常見事件是 ContentBlockDelta。
Tool arguments streaming 會出現新事件型態：InputJsonEvent，在程式中常看 chunk.type == "input_json"。
InputJsonEvent 兩個重點屬性：
partial_json：這次收到的 JSON chunk。
snapshot：目前累積起來的 JSON。

for chunk in stream:
    if chunk.type == "input_json":
        print(chunk.partial_json)
        current_args = chunk.snapshot

預設 behavior：Anthropic API 會 buffering 並 validation，等完整 top-level key-value pair 產生後才送出。
例如工具 input 有 abstract 與 meta，API 可能等整個 abstract value 完整且通過 schema validation 後才釋出。
因此 streaming 可能呈現「延遲後一大段 burst」。
Fine-grained tool calling：
加快工具參數 streaming。
會停用 API-side JSON validation。
可更快收到 chunks，但應用程式必須自行處理 invalid JSON。

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=True
)

Invalid JSON handling：

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    print("Received invalid JSON, continuing...")

適用時機：需要即時進度、需要提早處理 partial arguments、UX 被 buffering delay 影響，且你有能力處理 JSON parse error。
多數一般應用：預設有 validation 的行為已足夠。

13. Text editor tool：schema 內建，但 implementation 仍歸你

來源：

Text editor tool 讓 Claude 能要求：
View file or directory contents
View specific line ranges
Replace text in a file
Create new files
Insert text at specific lines
Undo recent edits
易混淆：text editor tool 的 schema knowledge 是 built-in，但你仍要提供實際 file operation implementation。
Claude 知道如何「要求」讀檔、改檔。
你的應用程式要負責真的讀寫檔案。
Schema stub 依 model version 不同：

def get_text_edit_schema(model):
    if model.startswith("claude-3-7-sonnet"):
        return {
            "type": "text_editor_20250124",
            "name": "str_replace_editor",
        }
    elif model.startswith("claude-3-5-sonnet"):
        return {
            "type": "text_editor_20241022", 
            "name": "str_replace_editor",
        }

重要提醒：課程原文提到 tool version strings 要查官方文件：https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/text-editor-tool。
實務風險：檔案工具有副作用，必須加 sandbox、path allowlist、diff preview、permission model、undo / audit log。

14. Web search tool：Claude 代管搜尋流程，但要先啟用

來源：

Web search tool 必須先在 Console settings 啟用：https://console.anthropic.com/settings/privacy。
Schema 範例：

web_search_schema = {
    "type": "web_search_20250305",
    "name": "web_search", 
    "max_uses": 5
}

max_uses 限制 Claude 可做幾次 search；一次 search 會回多個 results，但 Claude 可能再做 follow-up searches。
限制搜尋 domain：

web_search_schema = {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
    "allowed_domains": ["nih.gov"]
}

Web search response 可能包含的 block / object types：
Text blocks：Claude 的說明與回答。
ServerToolUseBlock：Claude 實際使用的 search query。
WebSearchToolResultBlock：搜尋工具結果容器。
WebSearchResultBlock：個別搜尋結果，含 title / URL。
Citation blocks：支撐 Claude statement 的引用文字與來源 URL。
適用場景：current events、recent developments、specialized information、fact-checking、研究任務。
實務：醫療、法規、投資等高風險領域建議使用 allowed_domains 限制權威來源。

認證準備

必背核心句

Tool use 不是 Claude 直接執行外部 API；Claude 產生 tool_use request，真正執行的是你的 application / server。
一個 tool 要有兩部分：實際 tool function，以及給 Claude 看的 tool schema。
Tool schema 的三個核心欄位是 name、description、input_schema。
input_schema 是 JSON Schema，常見 keys 包含 type、properties、required、default。
啟用工具是在 API call 中傳 tools=[...]，其中放的是 schema list。
Claude 要用工具時，response 的 stop_reason 會是 "tool_use"。
tool_use block 是 assistant message 裡的 content block；tool_result block 要放在 user message 裡送回。
tool_result.tool_use_id 必須 match 原本 tool_use.id。
使用工具後，conversation history 要保存完整 response.content，不能只保存文字。
同一則 response 可能有多個 tool_use blocks；要逐一執行並回傳對應 results。
工具失敗也要回 tool_result，並設 is_error=True。
Fine-grained tool calling 提高 tool argument streaming 粒度，但會停用 API-side JSON validation。
Text editor tool schema built-in，但檔案操作 implementation 仍要你實作。
Web search tool implementation 由 Claude / Anthropic 處理，但組織必須先啟用，且 schema 要含 type、name、max_uses。

易混淆考點

題型陷阱	正確辨識
Claude tool use 代表 Claude 會自己呼叫外部 API？	錯。Claude 只產生 `tool_use` request；server 執行工具。
`tools` 參數要傳 Python functions？	錯。`tools` 傳 tool schemas，例如 `get_current_datetime_schema`。
Tool schema 只要有 `name` 就夠？	錯。還需要清楚 `description` 與 `input_schema`。
`description` 不重要，只是文件？	錯。Claude 依 description 判斷何時使用工具與如何使用。
啟用 tools 後仍可假設 `message.content[0].text` 是全部回答？	錯。可能有 `text` + `tool_use` 多 blocks。
可以把 assistant response 轉成純文字後存入 history？	錯。要保留完整 `response.content`，否則 tool context 會斷。
tool result 是 assistant message？	錯。`tool_result` block 放在 role 為 `user` 的 message 裡。
`tool_use_id` 可任意填？	錯。必須 match 對應 tool use block 的 `id`。
Claude 要多個工具時一定分多次 response？	不一定。同一則 response 可有多個 `tool_use` blocks。
工具失敗時不用回 Claude，直接拋 exception？	錯。應回 `tool_result` 並設 `is_error=True`，讓 Claude 有機會處理。
Follow-up request 送 tool results 後就不用再傳 `tools`？	錯。仍應包含 tool schema，讓 Claude 理解 history 中的 tool references。
`stop_reason != "tool_use"` 代表要繼續跑工具？	反了。`stop_reason == "tool_use"` 才代表要跑工具。
Fine-grained tool calling 只是一般 streaming 的別名？	錯。它會停用 API-side JSON validation，讓 tool argument chunks 更快送出。
Text editor tool 完全不用實作？	錯。schema built-in，但 file read/write implementation 仍要自己寫。
Web search tool 需要自己寫搜尋 API implementation？	通常不用。Claude handles search process；你提供 schema 並確保 console 已啟用。

參數與函式速記

API 呼叫核心：client.messages.create(...)
啟用工具：tools=[get_current_datetime_schema]
多工具：tools=[get_current_datetime_schema, add_duration_to_datetime_schema, set_reminder_schema]
Tool schema keys：name、description、input_schema
JSON Schema keys：type、properties、required、default
型別安全：from anthropic.types import ToolParam
Assistant tool request content block：type == "tool_use"
Tool request fields：id、name、input、type
Tool result content block：type: "tool_result"
Tool result fields：tool_use_id、content、is_error
判斷是否繼續工具迴圈：response.stop_reason == "tool_use"
保存 assistant message：{"role": "assistant", "content": response.content}
送回 tool result：{"role": "user", "content": [tool_result_block]}
執行工具參數 unpack：get_current_datetime(**tool_request.input)
找 tool requests：[block for block in message.content if block.type == "tool_use"]
text extraction：[block.text for block in message.content if block.type == "text"]
工具輸出序列化：json.dumps(tool_output)
Fine-grained tool calling：fine_grained=True
Tool argument streaming event：InputJsonEvent / chunk.type == "input_json"
Tool argument streaming fields：partial_json、snapshot
JSON parsing error：json.JSONDecodeError
Text editor schema type：text_editor_20250124、text_editor_20241022
Text editor schema name：str_replace_editor
Web search schema type：web_search_20250305
Web search schema name：web_search
Web search usage limit：max_uses
Web search domain allowlist：allowed_domains
Web search blocks：ServerToolUseBlock、WebSearchToolResultBlock、WebSearchResultBlock、Citation blocks

考試／評量焦點

1. Tool use 架構題

可能問法：Claude 如何取得即時天氣、股票價格或公司內部資料？

答案核心：提供 tool schema，Claude 需要資料時回傳 tool_use，server 執行外部 API / database call，再以 tool_result 回傳結果，Claude 產生 final response。
重點不是「prompt Claude 去上網」，而是建立 structured tool loop。

2. Tool function vs tool schema 題

可能問法：tool function 與 tool schema 各自負責什麼？

tool function：真正在 server 端執行能力，例如查時間、算日期、設定提醒。
tool schema：給 Claude 看的 JSON Schema / documentation，包含 name、description、input_schema。
Claude 不會讀 Python function body；Claude 依 schema 產生 tool input。

3. Message block 結構題

可能問法：啟用 tools 後，Claude response content 可能有哪些 block？

至少要記得：text block 與 tool_use block。
回工具結果時：用 tool_result block，放在 user message。
Web search 額外有 ServerToolUseBlock、WebSearchToolResultBlock、WebSearchResultBlock、Citation blocks。

4. Conversation history 題

可能問法：為什麼不能只把 Claude 的文字回答存入 messages？

因為 tool_use block 也是對話狀態的一部分。
後續 tool_result 要靠 tool_use_id 對應原本 tool_use.id。
正確做法是保存完整 response.content。

5. `stop_reason` 題

可能問法：如何知道 Claude 是否正在要求 tool call？

看 response.stop_reason。
response.stop_reason == "tool_use"：執行工具並繼續 loop。
response.stop_reason != "tool_use"：跳出 loop，視為 final answer。

6. Multiple tool calls 題

可能問法：Claude 同一輪要求兩個工具怎麼辦？

掃描所有 block.type == "tool_use" 的 blocks。
每個 tool use 都產生一個對應 tool_result block。
每個 result 的 tool_use_id 必須 match 該 tool request 的 id。

7. Error handling 題

可能問法：工具執行錯誤時，應該如何回報給 Claude？

建立 tool_result block。
content 放錯誤訊息，例如 f"Error: {e}"。
is_error 設為 True。
讓 Claude 有機會修正參數或向使用者解釋。

8. Fine-grained tool calling 題

可能問法：fine-grained tool calling 解決什麼問題？代價是什麼？

解決：預設 tool argument streaming 會等完整 top-level key-value pair 通過 validation 才釋出，可能造成延遲與 burst；fine-grained 可更即時收到 chunks。
代價：API-side JSON validation disabled；應用程式要處理 invalid JSON，例如 json.JSONDecodeError。

9. Built-in tools 題：text editor vs web search

可能問法：text editor tool 與 web search tool 差在哪裡？

Text editor tool：Claude 內建 schema knowledge，但你仍要提供 file operations implementation。
Web search tool：Claude handles search process；你只需啟用設定並提供 schema。
兩者都透過 tools schema 啟用，但責任邊界不同。

KC 的實務應用筆記

做半導體廠務 / 水處理 / IOTech agent 時，tool use 對應的是「查即時點位、查設備狀態、查 alarm、寫入工單、設定提醒」，不要只把資料塞 prompt。
任何有副作用的工具，例如 set_reminder、寫檔、下控制命令，都要加權限檢查、confirm step、audit log、dry-run 或 preview。
tool_result.content 建議回傳機器可讀 JSON string，並讓 Claude 只做解釋與使用者溝通；系統狀態仍以工具回傳為準。
多工具架構建議從一開始就做 run_tool() router / registry，避免每加一個工具就改很多地方。
對內部企業工具，schema description 要寫清楚「何時不要用」與「權限限制」，避免 Claude 過度呼叫工具。
Fine-grained tool calling 適合長表單生成、長 JSON arguments、進度 UI；一般查詢工具先用預設 validation，比較穩。
Web search 在教學與研究 demo 很好用，但正式應用要用 allowed_domains 控來源，例如只查公司內部 knowledge base 或官方文件。
Text editor tool 類能力很強，實作時務必限制 working directory，避免模型讀寫不該碰的路徑。
認證答題時要用精準詞：tool_use 是 assistant content block；tool_result 是 user content block；stop_reason 是判斷是否繼續 loop 的欄位。

複習問題

Claude 預設為什麼無法回答即時天氣？Tool use 如何補足？
Tool use 的完整流程中，Claude、your server、external API 各自做什麼？
get_current_datetime 這類 tool function 為什麼要做 input validation？
Tool schema 的 name、description、input_schema 各自用途是什麼？
input_schema.properties 與 input_schema.required 分別描述什麼？
API request 中的 tools 參數應該放 schema 還是 function？
啟用 tools 後，為什麼不能只用 message.content[0].text？
tool_use block 裡有哪些重要欄位？
tool_result block 必須放在哪個 role 的 message？
tool_result.tool_use_id 為什麼必須 match tool_use.id？
如何用 response.stop_reason 建立 tool conversation loop？
同一則 response 有多個 tool_use blocks 時，應如何處理？
工具執行失敗時，tool_result 的 is_error 應該是什麼？
為什麼 follow-up request 送 tool result 後仍要包含 tools schema？
run_tool(tool_name, tool_input) router 解決什麼問題？
Fine-grained tool calling 與預設 tool streaming 最大差異是什麼？
InputJsonEvent 的 partial_json 與 snapshot 差在哪裡？
Fine-grained tool calling 為什麼需要自己處理 invalid JSON？
Text editor tool 為什麼說 schema 內建但 implementation 不內建？
Web search tool 的 max_uses 與 allowed_domains 各自控制什麼？

考前速背卡

問：Tool use 解決 Claude 的什麼限制？→ 答：不能直接存取即時資料、外部系統與執行動作。
問：Claude 會自己執行工具嗎？→ 答：不會；Claude 只產生 tool_use，server 執行。
問：工具的兩大組成？→ 答：tool function + tool schema。
問：Tool schema 三核心欄位？→ 答：name、description、input_schema。
問：JSON Schema 常見欄位？→ 答：type、properties、required、default。
問：API call 啟用工具用哪個參數？→ 答：tools=[...]。
問：tools 裡放什麼？→ 答：tool schemas，不是 Python functions。
問：Claude 要求工具時 stop_reason 是？→ 答："tool_use"。
問：判斷是否繼續工具迴圈？→ 答：if response.stop_reason != "tool_use": break。
問：Assistant message 的工具請求 block type？→ 答：tool_use。
問：工具結果 block type？→ 答：tool_result。
問：tool_result 放在哪個 role？→ 答：user message。
問：tool_result.tool_use_id 對應什麼？→ 答：原始 tool_use block 的 id。
問：工具成功時 is_error？→ 答：False。
問：工具失敗時 is_error？→ 答：True，content 放錯誤訊息。
問：多個工具請求怎麼找？→ 答：掃描 message.content 中 block.type == "tool_use"。
問：為什麼 history 要存完整 response.content？→ 答：保留 text 與 tool_use blocks，讓後續 tool_result 有上下文。
問：Tool argument streaming event？→ 答：InputJsonEvent / input_json。
問：partial_json 是什麼？→ 答：目前 chunk 的部分 JSON。
問：snapshot 是什麼？→ 答：累積到目前為止的 JSON。
問：Fine-grained tool calling 做什麼？→ 答：停用 API-side JSON validation，讓 chunks 更即時。
問：Fine-grained 最大風險？→ 答：可能收到 invalid JSON，要處理 json.JSONDecodeError。
問：Text editor schema type 範例？→ 答：text_editor_20250124 或 text_editor_20241022。
問：Text editor tool name？→ 答：str_replace_editor。
問：Web search schema type？→ 答：web_search_20250305。
問：Web search tool name？→ 答：web_search。
問：限制 web search 次數用什麼？→ 答：max_uses。
問：限制 web search domain 用什麼？→ 答：allowed_domains。

Claude Certified Architect – Foundations 練習

練習模式

完整練習

弱項補強

錯題重練

課程模組

應試模擬

兩種應試模式

考前衝刺

模擬考

弱項分析

複習筆記