設計模型能夠使用的工具

閱讀約需 91 分鐘 分鐘,10 節 中共有 7 個範例。

版次 2026.11.14 範例於 2026年11 月 19 通過測試 70 個範例中有 70 個通過 變更內容

由 AI 翻譯。經人工以英文驗證。 我們如何製作書籍

譯自英文書,版次 2026.11.14。 閱讀原文

讀完本章後,你將能把商店的 API 轉換成 Model Context Protocol 工具,使其名稱、描述、輸入結構描述、結果與錯誤都能讓模型據以行動,並且能量測更動某個描述後,模型所選擇的工具會有何改變。以下內容適用於規格的 2026-07-28 版本,以及 Python SDK 的 mcp 2.3.0。

本章的每個工具,都是為了協助模型回答商店的某一類客戶工單而存在。商店的伺服器 shop-support 目前只有一個工具:get_order_status,出自〈包裝單一端點成為工具〉。〈MCP 為 API 增添了什麼〉也為它加上了一項資源與一個提示,但光靠一個工具,無法回答大多數的工單。客戶也會詢問某筆訂單是哪一筆、退款會是多少金額、要求退款,以及某項商品是否有庫存。

Model Context Protocol(MCP)伺服器的工具,是模型能看到的商店的唯一部分。模型從不讀取商店的程式碼或其 API。它讀取每個工具的名稱、描述與輸入結構描述,挑選其一,並填入引數,接著讀取回傳的內容,包括任何錯誤。因此,工具是為一位無法提問的讀者所設計的介面,定義中的每個部分,都可能幫助這位讀者,也可能誤導它。

本章將為這些工單建立完整的工具集,並測試每一項設計選擇。

此部分尚未翻譯,因此以英文呈現。

Shape tools around tasks, not endpoints

最近一次變動於第 2026.11.14 版

The shop's API has five endpoints for orders, stock and new refunds, and the quickest way to give a model all five is one tool per endpoint. Generators that turn an API's routes into MCP tools do exactly that. Tools shaped like the API suit a programmer who already knows the workflow. A model has to rebuild the workflow from the tools' names every time: look this up, then compute that, then post it.

The alternative is to shape each tool around a task the model performs for the person it's helping. A task tool may call one endpoint, combine two, or split one in two, and it hides the steps a model would get wrong. Tools are model-controlled: the model decides which to call and with what (server features). The shape of the tools decides which decisions are left to the model.

This chapter rebuilds shop-support in lib.shop_tools, a shared module, so that every example and every later chapter uses the same five tools. The book still calls it the shop's server. Its resource and prompt return in Serve data as resources and prompts. Each of its tools serves one kind of ticket:

  • find_orders searches one customer's orders by status or by the date placed. It calls the API's order list and adds a date filter the API doesn't have.
  • get_order_status looks up one order by its ID, as in chapter 1.
  • quote_refund works out what a refund would be, and changes nothing.
  • issue_refund makes the refund from a quote. Above the policy's limit the shop's API holds it for a person (Return an input request instead of a result); within the limit, nothing in this chapter asks anyone. Consent is the host asking the user before a call that changes something, and it arrives in Ask for consent before side effects.
  • check_stock reports one product's stock in each warehouse.

The module also holds endpoint_tools(), the list a one-tool-per-endpoint generator writes for the same API, so the two shapes can be compared. Both lists print with each tool's required arguments. Then ticket T-0024, "please refund the aluminium muffin tray on o2415", runs both ways.

tools-from-endpoints.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""Two tool lists for the same API, one tool per endpoint as a generator writes them and the shop's five task tools, thenticket T-0024's refund both ways. The point rests on two printed lines: the endpoint tool records the amount the modelsent, and quote_refund's amount is the server's own figure, which the code asserts is within the limit."""import asyncioimport httpx2from mcp import Clientfrom lib import loopback, shop_api, shop_toolsasync def main() -> None:    for tool in shop_tools.endpoint_tools():        print("endpoint tool:", tool.name, tool.input_schema["required"])    with loopback.serve(shop_api.create_app()) as base_url:        async with Client(shop_tools.server_params(base_url)) as client:            print("protocol revision:", client.protocol_version)            for tool in (await client.list_tools()).tools:                print("task tool:", tool.name, tool.input_schema.get("required", []))  # .get: no "required" key if none            # T-0024: "please refund the aluminium muffin tray on o2415". The endpoint tool post_refunds forwards            # its arguments to POST /refunds, so the amount is whatever the model sends, such as the order's total.            order = httpx2.get(f"{base_url}/orders/O-2415", headers={"X-API-Key": shop_api.DEMO_API_KEY}).json()            refund = httpx2.post(f"{base_url}/refunds", headers={"X-API-Key": shop_api.DEMO_API_KEY},                                 json={"order_id": "O-2415", "amount": order["total"], "reason": "damaged"})            print("post_refunds status:", refund.status_code)            print("post_refunds amount:", refund.json()["amount"])            quote = await client.call_tool("quote_refund", {"order_id": "O-2415", "sku": "KG-1050",                                                            "reason": "arrived damaged"})            print("quote_refund amount:", quote.structured_content["amount"])            print("quote_refund within limit:", quote.structured_content["within_limit"])            assert quote.structured_content["within_limit"]  # the muffin tray's line is under the refund policy's limitasyncio.run(main())
輸出python tools-from-endpoints.py
endpoint tool: get_orders []
endpoint tool: get_orders_by_order_id ['order_id']
endpoint tool: get_stock_by_sku ['sku']
endpoint tool: post_refunds ['order_id', 'amount']
endpoint tool: post_stock_by_sku_recount ['sku']
protocol revision: 2026-07-28
task tool: find_orders ['customer_id']
task tool: get_order_status ['order_id']
task tool: quote_refund ['order_id']
task tool: issue_refund ['quote_id']
task tool: check_stock ['sku']
post_refunds status: 201
post_refunds amount: 49.96
quote_refund amount: 23.98
quote_refund within limit: True

The endpoint tools mirror the API. get_orders requires no argument at all, so a model can list every customer's orders. post_refunds requires an order_id and an amount. And post_stock_by_sku_recount puts a slow warehouse job in front of a support model. When a model sends the whole order's total to post_refunds, the API accepts it with status 201 and records a refund of €49.96, for a ticket about one product. The API checks only that the amount isn't more than the order's total, so the model's arithmetic is the only check on the money.

The task tools move those decisions into the server. find_orders requires a customer_id, so a search covers one customer, though the model still picks which one. quote_refund takes the order and, optionally, one SKU, and the server works out the amount itself: €23.98 for the muffin tray's line. That amount is within the refund policy's limit, as the quote's within_limit field says. issue_refund takes no amount at all, only the quote's ID. The stock recount stays off this server; Stream progress on a long call puts it on a server of its own.

Splitting the refund in two also follows most of the specification's guidance for state across calls. The pinned revision has no protocol session, so a tool that needs state from an earlier call gets it as an explicit handle: one tool returns an ID, and the next takes it as an argument. The guidance asks that the creating tool's description state how long the handle lives, and that a call with an expired or unknown handle return a tool execution error that says so (tools, "Stateful tools"). In the shop's server, quote_refund returns a quote_id valid for 15 minutes, and its description says so.

What the server doesn't do yet matters as much. It trusts the customer_id and order IDs the caller sends, so a model, or a ticket written to mislead one, can list any customer's orders and quote any order. Whoever holds a quote_id can spend it. The guidance asks for a handle "with sufficient entropy (e.g., a UUIDv4)" on a server without authentication, and, on one with it, a check of the caller's authorization against the handle "on every call" (tools, "Stateful tools"). The shop's quote IDs come from Python's secrets module, so no one can work one out from the order, but they're only 40 bits and bound to no customer. Secure tools against misuse takes the acting user from the verified token's subject, never from an argument. Where customers sign in, that is the customer. At the support team's host it is a member of staff, and the customer comes from the ticket record the server looks up and checks (Keep the server from acting as a confused deputy).

Working rule: Start from the tasks in your tickets or logs, not from your routes, and give each task one tool. Move every decision the model shouldn't make into the server, such as an amount or a sequence of calls. Use a handle when one task needs the result of another, state its lifetime in the description of the tool that creates it, make it unguessable, and check on every call that it belongs to the caller. Expose an endpoint as it stands only when the task and the endpoint are the same, as check_stock and GET /stock/{sku} are.

撰寫模型會讀的描述

最近一次變動於第 2026.11.11 版

上一節的任務工具,只有在模型選對工具時才有用,而模型是根據主機呈現給它的內容來選擇。本書的主機迴圈 lib.host 會向模型顯示每個工具的名稱、描述與輸入結構描述。規格將描述稱為一種「提示」,用戶端可以用它來「改善 LLM 對可用工具的理解」(schema,Tool.description)。

已發布的描述多半品質不佳。一項針對 103 個伺服器上 856 個工具的研究發現,97.1% 至少有一項缺陷,56% 沒有清楚說明工具的用途(Hasan 等人,2026)。在一項對照測試中,兩個工具的介面完全相同,只修改其中一個工具的描述,就讓它在兩個受測模型上的使用量超過原版的 10 倍(Faghih 等人,2025)。描述較長並不必然較好。在第一項研究中,完全改寫的描述使任務成功率的中位數提高了 5.85 個百分點,但步驟增加了 67%,且每 6 個案例中就有 1 個變得更差。

有幫助的描述會說明四件事:工具做什麼、何時該用它而不是相鄰的工具、輸入長什麼樣子,以及會回傳什麼。在 Python SDK 中,工具的描述就是其函式的 docstring,除非你在 decorator 中傳入 description=(tools)。在本書所用的執行環境 Python 3.12.15 上,SDK 會原樣傳遞 docstring(mcp/server/mcpserver/tools/base.py),因此跨多行的 docstring 會把換行與縮排一併送給模型。商店的伺服器把所有描述放在一個字典 DESCRIPTIONS 中,並將每一則以 description= 的方式傳入。

這個範例會把八張工單與商店的五個工具交給模型三次,每次使用不同的一組描述,只有描述不同。

  • vague 組每個工具只有一行,是端點產生器會寫出的那種,例如「Refund quote.」。
  • draft 組是商店的初稿,以 docstring 寫成。
  • revised 組是商店的第二版,在讀過初稿的結果後寫成。

這八張是從商店的工單佇列中以人工挑選,並非抽樣:兩張詢問客戶有哪些訂單,兩張詢問訂單在哪裡,三張與退款有關,一張與庫存有關。沒有一張帶有被注入的指示,也沒有打錯的訂單編號。在執行之前,請先預測 vague 組與 draft 組各有多少張工單的第一次呼叫是正確的。

所用的模型就是本書每一份錄製都使用的那一個:Qwen3-4B-Instruct-2507,以 llama.cpp 在 CPU 上執行,設定方式如讓模型選擇工具所述。腳本 recordings/description_choices.py 產生了這份錄製 description-choices,每張工單取樣一則回覆,溫度設為 0.7,並使用一個固定的種子。評分只看模型呼叫的第一個工具,不看其引數。一張工單正確的第一個工具,是商店資料為它標註的那一個,但有一項變動:issue_refund 需要 quote_id,所以退款請求要先從 quote_refund 開始。

vague-description-wrong-tool.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""Predict, then run: eight of the shop's tickets and the same five tools, shown to the model with three sets ofdescriptions: one-line ones, the shop's first draft, and its revision. Only the descriptions differ. The model'sreplies are a recording (examples/data/recorded/description-choices/), made with recordings/description_choices.py."""import asyncioimport jsonfrom mcp import Clientfrom lib import shop_toolsfrom lib.host import ReplayModel, choose_toolfrom lib.shop_data import load_shopTICKETS = ("T-0002", "T-0013", "T-0004", "T-0022", "T-0006", "T-0029", "T-0024", "T-0016")SETS = {"vague": shop_tools.VAGUE_DESCRIPTIONS, "draft": shop_tools.DRAFT_DESCRIPTIONS,        "revised": shop_tools.DESCRIPTIONS}model = ReplayModel("description-choices")  # the recorded replies, so no model runs heredef right_tool(ticket) -> str:    """The tool a correct host calls first. issue_refund takes a quote_id, so a refund starts with quote_refund."""    return "quote_refund" if ticket.expected_tool == "issue_refund" else ticket.expected_toolasync def main() -> None:    shop = load_shop()    async with Client(shop_tools.create_server()) as client:     # in-process: listing tools calls no API        listed = (await client.list_tools()).tools    right = dict.fromkeys(SETS, 0)    for ticket_id in TICKETS:        ticket = shop.ticket(ticket_id)        # the same tools each time, with only their descriptions swapped        choices = {label: choose_tool(model, ticket, shop_tools.with_descriptions(listed, descriptions))                   for label, descriptions in SETS.items()}        for label, choice in choices.items():            right[label] += choice.tool == right_tool(ticket)        if all(choice.tool == right_tool(ticket) for choice in choices.values()):            print(f"{ticket_id} all three:", right_tool(ticket))            continue        print(f"{ticket_id} needs:", right_tool(ticket))        for label, choice in choices.items():            print(f"{ticket_id} {label}:", choice.tool or "none")        if choices["revised"].tool == "quote_refund":            print(f"{ticket_id} revised sku:", choices["revised"].arguments.get("sku"))            print(f"{ticket_id} order's skus:", ", ".join(line.sku for line in shop.order(ticket.order_id).lines))    print("sampling temperature:", json.loads((model.folder / "manifest.json").read_text())["sampling"]["temperature"])    for label, count in right.items():        print(f"{label} right:", f"{count} of {len(TICKETS)}")asyncio.run(main())
輸出python vague-description-wrong-tool.py
T-0002 all three: find_orders
T-0013 all three: find_orders
T-0004 all three: get_order_status
T-0022 all three: get_order_status
T-0006 needs: quote_refund
T-0006 vague: get_order_status
T-0006 draft: get_order_status
T-0006 revised: quote_refund
T-0006 revised sku: KG-1031
T-0006 order's skus: KG-1043
T-0029 needs: quote_refund
T-0029 vague: find_orders
T-0029 draft: get_order_status
T-0029 revised: quote_refund
T-0029 revised sku: KG-1022
T-0029 order's skus: KG-1019
T-0024 needs: quote_refund
T-0024 vague: get_order_status
T-0024 draft: get_order_status
T-0024 revised: quote_refund
T-0024 revised sku: KG-1022
T-0024 order's skus: KG-1050, KG-1051
T-0016 all three: check_stock
sampling temperature: 0.7
vague right: 5 of 8
draft right: 5 of 8
revised right: 8 of 8

vague 組在 5 of 8 張工單上選對了第一個工具,draft 組也一樣,為 5 of 8。光靠名稱與參數,就足以處理四張訂單工單與那張庫存工單,因此三組對這些工單都選了相同的正確工具。draft 較長的措辭對三張退款工單沒有幫助,這幾張的選擇並不相同。工單 T-0006 提到訂單「arrived with the enamelled saute pan cracked. what can you refund me」,vague 組給出 get_order_status,draft 組給出 get_order_status。

draft 說明了 quote_refund 做什麼,卻沒有說明它使查詢訂單變得不必要。修訂版在兩個工具中都說明了這一點。get_order_status 把退款問題導向 quote_refund,而 quote_refund 則要求先呼叫它,因為「it checks the order itself」。不過修訂版改動的不只這些。它重寫了 quote_refund 描述的開頭,而且是以 description= 傳入,而非作為 docstring,因此去掉了初稿的換行與縮排。加上這三項改動,revised 組在 8 of 8 張工單上選對了第一個工具。這次執行並未顯示是哪一項改動起了作用。

修訂版修正了工具的選擇,卻沒有修正引數:三個退款呼叫都無法成功。對於 T-0006,模型送出的 SKU 是 KG-1031,也就是 sku 參數自身描述中的範例,而它送出的三個 SKU 沒有一個在該訂單上。將失敗回報為工具結果說明商店的伺服器如何攔截這類錯誤。T-0013 的日期在三組中都是錯的,下一節會說明原因。

請把這些計數視為一次測量。它們來自一個模型、一個種子,以及八張人工挑選的工單,換一個種子可能會改變部分選擇。修訂版是在讀過同樣八張工單的結果之後寫成的,因此它的分數有所高估。測量選對工具的頻率會在整個工單佇列上測量選擇情形,那才是具決定性的測試。

實用原則: 每則描述用兩到四句話寫成:工具做什麼、何時該用它而不是最容易與它混淆的工具、輸入長什麼樣子,以及回傳什麼。請以 description= 傳入,而不要依賴多行的 docstring,讓模型讀到的正是你寫下的文字。接著,錄下你要上線的模型對真實工單選擇工具的過程,檢視錯誤的選擇,並修改這些選擇所指向的描述。當你需要知道是哪項改動奏效時,每次錄製只改一件事,並在你撰寫改動時沒有用過的工單上檢查結果。

以 JSON Schema 為輸入定型

最近一次變動於第 2026.11.11 版

上一節的描述告訴模型工具需要什麼,而輸入綱要(input schema)則讓伺服器強制執行這些要求。每個工具都有一個 inputSchema,它是一個 JSON Schema 物件,根節點為 "type": "object"。在鎖定的修訂版本中,其中可以出現任何 JSON Schema 2020-12 的關鍵字(變更記錄),包括 oneOf、if、then、else 與 $ref(schema,Tool.inputSchema)。沒有 $schema 欄位的綱要會被視為 2020-12,而且實作「MUST NOT」自動跟隨指向網路 URI 的 $ref(基礎協定),因此在預設情況下,綱要無法讓用戶端下載任何東西。

綱要有兩項工作。它向模型呈現有效呼叫的形狀,也讓伺服器能在執行工具的任何程式碼之前拒絕無效的呼叫。規格將伺服器這一半的工作列為要求:伺服器「MUST」驗證所有工具輸入(tools,「Security considerations」)。

Python SDK 會根據函式的型別提示建立綱要,而 pydantic 的 Annotated[..., Field(...)] 則為這些提示加上限制(tools)。商店的伺服器只定義一次 ID 型別。OrderId 是帶有 pattern=r"^O-\d{4}$" 的字串,CustomerId 與 Sku 的作法相同。find_orders 接受 status,其型別是五種訂單狀態的 Literal;接受 placed_since,其型別是 date;也接受 limit,其型別是帶有 ge=1, le=50 的整數。SDK 根據這些提示建立的綱要會先印出。接著 find_orders 以三種方式被呼叫:一次帶有三個錯誤引數、一次把數字當成字串傳送,以及一次使用已錄製的模型在 撰寫模型會讀的描述 中為工單 T-0013 傳送的日期。該工單要求的是「自 6 月 12 日起」的訂單。

reject-bad-arguments.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""find_orders' typed inputs: the JSON Schema the SDK builds from them, one result that names three rejected arguments,a string the SDK converts without complaint, and a date that is valid but wrong. The point rests on the last two ordercounts: a date that passes validation can still return the wrong orders."""import asyncioimport jsonfrom mcp import Clientfrom lib import loopback, shop_api, shop_toolsasync def main() -> None:    with loopback.serve(shop_api.create_app()) as base_url:        async with Client(shop_tools.server_params(base_url)) as client:            tools = {tool.name: tool for tool in (await client.list_tools()).tools}            for name, prop in tools["find_orders"].input_schema["properties"].items():                rules = {k: v for k, v in prop.items() if k in ("pattern", "minimum", "maximum", "default")}                # an optional argument's schema is anyOf: its type or enum, and null                kinds = [p.get("enum") or p.get("format") or p["type"] for p in prop.get("anyOf", [prop])]                print(f"{name}:", json.dumps(kinds), json.dumps(rules))            bad = await client.call_tool("find_orders", {"customer_id": "42", "status": "lost", "limit": 500})            print("bad arguments is error:", bad.is_error)            assert bad.is_error            print(bad.content[0].text)            # "5" is a string; pydantic converts it to the integer 5 before the tool runs            loose = await client.call_tool("find_orders", {"customer_id": "C-0085", "limit": "5"})            print("string limit is error:", loose.is_error)            assert not loose.is_error            print("string limit orders:", len(loose.structured_content["orders"]))            # T-0013 asks for orders "since 12 Jun"; the recorded model sent 2023-06-12, a valid date            wrong_year = await client.call_tool("find_orders", {"customer_id": "C-0085", "placed_since": "2023-06-12"})            right_year = await client.call_tool("find_orders", {"customer_id": "C-0085", "placed_since": "2026-06-12"})            print("since 2023-06-12 orders:", len(wrong_year.structured_content["orders"]))            print("since 2026-06-12 orders:", len(right_year.structured_content["orders"]))asyncio.run(main())
輸出python reject-bad-arguments.py
customer_id: ["string"] {"pattern": "^C-\\d{4}$"}
status: [["placed", "shipped", "delivered", "cancelled", "returned"], "null"] {"default": null}
placed_since: ["date", "null"] {"default": null}
limit: ["integer"] {"default": 10, "maximum": 50, "minimum": 1}
bad arguments is error: True
Error executing tool find_orders: 3 validation errors for find_ordersArguments
customer_id
  String should match pattern '^C-\d{4}$' [type=string_pattern_mismatch, input_value='42', input_type=str]
    For further information visit https://errors.pydantic.dev/2.14/v/string_pattern_mismatch
status
  Input should be 'placed', 'shipped', 'delivered', 'cancelled' or 'returned' [type=literal_error, input_value='lost', input_type=str]
    For further information visit https://errors.pydantic.dev/2.14/v/literal_error
limit
  Input should be less than or equal to 50 [type=less_than_equal, input_value=500, input_type=int]
    For further information visit https://errors.pydantic.dev/2.14/v/less_than_equal
string limit is error: False
string limit orders: 5
since 2023-06-12 orders: 5
since 2026-06-12 orders: 1

每個提示都變成了一個綱要關鍵字:客戶 ID 對應 pattern,狀態對應 enum,日期對應 "format": "date",數量上限對應 minimum 與 maximum。帶有三個錯誤引數的呼叫以單一失敗結果回傳,其文字列出每個失敗的引數、違反的規則以及傳入的值。模型可以在下一次呼叫中一次修正這三項錯誤。

SDK 在一方面比綱要寬鬆。綱要說 limit 是整數,但傳入 "5" 的呼叫卻成功了,並回傳 5 筆訂單。負責驗證引數的 Pydantic 預設會把數字字串轉換成整數。這在此處無傷大雅。若字串與數字必須保持區別,請以 Field(strict=True) 宣告該欄位。Pydantic 也會不報錯地丟棄綱要未宣告的任何引數(mcp/server/mcpserver/utilities/func_metadata.py),避免伺服器淪為混淆代理人即仰賴這一點。

日期是任何綱要都抓不到的錯誤。工單中的「6 月 12 日」沒有年份,而模型傳送了 2023-06-12,這是一個有效的日期,比商店資料的結束時間早了三年。該呼叫通過了驗證,並回傳 5 筆訂單,也就是該客戶的所有訂單,而不是商店當年自 6 月 12 日起下的 1 筆。綱要檢查的是形式,意義必須來自其他地方,例如由主機把工單的日期放進提示,或由描述說明如何解讀沒有年份的日期。

規格對於被拒絕的引數該放在哪裡並不一致。它的 tools 頁面把輸入驗證列為工具執行錯誤,這類錯誤以結果的形式回傳。它的 schema 參考則把「invalid tool arguments」列在 JSON-RPC 錯誤 -32602 之下(schema,InvalidParamsError)。SDK 依循 tools 頁面,本書亦然。用戶端「SHOULD」把執行錯誤傳給模型,但對協定錯誤只是「MAY」傳遞,規格說這類錯誤「less likely to result in successful recovery」(tools,「Error handling」)。結果是模型能指望讀到的路徑。

實用原則: 在 API 允許的範圍內,盡可能狹窄地指定每個引數的型別:ID 用 pattern,固定值用 enum,數量用上下界,日期用 format。讓 SDK 在你的程式碼執行之前拒絕錯誤的呼叫,並一次回傳所有失敗。不要把意義託付給綱要,因為有效的日期仍可能是錯誤的日期。請在工具內部檢查綱要無法表達的部分,並在描述中說明如何填寫工單常常寫得不完整的值。

此部分尚未翻譯,因此以英文呈現。

Return structured content with an output schema

最近一次變動於第 2026.11.14 版

The inputs from the previous section have a schema, and results can have one too. A tool may declare an outputSchema, and its result then carries structuredContent: the result's data as JSON that a program can read without parsing text (tools, "Structured content"). When a tool declares an output schema, the server "MUST" return results that conform to it, and clients "SHOULD" validate them. A tool that returns structured content "SHOULD" also return it serialized as JSON in a text block, for clients that read only text. The same section notes that structuredContent is the server's result data, unrelated to a model's "structured outputs".

The output schema serves the host's code more than the model. Code can branch on a field called within_limit instead of searching a sentence for "exceeds", and a test can check a field instead of a string. structuredContent may be any JSON value at the pinned revision (changelog). Revision 2025-11-25 required an object (tools at 2025-11-25), which Migrate a 2025-era server covers.

The Python SDK builds the output schema from the function's return type. Primitive types, None, lists and unions are wrapped in {"result": ...}. Pydantic models, TypedDicts, dataclasses and dict[str, ...] aren't (structured output; mcp/server/mcpserver/utilities/func_metadata.py). quote_refund returns RefundQuote, a pydantic model with the quote's ID, the order, the SKU, the amount, the policy limit, within_limit and the quote's lifetime in seconds. Quoting order O-2289 for ticket T-0006 with no SKU, so the quote covers the whole order, shows the structured result. A second server then has one tool that returns the same amount as a bare string, to show the wrapper.

refund-quote-structured.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""quote_refund returns a pydantic model, so the SDK publishes its output schema and returns structuredContent; a toolthat returns a bare string gets a {"result": ...} wrapper instead. The point rests on the bare structured content line,and the quote's within-limit flag and text block, which the code asserts."""import asyncioimport jsonfrom mcp import Clientfrom mcp.server.mcpserver import MCPServerfrom lib import loopback, shop_api, shop_toolsfrom lib.shop_data import load_shop, moneybare = MCPServer("bare-return")@bare.tool()def refund_amount(order_id: str) -> str:    """The refund for a whole order, as a decimal string."""    return money(load_shop().order(order_id).total_cents)async def main() -> None:    with loopback.serve(shop_api.create_app()) as base_url:        async with Client(shop_tools.server_params(base_url)) as client:            tools = {tool.name: tool for tool in (await client.list_tools()).tools}            print("output schema requires:", ", ".join(tools["quote_refund"].output_schema["required"]))            quote = await client.call_tool("quote_refund", {"order_id": "O-2289", "reason": "arrived cracked"})            shown = {**quote.structured_content, "quote_id": "(random)"}      # quote IDs differ on every run            print("structured content:", json.dumps(shown))            print("amount:", quote.structured_content["amount"])            print("within limit:", quote.structured_content["within_limit"])            assert quote.structured_content["within_limit"] is False            # the lifetime is in seconds; the prose gives it in minutes            print("quote lifetime minutes:", quote.structured_content["expires_in_seconds"] // 60)            # the text block a client that reads only text gets, parsed back to JSON            same_json = json.loads(quote.content[0].text) == quote.structured_content            print("text block is the same JSON:", same_json)            assert same_json    async with Client(bare) as client:                  # in-process: no wire needed to read a schema        tool = (await client.list_tools()).tools[0]        print("bare output schema:", json.dumps(tool.output_schema))        result = await client.call_tool("refund_amount", {"order_id": "O-2289"})        print("bare structured content:", json.dumps(result.structured_content))asyncio.run(main())
輸出python refund-quote-structured.py
output schema requires: quote_id, order_id, sku, amount, policy_limit, within_limit, expires_in_seconds
structured content: {"quote_id": "(random)", "order_id": "O-2289", "sku": null, "amount": "180.00", "policy_limit": "150.00", "within_limit": false, "expires_in_seconds": 900}
amount: 180.00
within limit: False
quote lifetime minutes: 15
text block is the same JSON: True
bare output schema: {"properties": {"result": {"title": "Result", "type": "string"}}, "required": ["result"], "title": "refund_amountOutput", "type": "object"}
bare structured content: {"result": "180.00"}

The quote's output schema requires quote_id, order_id, sku, amount, policy_limit, within_limit, expires_in_seconds, and the structured content has each of those fields. Its amount, €180.00, is more than the policy's limit, so within_limit is false, and Return an input request instead of a result is where that flag starts a person's confirmation. The text block holds the same JSON, as the code checks.

The bare tool shows where the SDK lags the specification. The pinned revision allows a string as structured content, but the SDK still wraps any value that isn't an object in {"result": ...}, and publishes an object schema to match (mcp/server/mcpserver/utilities/func_metadata.py). The bare tool's structured content is {"result": "180.00"}, not the bare string. A host written to the specification that expects a string gets an object instead. Return a model from every tool and the question never comes up.

Both sides check structured content. The SDK's client validates every successful result against the output schema it cached from tools/list. It raises a RuntimeError when the structured content doesn't match, or when a tool with an output schema returns none (mcp/client/session.py, validate_tool_result). The SDK's server also checks a tool's return value against the tool's own model before sending it (mcp/server/mcpserver/utilities/func_metadata.py), so a mismatch fails on whichever side changed.

Working rule: Give every tool a pydantic model as its return type, so the SDK publishes an output schema, returns structured content with no wrapper, and adds the text block for you. Put a field in the model for each decision the host's code makes, such as within_limit, rather than leaving it in a sentence. Return a bare string only from a tool whose result no code reads.

將失敗回報為工具結果

最近一次變動於第 2026.11.11 版

上一節的報價單,是呼叫成功時的結果。呼叫失敗時,規格為它提供兩條路徑(tools,「Error handling」)。協定錯誤(protocol error)是 JSON-RPC 錯誤,適用於未知的工具、不符合 tools/call 結構描述的請求,或伺服器故障。工具執行錯誤(tool execution error)則是將 isError 設為 true 的一般結果,適用於 API 失敗、無效的輸入或違反業務規則的情況。本書其餘部分所稱的工具錯誤(tool errors),依規格所述,「包含語言模型可用來自我修正的可行動回饋」,而且用戶端「SHOULD」將它們傳遞給模型。

由於用戶端 SHOULD 將執行錯誤傳遞給模型,而協定錯誤只是 MAY,因此走哪一條路徑,決定了誰能修復這個失敗。在 Python SDK 中,拋出 ToolError 會產生帶有你的訊息的執行錯誤。拋出 MCPError 則會產生協定錯誤。任何其他例外都視為崩潰:結果只會顯示「Error executing tool」與工具名稱,例外本身則留在伺服器的日誌中(handling errors)。SDK 的指南將這項選擇表述為一個問題:更聰明的模型能否避免這個失敗?若能,就拋出 ToolError;若不能,就拋出 MCPError。

商店的伺服器遵循這項判斷。訂單不存在、訂單不可退款、SKU 不在訂單中,以及報價單未知或已過期,全都屬於 ToolError,每一個都附有說明該改做什麼的訊息。商店 API 回傳 401,表示伺服器的金鑰有誤,這是任何模型都無法修正的,因此伺服器以 JSON-RPC 的內部錯誤碼拋出 MCPError。其他情況,例如 API 停止運作,則維持為崩潰。有五個呼叫刻意失敗,依程式碼產生它們的順序列出如下:

  1. 工單 T-0006 所記錄的呼叫,採用撰寫供模型閱讀的描述中修訂後的描述,其中含有一個捏造的 SKU;
  2. 使用伺服器從未發出的報價單呼叫 issue_refund;
  3. 一個不存在的工具;
  4. 對以錯誤金鑰啟動的伺服器發出呼叫;
  5. 在商店 API 停止後發出呼叫。
tool-error-versus-protocol-error.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""Five failures and the path each takes: three tool execution errors the model reads (isError results), a crash themodel sees only as a generic message, and a protocol error (a JSON-RPC error) that only the host sees. The point restson which results are flagged as errors, and the code asserts that a missing tool is one of them."""import asynciofrom mcp import Client, MCPErrorfrom lib import loopback, shop_api, shop_toolsfrom lib.host import ReplayModel, choose_toolfrom lib.shop_data import load_shopasync def attempt(params, name: str, arguments: dict, label: str) -> object | None:    async with Client(params) as client:        try:            result = await client.call_tool(name, arguments)            print(f"{label} is error:", result.is_error)            print(f"{label} says:", result.content[0].text)            return result        except MCPError as error:            print(f"{label} JSON-RPC error code:", error.code)            print(f"{label} JSON-RPC error message:", error.message)            return Noneasync def main() -> None:    with loopback.serve(shop_api.create_app()) as base_url:        params = shop_tools.server_params(base_url)        async with Client(params) as client:          # T-0006's recorded choice, with the SKU the model made up            tools = (await client.list_tools()).tools        choice = choose_tool(ReplayModel("description-choices"), load_shop().ticket("T-0006"), tools)        await attempt(params, choice.tool, choice.arguments, "wrong SKU")        await attempt(params, "issue_refund", {"quote_id": "Q-0000000000"}, "unknown quote")        unknown = await attempt(params, "refund_order", {"order_id": "O-2289"}, "unknown tool")        assert unknown is not None and unknown.is_error  # a failed result, not a protocol error        # a key the shop's API rejects: the server answers with a protocol error, which the client raises        await attempt(shop_tools.server_params(base_url, api_key="wrong-key"), "get_order_status",                      {"order_id": "O-2289"}, "rejected key")    await attempt(params, "get_order_status", {"order_id": "O-2289"}, "API down")    # the API has stoppedasyncio.run(main())
輸出python tool-error-versus-protocol-error.py
wrong SKU is error: True
wrong SKU says: Error executing tool quote_refund: Order O-2289 has no line for KG-1031. Its SKUs are KG-1043.
unknown quote is error: True
unknown quote says: Error executing tool issue_refund: There is no quote Q-0000000000. Call quote_refund for the order to get a quote_id.
unknown tool is error: True
unknown tool says: Unknown tool: refund_order
rejected key JSON-RPC error code: -32603
rejected key JSON-RPC error message: The shop's API rejected this server's key. The server needs reconfiguring.
API down is error: True
API down says: Error executing tool get_order_status

捏造的 SKU 以執行錯誤的形式返回,其文字提供了模型所缺少的資訊:「Error executing tool quote_refund: Order O-2289 has no line for KG-1031. Its SKUs are KG-1043.」讀到這段訊息的模型,可以用正確的 SKU 再次呼叫。未知報價單的訊息作用相同:「Error executing tool issue_refund: There is no quote Q-0000000000. Call quote_refund for the order to get a quote_id.」

未知的工具顯示出與規格有出入的地方。規格的範例以 JSON-RPC 錯誤 -32602 回應未知的工具,但 SDK 的伺服器改為回傳執行錯誤(mcp/server/mcpserver/tools/tool_manager.py)。該結果被標示為錯誤,其文字為「Unknown tool: refund_order」。對模型而言,這是更有用的回答,因為它顯示名稱有誤。若主機以計算協定錯誤的方式來察覺模型是否混淆,就不會看到這些情況,因此也要計算執行錯誤。

錯誤的金鑰走了另一條路徑。用戶端拋出 MCPError,範例將它捕捉為 JSON-RPC 錯誤 -32603,訊息為「The shop's API rejected this server's key. The server needs reconfiguring.」主機的程式碼看得到這項錯誤,而模型只有在主機將它傳遞下去時才看得到。API 停止運作時,模型只得到「Error executing tool get_order_status」,例外則留在伺服器的日誌中(handling errors)。

還有一種錯誤會同時略過兩條路徑:工具將錯誤訊息當作一般字串回傳。SDK 傳送回傳字串時,會讓 isError 為 false,因此模型會把這個錯誤讀成成功的回答(handling errors)。應改為拋出例外。

**實用原則:**對於模型能夠修正的每一種失敗,都拋出 ToolError,訊息中要指出錯在哪裡以及應改送什麼,若有效值不多,則一併列出。只有在沒有任何模型能修復的失敗(例如設定問題)時,才拋出 MCPError,並讓非預期的例外保持通用的訊息,使內部細節留在伺服器上。切勿將錯誤當作純字串回傳。

此部分尚未翻譯,因此以英文呈現。

Mark what a tool changes with annotations

最近一次變動於第 2026.11.14 版

The errors in the previous section tell the model what went wrong after a call. A tool's annotations tell the host what a call will do before it's made, so the host can decide whether to ask for consent first. The specification wants a person able to say no to any tool call, as Let a model choose the tool quoted. A tool's annotations hold a title and four hints (schema, ToolAnnotations):

  • readOnlyHint: the tool doesn't change its environment. The default is false.
  • destructiveHint: a tool that changes something may destroy or overwrite data, rather than only add to it. The default is true.
  • idempotentHint: calling the tool again with the same arguments has no further effect. The default is false.
  • openWorldHint: the tool reaches entities outside a closed domain, such as the web. The default is true.

destructiveHint and idempotentHint mean something only when readOnlyHint is false. The defaults describe the worst case, so to a careful host a tool with no annotations is destructive, not idempotent, and reaches the open world. Annotations go into the Python SDK as ToolAnnotations(read_only_hint=..., destructive_hint=..., idempotent_hint=..., open_world_hint=...) to the tool() decorator (tools).

The shop's four reading tools carry read_only_hint=True and open_world_hint=False, because they only read the shop's own API. issue_refund is the one tool that changes something, and its hints are judgements. We set destructive_hint=False, because a refund adds a record and never overwrites one, and open_world_hint=False, because the tool talks only to the shop's API, which records the request for the shop's staff to pay. idempotent_hint=True is the hint that needs a guarantee behind it: the server returns the same refund for the same quote_id.

The code works out what a host should assume about each tool, filling in the default wherever a hint is missing, and applies a consent rule to the result. It includes the endpoint tool post_refunds, which has no annotations. Then it calls issue_refund twice with one quote, and POST /refunds twice with one amount.

annotate-the-refund-tool.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""What each tool's annotations tell a host, with the specification's defaults filled in where a hint is missing, andwhether the server keeps issue_refund's idempotent promise when the same call arrives twice. The point rests on the tworefund pairs: issue_refund returns one refund both times, while two posts to the endpoint make two."""import asyncioimport httpx2from mcp import Clientfrom lib import loopback, shop_api, shop_tools# the specification's defaults, used for any hint a tool leaves outDEFAULTS = {"read_only_hint": False, "destructive_hint": True, "idempotent_hint": False, "open_world_hint": True}def assumed(annotations) -> dict:    """The hints a host should assume: each one the tool sets, and the specification's default for the rest."""    given = annotations.model_dump(exclude_none=True) if annotations else {}    hints = {hint: given.get(hint, default) for hint, default in DEFAULTS.items()}    if hints["read_only_hint"]:          # destructive and idempotent apply only to a tool that changes something        del hints["destructive_hint"], hints["idempotent_hint"]    return hintsasync def main() -> None:    with loopback.serve(shop_api.create_app()) as base_url:        async with Client(shop_tools.server_params(base_url)) as client:            tools = (await client.list_tools()).tools + shop_tools.endpoint_tools()[3:4]    # + post_refunds            for tool in tools:                hints = assumed(tool.annotations)                shown = ", ".join(h.removesuffix("_hint") for h, on in hints.items() if on) or "nothing"                print(f"{tool.name} assumes:", shown)                print(f"{tool.name} asks consent:", not hints["read_only_hint"])            quote = (await client.call_tool("quote_refund", {"order_id": "O-2415", "sku": "KG-1050"})).structured_content            first = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})            again = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})            print("issue_refund first refund:", first.structured_content["refund_id"])            print("issue_refund second refund:", again.structured_content["refund_id"])        # the amount the quote for KG-1050 gave, posted straight to the endpoint        twice = [httpx2.post(f"{base_url}/refunds", headers={"X-API-Key": shop_api.DEMO_API_KEY},                             json={"order_id": "O-2415", "amount": "23.98"}).json()["refund_id"] for _ in range(2)]        print("post_refunds first refund:", twice[0])        print("post_refunds second refund:", twice[1])asyncio.run(main())
輸出python annotate-the-refund-tool.py
find_orders assumes: read_only
find_orders asks consent: False
get_order_status assumes: read_only
get_order_status asks consent: False
quote_refund assumes: read_only
quote_refund asks consent: False
issue_refund assumes: idempotent
issue_refund asks consent: True
check_stock assumes: read_only
check_stock asks consent: False
post_refunds assumes: destructive, open_world
post_refunds asks consent: True
issue_refund first refund: R-0111
issue_refund second refund: R-0111
post_refunds first refund: R-0112
post_refunds second refund: R-0113

Each of the four reading tools comes out as read_only, and issue_refund as idempotent: it isn't read-only, but it is neither destructive nor open-world. The unannotated post_refunds comes out as destructive, open_world, because that's what the defaults say. A host that asks for consent before any tool that isn't read-only asks before both refund tools and none of the others. The shop's host gets that rule in Ask for consent before side effects.

The two pairs of calls show why idempotent_hint=True is safe to claim for issue_refund and wouldn't be for the endpoint. Two calls of issue_refund with one quote returned R-0111 and R-0111: one refund, twice. Two identical posts to the API created R-0112 and R-0113: two refunds. The shop's API has no once-only check, so the server adds one. It stores the refund against its quote, under a lock, because the SDK runs synchronous tools on worker threads and two calls can arrive together.

將註解視為提示,而非保證

協定本身不會檢查註解是否與工具的實際行為相符。規格指出,註解「不保證能如實描述工具的行為」,而且除非註解來自受信任的伺服器,否則用戶端「MUST」將其視為不可信(schema,ToolAnnotations;tools)。如果伺服器把退款工具標示為唯讀,任何相信這項標示的主機都會被它蒙混過關。Catch poisoned tool descriptions 展示了一個刻意在工具定義中說謊的伺服器。

對伺服器的作者而言,提示是程式碼必須兌現的承諾。商店的 issue_refund 具有冪等性,是因為報價儲存區這樣保證,而不是因為註解這麼寫。如果重新啟動後儲存區的資料遺失,重試的呼叫只會得到「There is no quote」,而不會產生第二次退款,這仍然是安全的。檢查應保留在伺服器中,並把註解視為對這項檢查的描述。

實用原則: 為每個工具加上註解,因為省略提示,等於告訴謹慎的主機要往最壞的情況假設。只有在伺服器確實強制保證冪等性時,才將工具標示為冪等;退款、付款,以及其他只能發生一次的操作,都應由伺服器上的檢查把關。身為主機時,只能使用來自受信任伺服器的註解來決定向使用者顯示什麼內容,絕不可將其當作略過同意程序的許可(Ask for consent before side effects),並把其他所有伺服器的註解都視為未經驗證的聲明。

讓工具清單保持精簡

最近一次變動於第 2026.11.11 版

主機(host)在每一輪對話中,都會把前幾節的每個工具,連同其說明與輸入結構描述(input schema),放進模型的提示中,而模型在選擇之前會讀完整份清單。工具越多,花費的 token 越多,選擇也越困難。在一項針對 MCP 伺服器的測試中,只檢索與請求相關的工具,使選擇準確率提高到三倍以上,從 13.62% 升至 43.13%(Gan and Sun, 2025)。在邊緣裝置上,提供較少的工具給小型模型,提高了它們的函式呼叫成功率,並將執行時間最多縮短 70%(Paramanayakam and others, 2025)。這兩項都是各自設定下的單一研究,因此請把它們視為效果的方向,而不是商店情境的數字。

成本與其憑空猜測,不如直接測量。錄製腳本執行時,也用錄製所用模型的 tokenizer,計算了每個工具在主機提示中佔用多少 token。這項檢查會加總修訂後工具的 token 數、撰寫供模型閱讀的說明中那些含糊的工具,以及端點工具的 token 數,並測量它們的位元組數。如果某個工具在計算 token 之後又有變動,檢查就會拒絕執行。

tool-list-size.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通過
"""What the shop's tool list costs in the host's prompt: bytes, and tokens counted with the recording model's tokenizerwhen the recording was made (examples/data/recorded/description-choices/prompt_tokens.json). The point rests on therevised, vague and endpoint prompt token lines."""import asyncioimport hashlibimport jsonfrom mcp import Clientfrom lib import shop_toolsfrom lib.host import RECORDED, tool_specs# the token counts and line hashes the recording script wrotecounted = json.loads((RECORDED / "description-choices" / "prompt_tokens.json").read_text())def cost(label: str, tools) -> tuple[int, int]:    """Bytes and tokens of the tools as the host's prompt renders them, one JSON line per tool."""    lines = [json.dumps(spec, ensure_ascii=False) for spec in tool_specs(tools)]    # the hash of each line as the host renders it; a tool that changed since then fails here    for spec, line in zip(tool_specs(tools), lines):        if counted[label][spec["name"]]["sha256"] != hashlib.sha256(line.encode()).hexdigest():            raise LookupError(f"{spec['name']} changed since its tokens were counted: re-run the recording script")    tokens = sum(counted[label][spec["name"]]["tokens"] for spec in tool_specs(tools))    return sum(len(line.encode()) for line in lines), tokensasync def main() -> None:    async with Client(shop_tools.create_server()) as client:        result = await client.list_tools()    listed = result.tools    print("tools/list result bytes:", len(result.model_dump_json(by_alias=True, exclude_none=True).encode()))    vague = shop_tools.with_descriptions(listed, shop_tools.VAGUE_DESCRIPTIONS)    for label, tools in (("revised", listed), ("vague", vague), ("endpoint", shop_tools.endpoint_tools())):        size, tokens = cost(label, tools)        print(f"{label} prompt bytes:", size)        print(f"{label} prompt tokens:", tokens)    tokens_per_tool = cost("revised", listed)[1] / len(listed)  # cost returns (bytes, tokens): index 1 is tokens    print("revised tokens per tool:", round(tokens_per_tool))    print("20 such tools tokens:", round(20 * tokens_per_tool))       # arithmetic on the counts, not a count    print("prompt without tools tokens:", counted["prompt_without_tools"])    print("recording context tokens:", counted["context"])asyncio.run(main())
輸出python tool-list-size.py
tools/list result bytes: 8049
revised prompt bytes: 3417
revised prompt tokens: 970
vague prompt bytes: 1945
vague prompt tokens: 620
endpoint prompt bytes: 1014
endpoint prompt tokens: 288
revised tokens per tool: 194
20 such tools tokens: 3880
prompt without tools tokens: 136
recording context tokens: 4096

成本大部分在結構描述上。商店的五個修訂後工具在提示中佔 970 個 token,而主機其餘指示佔 136 個。若使用含糊的說明,它們佔 620 個,因此修訂後的說明約佔清單成本的三分之一。端點工具佔 288 個:說明只有一行,結構描述沒有 pattern、enum,也沒有各自的說明。修訂後的結構描述,就是以 JSON Schema 定義輸入型別中攔截到錯誤引數的那些結構描述。完整的 tools/list 結果更大,因為它還包含輸出結構描述、標題與註解,而這些是主機提示所省略的,輸出的位元組數也顯示了這一點。

以每個工具約 194 個 token 計算,20 個這樣的工具在模型讀到工單之前,就會佔去約 3880 個 token:幾乎是錄製時所用的 4096 token 情境的全部。這個數字是算術推估,不是實測,實際的工具大小各有不同。較短的清單也會降低兩項說明重疊的機會,而這正是草稿中 get_order_status 與 quote_refund 的問題(撰寫供模型閱讀的說明)。

伺服器要讓清單保持簡短,做法是只服務單一對象。商店的伺服器服務的是客服工單,因此清單中沒有庫存盤點。在固定的修訂版本下,伺服器無法針對單一連線裁減其清單,不過清單可能因請求所帶的授權而不同,而且會以固定順序出現(快取清單結果)。該節涵蓋結果上的快取提示,而依權杖允許的範圍劃定工具則展示了依權杖而異的清單。

實用原則: 每個伺服器只服務一種對象,只提供該對象的任務所需的少數工具,並在你的主機提示中測量清單的成本。把 token 花在結構描述,以及區分模型容易混淆的兩個工具的那一句話上,刪掉與結構描述重複的說明文字。當主機需要的工具多到模型無法妥善選擇時,應把它們分散到多個伺服器,並且只連接某次對話所需的伺服器,而不是讓單一伺服器的清單取決於連線。

正式環境中會出什麼問題

最近一次變動於第 2026.11.11 版

商店的伺服器在單一機器上處理八張工單時運作正常。但面對整個工單佇列與真實的部署環境,工具設計會以幾種可辨認的方式失敗。

模型無法分辨的兩個工具。撰寫模型會讀的描述中的描述草稿,讓模型去查詢了本應直接報價的訂單。在正式環境中,徵兆是某個工具被呼叫的次數遠多於或遠少於它所服務的工單數,或是兩個工具被接連呼叫,而其實一個就夠。請對照已標註的工單來統計工具選擇(衡量正確工具被選中的頻率),並修正用來區分這兩個工具的那句描述。

**模型把範例值當成真實值送出。**在三張退款工單之一中,模型把 sku 參數描述裡的範例 SKU 當成顧客所寫的內容送出。KG-1031 是真實存在的產品,因此若沒有檢查該 SKU 是否在訂單上,工具就會對錯誤的產品報價。商店的描述之所以能保留真實的範例 ID,只是因為錄製時使用了這些 ID。徵兆是範例值出現在引數中的頻率,遠高於真實流量所能解釋的程度。請保留檢查,將每個引數與其所屬的紀錄綁在一起,並選用不可能是真實的範例,例如超出目前使用範圍的 ID。

**輸出綱要與程式碼脫節。**SDK 的用戶端會依據從 tools/list 快取的輸出綱要驗證每個結果,兩者不一致時就會引發 RuntimeError(mcp/client/session.py)。如果伺服器發布時移除或更改了某個欄位,而用戶端仍快取著舊的清單,那麼對該工具的每次呼叫都會失敗。伺服器發布後,你會在主機端看到 RuntimeError: Invalid structured content。請把輸出綱要視為一種契約並加以測試(將綱要當成契約來檢查)。

**模型讀不懂的當機。**凡不是 ToolError 或 MCPError 的例外,到達模型時都只是「Error executing tool」,沒有更多資訊。請留意模型重複相同的呼叫,或在對話中沒有任何原因就放棄的情形。請查看伺服器的標準錯誤輸出,並把模型有能力修正的每一種失敗都轉成 ToolError。

**隨行程消失的控制代碼。**商店的報價存放在伺服器的記憶體中。重新啟動會遺失所有未結的報價,模型會對幾分鐘前才建立的報價收到「There is no quote」。若同一個位址後面有多個複本,損失更大,因為在某一個複本上建立的報價,下一個複本並不知道。一旦伺服器以多個行程執行,就應把控制代碼存放在共用儲存空間中(在沒有黏性工作階段的情況下執行多個複本)。

**跨伺服器重名的工具。**連接到兩個伺服器的主機,可能會看到兩個名為 get_order_status 的工具。規格指出主機「SHOULD」加以區分,例如在每個名稱前加上伺服器識別碼作為前綴(tools,「Tool names」),而為跨伺服器的工具命名會實作這一點。

**標頭中的個人資料。**標記為 x-mcp-header 的參數,其值在 Streamable HTTP 上會被複製到 HTTP 標頭中,代理伺服器與日誌都看得到。規格指出伺服器「SHOULD NOT」以這種方式標記敏感參數,個人資料也包括在內(tools),因此絕不要標記顧客 ID 或電子郵件。透過 Streamable HTTP 提供服務會說明這個標頭。

**實用原則:**在商店的工具上線之前,請針對一組已標註的真實工單樣本,錄下你要發布的模型如何選擇工具;檢查模型有能力修正的每一種失敗,是否都以附有實用訊息的 ToolError 回傳;並為每個輸出綱要加上契約測試。發布之後,請監看工具選擇的次數、引數中的範例值,以及主機端的 RuntimeError。

本章做出的決定

最近一次變動於第 2026.11.11 版
  • 採用五個任務型工具,而不是每個端點一個工具:find_orders、get_order_status、quote_refund、issue_refund與check_stock,都放在lib.shop_tools中。庫存盤點不放在客服伺服器上。
  • 退款拆成報價與核發兩個步驟。quote_refund負責計算金額,並回傳有效期為 15 分鐘的 quote_id;issue_refund只接受這個代號。
  • **伺服器信任呼叫端提供的 customer_id,**而 quote_id 雖是隨機產生,卻很短,也不綁定任何客戶。保護工具以防濫用一章的做法,是從已驗證的權杖取得執行操作的使用者,而不是從引數取得。
  • **目前尚無同意機制。**在政策的上限之內,issue_refund不會詢問任何人就直接執行;主機端的同意機制會在在產生副作用之前徵求同意中介紹。
  • **描述以 description= 傳入,**並出自同一份字典。每則描述都說明該工具的作用、何時應選用它而非相鄰的工具、它的輸入與結果。這些描述曾經修訂一次,依據是某個模型在八張工單上的選擇紀錄;這次執行的改善歸功於整體修訂,而不是其中任何一句。
  • **每個引數都以 Annotated[..., Field(...)] 做嚴格的型別限定:**ID 使用樣式、狀態使用列舉、limit 使用範圍界限、placed_since 使用日期。
  • **每個工具都回傳 pydantic 模型,**因此 SDK 會公開輸出綱要,並傳送不含 {"result": ...} 包裝的結構化內容。
  • **被拒絕的引數會以執行錯誤的形式回傳,**這與規格的工具頁面及 SDK 的做法一致,模型因此可以讀取錯誤並修正自己的呼叫。
  • **模型能夠自行修正的問題使用 ToolError,**並在訊息中附上有效的值;API 金鑰被拒絕時使用 MCPError;其餘情況一律維持為一般的當機。
  • **每個工具都有加上註解。**讀取類工具是唯讀且封閉世界的。issue_refund是累加式、封閉世界且具冪等性的,提示的背後有伺服器端僅執行一次的檢查作為支撐。
  • **來自其他伺服器的註解不可信任,**同意與否絕不單靠這些註解決定。
  • **報價存放在伺服器的記憶體中,**這只在單一 stdio 行程內成立。若有多個副本,就需要共用的儲存空間。

本章,於本版次中

版次 2026.11.14範例於 2026年11 月 19 通過測試本章 7 個範例 個範例中有 7 個通過

譯自英文書,版次 2026.11.14。

引用本節

格式

各種格式皆引用英文原書,本譯本即依循該原書。

每種格式都會標示本版。其連結會開啟目前版次,節標題會說明該節內文最後一次變動的時間。存取日期與擷取日期即為你開啟此頁的當日。

本頁內容

第 3 章,共 12 章: 設計模型能夠使用的工具

  1. Shape tools around tasks, not endpoints
  2. 撰寫模型會讀的描述
  3. 以 JSON Schema 為輸入定型
  4. Return structured content with an output schema
  5. 將失敗回報為工具結果
  6. Mark what a tool changes with annotations
  7. 將註解視為提示,而非保證
  8. 讓工具清單保持精簡
  9. 正式環境中會出什麼問題
  10. 本章做出的決定

返回頂端所有章節