---
site: "zyx.tw"
title: "工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果"
description: "模型選工具，外圍程式執行，請求與結果靠 id 配對。"
url: "https://www.zyx.tw/map/harness/tool-calls"
---

# 工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果

紀錄 045，深讀 L2，912 字，2 分鐘，v2.0.0，更新 2026-11-16

工具對模型來說，是名稱、說明與參數格式的約定。模型外圍負責迴圈與工具執行的程式，稱為 harness。模型依說明選工具，harness 依名稱執行，請求與結果用相同的 id 配對。

## 先把工具定義送給模型

在 Agent Loop 的每次模型請求中，工具定義都會一起送出。模型讀得到的介面是名稱、說明與參數格式，因此說明必須讓模型判斷何時該選這個工具。

參數格式用 JSON Schema 描述，也就是規定輸入格式的描述方式。模型選定工具後，輸出工具請求，內容包含 id、工具名稱與參數；此時還沒有執行工具。

不同 API 使用不同的訊息名稱。Anthropic 使用 tool\_use 與 tool\_result，OpenAI 使用 function\_call 與 function\_call\_output，Gemini 使用 functionCall 與 functionResponse。

## 從請求走到函式，再送回結果

harness 收到請求後，先依參數格式檢查 input。工具表則把每個名稱對應到說明、參數格式與執行函式，供 run\_tool 查找。

以圖中的讀檔流程為例，harness 呼叫 read\_file(path)，工具回傳檔案文字。harness 再把文字包成工具結果，附上原請求的 id，送回模型。

```text
  MODEL                 HARNESS                 TOOL
    │                      │                      │
    │  id, name, input     │                      │
    │ ───────────────────> │                      │
    │                      │  read_file(path)     │
    │                      │ ───────────────────> │
    │                      │  file text           │
    │                      │ <─────────────────── │
    │  same id, result     │                      │
    │ <─────────────────── │                      │
```

Figure: A sequence: the model sends a tool request with an id, a name and an input. The harness calls the tool, then answers the model with a result that carries the same id.

1. Request: 模型輸出工具請求：一個 id、工具名稱與參數。
2. Run: harness 依名稱找到函式並執行。
3. Result: harness 回覆工具結果，用相同的 id 指回原本的請求。

## 唯讀請求可以同時執行，改動請求依序執行

一則模型回覆可以帶多份工具請求。安排執行順序時，唯讀呼叫可以同時執行，會改動資料的呼叫則依序執行。

## 工具說明與功能區分決定模型能否選對

替常用指令寫工具定義時，先寫名稱、說明與參數格式，再只讀名稱與說明，判斷用途是否清楚。

工具集合也會影響選擇。讀檔、寫檔、改檔與執行指令就能組成 coding agent；功能重疊的工具會讓模型難以選擇。

## 失敗也要送回對應的結果

每份工具請求都必須有結果，包含執行失敗的請求。少了一份結果，多數 API 會拒絕下一個請求。

分派函式用 TOOLS.get(call.name) 查工具表，查不到就回傳帶同一個 id 的錯誤結果：result(call.id, "unknown tool", error=True)。

若函式執行時拋出例外，示意程式會把 str(e) 放入錯誤結果。不過，錯誤文字還需要寫明原因與下一步，模型讀到後才有依據自行修正。

下圖示範工具表與 run\_tool 如何分派請求，並處理成功、名稱不存在與執行例外的結果。

```text
TOOLS = {
  "read_file": {
    "description": "Read a file. Returns its text.",
    "schema": {"path": "string"},
    "run": read_file,
  },
}

def run_tool(call):
    tool = TOOLS.get(call.name)
    if tool is None:
        return result(call.id, "unknown tool", error=True)
    try:
        output = tool["run"](**call.input)
        return result(call.id, truncate(output))
    except Exception as e:
        return result(call.id, str(e), error=True)
```

Figure: Pseudo code of a tool table and a dispatcher that looks a tool up by name, runs it and returns a result with the call's id.

1. Define: 說明與參數格式送給模型。函式留在 harness，模型看不到。
2. Dispatch: harness 依名稱找到函式，帶入模型給的參數。
3. Id: 每個結果都帶回請求的 id。
4. Error: 錯誤也回傳給模型，迴圈不會中斷。
5. Truncate: 過長的輸出先截短，或存成檔案後只回傳路徑。

## 結果內容不能變成使用者要求

工具成功執行，不代表回傳內容可信。網頁與檔案可能夾帶指令，這些文字只能放在工具結果中，不能當成使用者的要求。

一次請求送給模型的全部內容稱為 context。工具結果與使用者要求在 context 裡都是文字，所以結果裡的指令可能被模型照做；把指令藏進模型會讀到的內容，就是 prompt injection。

## 來源

- [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls), Claude API docs
- [Parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use), Claude API docs
- [Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents), Anthropic
- [What I learned building an opinionated and minimal coding agent](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/), Mario Zechner
- [Agentic Coding Recommendations](https://lucumr.pocoo.org/2025/6/12/agentic-coding/), Armin Ronacher
- [Function calling](https://developers.openai.com/api/docs/guides/function-calling), OpenAI API docs
- [Function calling](https://ai.google.dev/gemini-api/docs/function-calling), Gemini API docs

## 地圖

- 先讀：[Agent Loop 讓模型提出請求，由程式執行並送回結果](https://www.zyx.tw/map/harness/agent-loop.md)
- 先讀：[MCP 把服務操作包成 agent 能呼叫的工具](https://www.zyx.tw/map/basics/mcp-wraps-a-service.md)
- 原理：[MCP 用 JSON-RPC 傳訊息：先取得工具定義，再轉送模型選定的操作](https://www.zyx.tw/map/harness/mcp-on-the-wire.md)
- 原理：[權限規則先拒絕、再詢問、最後放行，沒有命中才交給模式](https://www.zyx.tw/map/harness/permission-gates.md)
- 原理：[工具讀回的內容可能被當成指令，防護要限制讀取與傳送的組合](https://www.zyx.tw/map/harness/untrusted-input.md)
- 原理：[先做最小的 harness，遇到問題再加零件](https://www.zyx.tw/map/harness/build-a-small-harness.md)
- 相關：[每輪重送 context，固定前段與對話長度要分開管理](https://www.zyx.tw/map/harness/context-is-resent.md)
- 回到：[Harness](https://www.zyx.tw/map.md)
