Projete ferramentas que um modelo pode usar
Cerca de 42 minutos min de leitura, com 7 exemplos em 10 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.14. Leia o original
Nesta página
- Shape tools around tasks, not endpoints
- Escreva descrições que o modelo lê
- Tipifique as entradas com JSON Schema
- Return structured content with an output schema
- Informe falhas como resultados de ferramentas
- Mark what a tool changes with annotations
- Trate as anotações como dicas, não como garantias
- Mantenha a lista de ferramentas pequena
- O que dá errado em produção
- Decisões tomadas neste capítulo
Ao final deste capítulo, você saberá transformar a API da loja em ferramentas do Model Context Protocol cujos nomes, descrições, esquemas de entrada, resultados e erros um modelo consiga aproveitar, e medirá como uma mudança na descrição de uma ferramenta altera a ferramenta que um modelo escolhe. Tudo o que segue vale para a revisão 2026-07-28 da especificação e para o SDK para Python, mcp 2.3.0.
Toda ferramenta deste capítulo existe para ajudar um modelo a responder a um dos tickets de atendimento da loja. O servidor da loja, shop-support, tem por enquanto apenas uma ferramenta: get_order_status, apresentada em Envolva um endpoint como uma ferramenta. O que o MCP acrescenta a uma API também lhe deu um recurso e um prompt, mas uma única ferramenta não consegue responder à maioria dos tickets. Os clientes também perguntam qual pedido era qual, quanto seria um reembolso, pedem para ser reembolsados e se um produto está em estoque.
As ferramentas de um servidor do Model Context Protocol (MCP) são a única parte da loja que um modelo enxerga. O modelo nunca lê o código da loja nem a sua API. Ele lê o nome, a descrição e o esquema de entrada de cada ferramenta, escolhe uma delas e preenche os argumentos. Depois lê o que volta, inclusive qualquer erro. Por isso, uma ferramenta é uma interface projetada para um leitor que não pode fazer perguntas, e cada parte da definição é uma oportunidade de ajudar esse leitor ou de induzi-lo ao erro.
Este capítulo constrói o conjunto completo de ferramentas para esses tickets e testa cada decisão de projeto.
Esta parte ainda não foi traduzida, por isso está em inglês.
Shape tools around tasks, not endpoints
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_orderssearches 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_statuslooks up one order by its ID, as in chapter 1.quote_refundworks out what a refund would be, and changes nothing.issue_refundmakes 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_stockreports 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.
1"""Two tool lists for the same API, one tool per endpoint as a generator writes them and the shop's five task tools, then2ticket T-0024's refund both ways. The point rests on two printed lines: the endpoint tool records the amount the model3sent, and quote_refund's amount is the server's own figure, which the code asserts is within the limit."""4import asyncio56import httpx27from mcp import Client89from lib import loopback, shop_api, shop_tools101112async def main() -> None:13 for tool in shop_tools.endpoint_tools():14 print("endpoint tool:", tool.name, tool.input_schema["required"])15 with loopback.serve(shop_api.create_app()) as base_url:16 async with Client(shop_tools.server_params(base_url)) as client:17 print("protocol revision:", client.protocol_version)18 for tool in (await client.list_tools()).tools:19 print("task tool:", tool.name, tool.input_schema.get("required", [])) # .get: no "required" key if none2021 # T-0024: "please refund the aluminium muffin tray on o2415". The endpoint tool post_refunds forwards22 # its arguments to POST /refunds, so the amount is whatever the model sends, such as the order's total.23 order = httpx2.get(f"{base_url}/orders/O-2415", headers={"X-API-Key": shop_api.DEMO_API_KEY}).json()24 refund = httpx2.post(f"{base_url}/refunds", headers={"X-API-Key": shop_api.DEMO_API_KEY},25 json={"order_id": "O-2415", "amount": order["total"], "reason": "damaged"})26 print("post_refunds status:", refund.status_code)27 print("post_refunds amount:", refund.json()["amount"])2829 quote = await client.call_tool("quote_refund", {"order_id": "O-2415", "sku": "KG-1050",30 "reason": "arrived damaged"})31 print("quote_refund amount:", quote.structured_content["amount"])32 print("quote_refund within limit:", quote.structured_content["within_limit"])33 assert quote.structured_content["within_limit"] # the muffin tray's line is under the refund policy's limit343536asyncio.run(main())
python tools-from-endpoints.pyendpoint 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.
Escreva descrições que o modelo lê
As ferramentas de tarefa da seção anterior só ajudam se o modelo escolher a certa, e ele escolhe a partir do que o host lhe mostra. O laço do host do livro, lib.host, mostra ao modelo o nome, a descrição e o esquema de entrada de cada ferramenta. A especificação chama a descrição de uma "dica" que os clientes podem usar "to improve the LLM's understanding of available tools" (esquema, Tool.description).
A maioria das descrições publicadas é ruim. Um estudo de 856 ferramentas em 103 servidores constatou que 97.1% tinham pelo menos um defeito, e que 56% não diziam com clareza para que a ferramenta serve (Hasan e outros, 2026). Em um teste controlado com duas ferramentas de interfaces idênticas, editar apenas a descrição de uma delas deu a ela mais de 10 vezes o uso da original com dois dos modelos testados (Faghih e outros, 2025). Mais longo não é automaticamente melhor. No primeiro estudo, descrições totalmente reescritas elevaram o sucesso da tarefa em uma mediana de 5.85 pontos, mas acrescentaram 67% mais passos e pioraram 1 caso em cada 6.
Uma descrição que ajuda diz quatro coisas: o que a ferramenta faz, quando usá-la em vez da vizinha, como são as suas entradas e o que ela devolve. No SDK de Python, a descrição de uma ferramenta é a docstring da sua função, a menos que você passe description= ao decorator (ferramentas). Em Python 3.12.15, o runtime do livro, o SDK repassa a docstring exatamente como está escrita (mcp/server/mcpserver/tools/base.py), de modo que uma docstring que ocupa várias linhas envia ao modelo as quebras de linha e a indentação. O servidor da loja guarda as descrições em um único dicionário, DESCRIPTIONS, e repassa cada uma como description=.
O exemplo mostra ao modelo oito tickets e as cinco ferramentas da loja três vezes, cada vez com um conjunto diferente de descrições. Só as descrições mudam.
- O conjunto vago tem uma linha por ferramenta, do tipo que um gerador de endpoints escreve, como "Refund quote."
- O conjunto rascunho é o primeiro rascunho da loja, escrito como docstrings.
- O conjunto revisado é o segundo rascunho da loja, escrito depois de ler os resultados do rascunho.
Os oito foram escolhidos à mão na fila de tickets da loja, e não por amostragem: dois perguntam quais pedidos um cliente tem, dois onde está um pedido, três sobre reembolsos e um sobre estoque. Nenhum traz instruções injetadas ou um número de pedido digitado errado. Antes de executar, preveja quantas primeiras chamadas corretas o conjunto vago e o rascunho acertam, cada um.
O modelo é o mesmo usado em todas as gravações deste livro: Qwen3-4B-Instruct-2507, executado na CPU com llama.cpp, como Deixe um modelo escolher a ferramenta o configurou. O script recordings/description_choices.py fez esta gravação, description-choices, amostrando uma resposta por ticket, com temperatura 0.7 e uma única semente fixa. A avaliação olha apenas para a primeira ferramenta que o modelo chama, e não para os seus argumentos. A primeira ferramenta certa de um ticket é a que os dados da loja marcam para ele, com uma mudança: issue_refund precisa de um quote_id, portanto um pedido de reembolso começa com quote_refund.
1"""Predict, then run: eight of the shop's tickets and the same five tools, shown to the model with three sets of2descriptions: one-line ones, the shop's first draft, and its revision. Only the descriptions differ. The model's3replies are a recording (examples/data/recorded/description-choices/), made with recordings/description_choices.py."""4import asyncio5import json67from mcp import Client89from lib import shop_tools10from lib.host import ReplayModel, choose_tool11from lib.shop_data import load_shop1213TICKETS = ("T-0002", "T-0013", "T-0004", "T-0022", "T-0006", "T-0029", "T-0024", "T-0016")14SETS = {"vague": shop_tools.VAGUE_DESCRIPTIONS, "draft": shop_tools.DRAFT_DESCRIPTIONS,15 "revised": shop_tools.DESCRIPTIONS}16model = ReplayModel("description-choices") # the recorded replies, so no model runs here171819def right_tool(ticket) -> str:20 """The tool a correct host calls first. issue_refund takes a quote_id, so a refund starts with quote_refund."""21 return "quote_refund" if ticket.expected_tool == "issue_refund" else ticket.expected_tool222324async def main() -> None:25 shop = load_shop()26 async with Client(shop_tools.create_server()) as client: # in-process: listing tools calls no API27 listed = (await client.list_tools()).tools28 right = dict.fromkeys(SETS, 0)29 for ticket_id in TICKETS:30 ticket = shop.ticket(ticket_id)31 # the same tools each time, with only their descriptions swapped32 choices = {label: choose_tool(model, ticket, shop_tools.with_descriptions(listed, descriptions))33 for label, descriptions in SETS.items()}34 for label, choice in choices.items():35 right[label] += choice.tool == right_tool(ticket)36 if all(choice.tool == right_tool(ticket) for choice in choices.values()):37 print(f"{ticket_id} all three:", right_tool(ticket))38 continue39 print(f"{ticket_id} needs:", right_tool(ticket))40 for label, choice in choices.items():41 print(f"{ticket_id} {label}:", choice.tool or "none")42 if choices["revised"].tool == "quote_refund":43 print(f"{ticket_id} revised sku:", choices["revised"].arguments.get("sku"))44 print(f"{ticket_id} order's skus:", ", ".join(line.sku for line in shop.order(ticket.order_id).lines))45 print("sampling temperature:", json.loads((model.folder / "manifest.json").read_text())["sampling"]["temperature"])46 for label, count in right.items():47 print(f"{label} right:", f"{count} of {len(TICKETS)}")484950asyncio.run(main())
python vague-description-wrong-tool.pyT-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
O conjunto vago escolheu a primeira ferramenta certa em 5 of 8 tickets, e o rascunho fez o mesmo, 5 of 8. Só os nomes e os parâmetros bastaram para os quatro tickets de pedidos e o ticket de estoque, de modo que os três conjuntos escolheram a mesma ferramenta certa em cada um. A redação mais longa do rascunho não ajudou nos três tickets de reembolso, em que as escolhas diferiram. O ticket T-0006, sobre um pedido que "arrived with the enamelled saute pan cracked. what can you refund me", recebeu get_order_status do conjunto vago e get_order_status do rascunho.
O rascunho dizia o que quote_refund faz, mas não que ele torna desnecessário consultar o pedido. A revisão diz isso nas duas ferramentas. get_order_status encaminha perguntas sobre reembolso para quote_refund, e quote_refund pede para ser chamada primeiro porque "it checks the order itself". A revisão mudou, porém, mais do que isso. Ela reescreveu o início da descrição de quote_refund e, passada como description= em vez de como docstring, eliminou as quebras de linha e a indentação do rascunho. Com as três mudanças, o conjunto revisado escolheu a primeira ferramenta certa em 8 of 8 tickets. A execução não mostra qual mudança fez diferença.
A revisão corrigiu a escolha da ferramenta, mas não os argumentos: nenhuma das três chamadas de reembolso teria funcionado. Para o T-0006, o modelo enviou o SKU KG-1031, o exemplo na descrição do próprio parâmetro sku, e nenhum dos três SKUs que enviou estava no pedido dele. Informe falhas como resultados de ferramenta mostra como o servidor da loja detecta esse erro. A data do T-0013 estava errada nos três conjuntos, como mostra a próxima seção.
Leia estas contagens como uma única medição. Elas vêm de um modelo, com uma semente, em oito tickets escolhidos à mão, e outra semente poderia mudar algumas escolhas. A revisão foi escrita depois de ler os resultados nesses mesmos oito tickets, de modo que a pontuação dela é favorecida. Meça com que frequência a ferramenta certa é escolhida mede as escolhas em toda a fila de tickets, que é o teste que decide.
Regra prática: Escreva cada descrição em duas a quatro frases: o que a ferramenta faz, quando usá-la em vez da ferramenta com que ela mais se confunde, como são as suas entradas e o que ela devolve. Passe-a como description= em vez de confiar em uma docstring de várias linhas, para que o modelo leia exatamente o texto que você escreveu. Depois, grave o modelo que você vai entregar escolhendo ferramentas para tickets reais, leia as escolhas erradas e altere as descrições para as quais essas escolhas apontam. Mude uma coisa por gravação quando precisar saber qual mudança funcionou, e verifique o resultado em tickets que você não usou para escrever a mudança.
Tipifique as entradas com JSON Schema
A descrição da seção anterior diz ao modelo o que a ferramenta espera, e um esquema de entrada faz o servidor impor essa expectativa. Toda ferramenta tem um inputSchema, um objeto JSON Schema cuja raiz tem "type": "object". Na revisão fixada, qualquer palavra-chave do JSON Schema 2020-12 pode aparecer nele (changelog), incluindo oneOf, if, then, else e $ref (schema, Tool.inputSchema). Um esquema sem o campo $schema é lido como 2020-12, e as implementações "MUST NOT" seguir automaticamente um $ref que aponte para uma URI de rede (protocolo base). Por isso, por padrão, um esquema não consegue fazer o cliente baixar nada.
O esquema cumpre duas funções. Ele mostra ao modelo a forma de uma chamada válida e permite que o servidor rejeite uma chamada inválida antes que qualquer código da ferramenta seja executado. A especificação torna a parte do servidor um requisito: os servidores "MUST" validar todas as entradas da ferramenta (ferramentas, "Security considerations").
O SDK de Python constrói o esquema a partir das dicas de tipo da função, e o Annotated[..., Field(...)] do pydantic acrescenta restrições a essas dicas (ferramentas). O servidor da loja define seus tipos de ID uma única vez. OrderId é uma string com pattern=r"^O-\d{4}$", e CustomerId e Sku funcionam da mesma forma. find_orders recebe status como um Literal dos cinco status de pedido, placed_since como date, e limit como um inteiro com ge=1, le=50. O esquema que o SDK construiu a partir dessas dicas é impresso primeiro. Em seguida, find_orders é chamada de três maneiras: com três argumentos inválidos ao mesmo tempo, com um número enviado como string e com a data que o modelo gravado enviou para o chamado T-0013 em Escreva descrições que o modelo lê. Esse chamado pedia pedidos "since 12 Jun".
1"""find_orders' typed inputs: the JSON Schema the SDK builds from them, one result that names three rejected arguments,2a string the SDK converts without complaint, and a date that is valid but wrong. The point rests on the last two order3counts: a date that passes validation can still return the wrong orders."""4import asyncio5import json67from mcp import Client89from lib import loopback, shop_api, shop_tools101112async def main() -> None:13 with loopback.serve(shop_api.create_app()) as base_url:14 async with Client(shop_tools.server_params(base_url)) as client:15 tools = {tool.name: tool for tool in (await client.list_tools()).tools}16 for name, prop in tools["find_orders"].input_schema["properties"].items():17 rules = {k: v for k, v in prop.items() if k in ("pattern", "minimum", "maximum", "default")}18 # an optional argument's schema is anyOf: its type or enum, and null19 kinds = [p.get("enum") or p.get("format") or p["type"] for p in prop.get("anyOf", [prop])]20 print(f"{name}:", json.dumps(kinds), json.dumps(rules))2122 bad = await client.call_tool("find_orders", {"customer_id": "42", "status": "lost", "limit": 500})23 print("bad arguments is error:", bad.is_error)24 assert bad.is_error25 print(bad.content[0].text)2627 # "5" is a string; pydantic converts it to the integer 5 before the tool runs28 loose = await client.call_tool("find_orders", {"customer_id": "C-0085", "limit": "5"})29 print("string limit is error:", loose.is_error)30 assert not loose.is_error31 print("string limit orders:", len(loose.structured_content["orders"]))3233 # T-0013 asks for orders "since 12 Jun"; the recorded model sent 2023-06-12, a valid date34 wrong_year = await client.call_tool("find_orders", {"customer_id": "C-0085", "placed_since": "2023-06-12"})35 right_year = await client.call_tool("find_orders", {"customer_id": "C-0085", "placed_since": "2026-06-12"})36 print("since 2023-06-12 orders:", len(wrong_year.structured_content["orders"]))37 print("since 2026-06-12 orders:", len(right_year.structured_content["orders"]))383940asyncio.run(main())
python reject-bad-arguments.pycustomer_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
Cada dica se tornou uma palavra-chave do esquema: pattern para o ID do cliente, enum para o status, "format": "date" para a data, e minimum e maximum para o limite. A chamada com três argumentos inválidos voltou como um único resultado com falha, e o texto dele nomeia cada argumento que falhou, a regra que ele violou e o valor enviado. Um modelo pode corrigir os três na chamada seguinte.
O SDK é mais tolerante que o esquema em um aspecto. O esquema diz que limit é um inteiro, mas a chamada com "5" foi bem-sucedida e retornou 5 pedidos. O pydantic, que valida os argumentos, converte por padrão uma string numérica em inteiro. Isso é inofensivo aqui. Quando uma string e um número precisam continuar distintos, declare o campo com Field(strict=True). O pydantic também descarta, sem erro, qualquer argumento que o esquema não declare (mcp/server/mcpserver/utilities/func_metadata.py), o que Evite que o servidor atue como um deputado confuso pressupõe.
A data é o erro que nenhum esquema detecta. A data "12 Jun" do chamado não tem ano, e o modelo enviou 2023-06-12, uma data válida três anos antes do fim dos dados da loja. A chamada passou na validação e retornou 5 pedidos, ou seja, todos os pedidos do cliente, em vez dos 1 feitos desde 12 de junho do ano da loja. O esquema verifica a forma. O significado precisa vir de outro lugar, como o host colocar a data do chamado no prompt, ou a descrição dizer como interpretar uma data sem ano.
A especificação não é consistente quanto ao destino de um argumento rejeitado. Sua página de ferramentas lista a validação de entrada entre os erros de execução de ferramentas, que voltam como resultado. Sua referência de esquema lista "invalid tool arguments" sob o erro JSON-RPC -32602 (schema, InvalidParamsError). O SDK segue a página de ferramentas, e este livro também. Os clientes "SHOULD" repassar os erros de execução ao modelo, mas apenas "MAY" repassar erros de protocolo, que a especificação descreve como "less likely to result in successful recovery" (ferramentas, "Error handling"). Um resultado é o caminho que o modelo pode contar que será lido.
Regra prática: Tipifique cada argumento de forma tão restrita quanto a API permitir: um padrão para IDs, um enum para valores fixos, limites para contagens e um formato para datas. Deixe o SDK rejeitar as chamadas inválidas antes que o seu código seja executado, e retorne todas as falhas de uma só vez. Não confie no esquema para expressar o significado, porque uma data válida ainda pode ser a data errada. Verifique dentro da ferramenta o que o esquema não consegue expressar, e diga na descrição como preencher um valor que os chamados costumam deixar incompleto.
Esta parte ainda não foi traduzida, por isso está em inglês.
Return structured content with an output schema
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.
1"""quote_refund returns a pydantic model, so the SDK publishes its output schema and returns structuredContent; a tool2that returns a bare string gets a {"result": ...} wrapper instead. The point rests on the bare structured content line,3and the quote's within-limit flag and text block, which the code asserts."""4import asyncio5import json67from mcp import Client8from mcp.server.mcpserver import MCPServer910from lib import loopback, shop_api, shop_tools11from lib.shop_data import load_shop, money1213bare = MCPServer("bare-return")141516@bare.tool()17def refund_amount(order_id: str) -> str:18 """The refund for a whole order, as a decimal string."""19 return money(load_shop().order(order_id).total_cents)202122async def main() -> None:23 with loopback.serve(shop_api.create_app()) as base_url:24 async with Client(shop_tools.server_params(base_url)) as client:25 tools = {tool.name: tool for tool in (await client.list_tools()).tools}26 print("output schema requires:", ", ".join(tools["quote_refund"].output_schema["required"]))27 quote = await client.call_tool("quote_refund", {"order_id": "O-2289", "reason": "arrived cracked"})28 shown = {**quote.structured_content, "quote_id": "(random)"} # quote IDs differ on every run29 print("structured content:", json.dumps(shown))30 print("amount:", quote.structured_content["amount"])31 print("within limit:", quote.structured_content["within_limit"])32 assert quote.structured_content["within_limit"] is False33 # the lifetime is in seconds; the prose gives it in minutes34 print("quote lifetime minutes:", quote.structured_content["expires_in_seconds"] // 60)35 # the text block a client that reads only text gets, parsed back to JSON36 same_json = json.loads(quote.content[0].text) == quote.structured_content37 print("text block is the same JSON:", same_json)38 assert same_json3940 async with Client(bare) as client: # in-process: no wire needed to read a schema41 tool = (await client.list_tools()).tools[0]42 print("bare output schema:", json.dumps(tool.output_schema))43 result = await client.call_tool("refund_amount", {"order_id": "O-2289"})44 print("bare structured content:", json.dumps(result.structured_content))454647asyncio.run(main())
python refund-quote-structured.pyoutput 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.
Informe falhas como resultados de ferramentas
A cotação da seção anterior é o resultado quando uma chamada funciona. Quando uma chamada falha, a especificação lhe dá um de dois caminhos (ferramentas, "Error handling"). Um erro de protocolo é um erro JSON-RPC, para uma ferramenta desconhecida, uma requisição que não se encaixa no schema de tools/call, ou uma falha do servidor. Um erro de execução de ferramenta é um resultado comum com isError definido como true, para uma falha da API, uma entrada inválida ou uma regra de negócio quebrada. Erros de ferramenta, como este livro os chama, segundo a especificação, "contêm feedback acionável que modelos de linguagem podem usar para se autocorrigir", e os clientes "SHOULD" repassá-los ao modelo.
Como os clientes SHOULD repassar erros de execução ao modelo e apenas MAY repassar erros de protocolo, o caminho determina quem pode corrigir a falha. No SDK de Python, lançar ToolError produz um erro de execução com a sua mensagem. Lançar MCPError produz um erro de protocolo. Qualquer outra exceção conta como uma falha grave (crash): o resultado diz apenas "Error executing tool" e o nome da ferramenta, e a exceção permanece no log do servidor (tratamento de erros). O guia do SDK formula a escolha como uma pergunta: um modelo mais inteligente poderia ter evitado essa falha? Se sim, lance ToolError; se não, lance MCPError.
O servidor da loja segue esse teste. Um pedido inexistente, um pedido que não pode ser reembolsado, um SKU que não está no pedido e uma cotação desconhecida ou expirada são todos ToolErrors, cada um com uma mensagem que diz o que fazer em vez disso. Um 401 da API da loja significa que a chave do servidor está errada, o que nenhum modelo pode corrigir; por isso, o servidor lança MCPError com o código de erro interno do JSON-RPC. Qualquer outra falha, como a API estar fora do ar, continua sendo uma falha inesperada. Cinco chamadas falham de propósito, listadas na ordem em que o código as faz:
- a chamada registrada do ticket T-0006, das descrições revisadas em Escreva descrições que o modelo lê, com seu SKU inventado;
issue_refundcom uma cotação que o servidor nunca emitiu;- uma ferramenta que não existe;
- uma chamada a um servidor iniciado com a chave errada;
- uma chamada depois que a API da loja parou.
1"""Five failures and the path each takes: three tool execution errors the model reads (isError results), a crash the2model sees only as a generic message, and a protocol error (a JSON-RPC error) that only the host sees. The point rests3on which results are flagged as errors, and the code asserts that a missing tool is one of them."""4import asyncio56from mcp import Client, MCPError78from lib import loopback, shop_api, shop_tools9from lib.host import ReplayModel, choose_tool10from lib.shop_data import load_shop111213async def attempt(params, name: str, arguments: dict, label: str) -> object | None:14 async with Client(params) as client:15 try:16 result = await client.call_tool(name, arguments)17 print(f"{label} is error:", result.is_error)18 print(f"{label} says:", result.content[0].text)19 return result20 except MCPError as error:21 print(f"{label} JSON-RPC error code:", error.code)22 print(f"{label} JSON-RPC error message:", error.message)23 return None242526async def main() -> None:27 with loopback.serve(shop_api.create_app()) as base_url:28 params = shop_tools.server_params(base_url)29 async with Client(params) as client: # T-0006's recorded choice, with the SKU the model made up30 tools = (await client.list_tools()).tools31 choice = choose_tool(ReplayModel("description-choices"), load_shop().ticket("T-0006"), tools)32 await attempt(params, choice.tool, choice.arguments, "wrong SKU")33 await attempt(params, "issue_refund", {"quote_id": "Q-0000000000"}, "unknown quote")34 unknown = await attempt(params, "refund_order", {"order_id": "O-2289"}, "unknown tool")35 assert unknown is not None and unknown.is_error # a failed result, not a protocol error36 # a key the shop's API rejects: the server answers with a protocol error, which the client raises37 await attempt(shop_tools.server_params(base_url, api_key="wrong-key"), "get_order_status",38 {"order_id": "O-2289"}, "rejected key")39 await attempt(params, "get_order_status", {"order_id": "O-2289"}, "API down") # the API has stopped404142asyncio.run(main())
python tool-error-versus-protocol-error.pywrong 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
O SKU inventado voltou como um erro de execução, e o texto dele dá ao modelo o que faltava: "Error executing tool quote_refund: Order O-2289 has no line for KG-1031. Its SKUs are KG-1043." Um modelo que lê isso pode chamar de novo com o SKU correto. A mensagem da cotação desconhecida funciona da mesma forma: "Error executing tool issue_refund: There is no quote Q-0000000000. Call quote_refund for the order to get a quote_id."
A ferramenta desconhecida mostra um desvio da especificação. O exemplo da especificação responde a uma ferramenta desconhecida com o erro JSON-RPC -32602, mas o servidor do SDK retorna, em vez disso, um erro de execução (mcp/server/mcpserver/tools/tool_manager.py). O resultado é marcado como erro, e o texto dele é "Unknown tool: refund_order". Para um modelo, essa é a resposta mais útil, pois mostra que o nome estava errado. Um host que conta erros de protocolo para identificar um modelo confuso não verá esses casos, por isso conte também os erros de execução.
A chave errada seguiu o outro caminho. O cliente lançou MCPError, e o exemplo a capturou como o erro JSON-RPC -32603, com a mensagem "The shop's API rejected this server's key. The server needs reconfiguring." O código do host vê isso, e o modelo só vê se o host o repassar. Quando a API estava fora do ar, o modelo recebeu apenas "Error executing tool get_order_status", e a exceção permaneceu no log do servidor (tratamento de erros).
Há ainda um erro que ignora os dois caminhos: uma ferramenta que retorna uma mensagem de erro como uma string comum. O SDK envia uma string retornada com isError definido como false, então o modelo lê o erro como uma resposta bem-sucedida (tratamento de erros). Lance uma exceção.
Regra prática: Lance ToolError para toda falha que um modelo poderia corrigir, com uma mensagem que diga o que estava errado e o que enviar no lugar, incluindo os valores válidos quando forem poucos. Lance MCPError apenas para falhas que nenhum modelo pode resolver, como configuração, e deixe as exceções inesperadas genéricas, para que os detalhes internos fiquem no servidor. Nunca retorne um erro como uma string simples.
Esta parte ainda não foi traduzida, por isso está em inglês.
Mark what a tool changes with annotations
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.
1"""What each tool's annotations tell a host, with the specification's defaults filled in where a hint is missing, and2whether the server keeps issue_refund's idempotent promise when the same call arrives twice. The point rests on the two3refund pairs: issue_refund returns one refund both times, while two posts to the endpoint make two."""4import asyncio56import httpx27from mcp import Client89from lib import loopback, shop_api, shop_tools1011# the specification's defaults, used for any hint a tool leaves out12DEFAULTS = {"read_only_hint": False, "destructive_hint": True, "idempotent_hint": False, "open_world_hint": True}131415def assumed(annotations) -> dict:16 """The hints a host should assume: each one the tool sets, and the specification's default for the rest."""17 given = annotations.model_dump(exclude_none=True) if annotations else {}18 hints = {hint: given.get(hint, default) for hint, default in DEFAULTS.items()}19 if hints["read_only_hint"]: # destructive and idempotent apply only to a tool that changes something20 del hints["destructive_hint"], hints["idempotent_hint"]21 return hints222324async def main() -> None:25 with loopback.serve(shop_api.create_app()) as base_url:26 async with Client(shop_tools.server_params(base_url)) as client:27 tools = (await client.list_tools()).tools + shop_tools.endpoint_tools()[3:4] # + post_refunds28 for tool in tools:29 hints = assumed(tool.annotations)30 shown = ", ".join(h.removesuffix("_hint") for h, on in hints.items() if on) or "nothing"31 print(f"{tool.name} assumes:", shown)32 print(f"{tool.name} asks consent:", not hints["read_only_hint"])3334 quote = (await client.call_tool("quote_refund", {"order_id": "O-2415", "sku": "KG-1050"})).structured_content35 first = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})36 again = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})37 print("issue_refund first refund:", first.structured_content["refund_id"])38 print("issue_refund second refund:", again.structured_content["refund_id"])3940 # the amount the quote for KG-1050 gave, posted straight to the endpoint41 twice = [httpx2.post(f"{base_url}/refunds", headers={"X-API-Key": shop_api.DEMO_API_KEY},42 json={"order_id": "O-2415", "amount": "23.98"}).json()["refund_id"] for _ in range(2)]43 print("post_refunds first refund:", twice[0])44 print("post_refunds second refund:", twice[1])454647asyncio.run(main())
python annotate-the-refund-tool.pyfind_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.
Trate as anotações como dicas, não como garantias
Nada no protocolo verifica uma anotação contra o que a ferramenta realmente faz. A especificação diz que as anotações "are not guaranteed to provide a faithful description of tool behavior", e que os clientes "DEVEM" considerá-las não confiáveis, a menos que venham de servidores confiáveis (schema, ToolAnnotations; tools). Um servidor que marca uma ferramenta de reembolso como somente leitura passa por qualquer host que acredite nisso. Detectar descrições de ferramentas envenenadas mostra um servidor cujas definições de ferramenta mentem de propósito.
Para o autor do servidor, uma dica é uma promessa que o código precisa cumprir. O issue_refund da loja é idempotente porque o armazenamento de cotações faz com que seja, não porque a anotação diz isso. Se uma reinicialização perder o armazenamento, uma chamada repetida receberia "There is no quote" em vez de um segundo reembolso, o que ainda é seguro. Mantenha a verificação no servidor e trate a anotação como uma descrição dela.
Regra prática: Anote toda ferramenta, porque deixar as dicas de fora leva um host cauteloso a presumir o pior. Marque uma ferramenta como idempotente somente quando o servidor garante isso, e mantenha reembolsos, pagamentos e qualquer outra coisa que deva acontecer uma única vez atrás de uma verificação no servidor. Como host, use anotações de um servidor em que você confia para decidir o que mostrar ao usuário, nunca como permissão para pular o consentimento (Peça consentimento antes de efeitos colaterais), e trate as anotações de qualquer outro servidor como afirmações não verificadas.
Mantenha a lista de ferramentas pequena
O host coloca cada ferramenta das seções anteriores, com sua descrição e seu esquema de entrada, no prompt do modelo a cada turno, e o modelo lê a lista inteira antes de escolher. Mais ferramentas custam mais tokens e também tornam a escolha mais difícil. Em um teste com servidores MCP, recuperar apenas as ferramentas relevantes para uma solicitação mais que triplicou a precisão de seleção, de 13.62% para 43.13% (Gan e Sun, 2025). Em dispositivos de borda, oferecer a modelos pequenos menos ferramentas aumentou o sucesso de suas chamadas de função e reduziu o tempo de execução em até 70% (Paramanayakam e outros, 2025). Ambos são estudos únicos, com configurações próprias, então leia-os como a direção do efeito, não como números para a loja.
O custo é mais fácil de medir do que de adivinhar. Quando o script de gravação foi executado, ele também contou, com o tokenizador do modelo de gravação, quantos tokens cada ferramenta ocupa no prompt do host. A verificação soma essas contagens para as ferramentas revisadas, as vagas de Escreva descrições que o modelo lê e as ferramentas de endpoint, e mede os seus bytes. Ela se recusa a rodar se alguma ferramenta tiver mudado desde que seus tokens foram contados.
1"""What the shop's tool list costs in the host's prompt: bytes, and tokens counted with the recording model's tokenizer2when the recording was made (examples/data/recorded/description-choices/prompt_tokens.json). The point rests on the3revised, vague and endpoint prompt token lines."""4import asyncio5import hashlib6import json78from mcp import Client910from lib import shop_tools11from lib.host import RECORDED, tool_specs1213# the token counts and line hashes the recording script wrote14counted = json.loads((RECORDED / "description-choices" / "prompt_tokens.json").read_text())151617def cost(label: str, tools) -> tuple[int, int]:18 """Bytes and tokens of the tools as the host's prompt renders them, one JSON line per tool."""19 lines = [json.dumps(spec, ensure_ascii=False) for spec in tool_specs(tools)]20 # the hash of each line as the host renders it; a tool that changed since then fails here21 for spec, line in zip(tool_specs(tools), lines):22 if counted[label][spec["name"]]["sha256"] != hashlib.sha256(line.encode()).hexdigest():23 raise LookupError(f"{spec['name']} changed since its tokens were counted: re-run the recording script")24 tokens = sum(counted[label][spec["name"]]["tokens"] for spec in tool_specs(tools))25 return sum(len(line.encode()) for line in lines), tokens262728async def main() -> None:29 async with Client(shop_tools.create_server()) as client:30 result = await client.list_tools()31 listed = result.tools32 print("tools/list result bytes:", len(result.model_dump_json(by_alias=True, exclude_none=True).encode()))33 vague = shop_tools.with_descriptions(listed, shop_tools.VAGUE_DESCRIPTIONS)34 for label, tools in (("revised", listed), ("vague", vague), ("endpoint", shop_tools.endpoint_tools())):35 size, tokens = cost(label, tools)36 print(f"{label} prompt bytes:", size)37 print(f"{label} prompt tokens:", tokens)38 tokens_per_tool = cost("revised", listed)[1] / len(listed) # cost returns (bytes, tokens): index 1 is tokens39 print("revised tokens per tool:", round(tokens_per_tool))40 print("20 such tools tokens:", round(20 * tokens_per_tool)) # arithmetic on the counts, not a count41 print("prompt without tools tokens:", counted["prompt_without_tools"])42 print("recording context tokens:", counted["context"])434445asyncio.run(main())
python tool-list-size.pytools/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
A maior parte do custo está nos esquemas. As cinco ferramentas revisadas da loja ocupam 970 tokens no prompt, contra 136 do restante das instruções do host. Com descrições vagas, elas ocupam 620, de modo que as descrições revisadas respondem por cerca de um terço do custo da lista. As ferramentas de endpoint ocupam 288: descrições de uma linha e esquemas sem padrões, enums ou descrições próprias. Os esquemas revisados são os mesmos que pegaram os argumentos inválidos em Tipifique as entradas com JSON Schema. A resposta completa de tools/list é ainda maior, porque também carrega esquemas de saída, títulos e anotações que o prompt do host deixa de fora, como mostram as contagens de bytes da saída.
Com cerca de 194 tokens por ferramenta, 20 ferramentas como essas ocupariam cerca de 3880 tokens antes de o modelo ler o ticket: quase todo o contexto de 4096 tokens com que as gravações rodam. Esse número é aritmética, não uma medição, e ferramentas reais variam de tamanho. Uma lista mais curta também reduz a chance de duas descrições se sobreporem, que foi o problema do rascunho com get_order_status e quote_refund (Escreva descrições que o modelo lê).
Um servidor mantém sua lista curta atendendo a um único público. O servidor da loja atende tickets de suporte, então a contagem de estoque não está nele. Na revisão fixada, um servidor não pode reduzir sua lista para uma conexão específica, embora a lista possa variar conforme a autorização que a solicitação apresenta, e ela vem em uma ordem fixa (Armazene em cache os resultados de lista). Essa seção trata das dicas de cache no resultado, e Limite as ferramentas pelo que o token permite mostra uma lista que varia conforme o token.
Regra prática: Dê a cada servidor um público e as poucas ferramentas de que as tarefas desse público precisam, e meça quanto a lista custa no prompt do seu host. Gaste os tokens nos esquemas e na frase que separa duas ferramentas que um modelo confunde, e corte o texto de descrição que repete o esquema. Quando um host precisa de mais ferramentas do que seu modelo escolhe bem, divida-as entre servidores e conecte apenas os servidores de que uma conversa precisa, em vez de fazer a lista de um servidor depender da conexão.
O que dá errado em produção
O servidor da loja atende oito tickets em uma única máquina. Em uma fila de tickets completa e em uma implantação real, o design de ferramentas falha de algumas maneiras reconhecíveis.
Duas ferramentas que o modelo não consegue distinguir. As descrições rascunhadas em Escreva descrições que o modelo lê fazem o modelo consultar pedidos que deveria ter cotado. Em produção, o sinal é uma ferramenta chamada muito mais, ou muito menos, vezes do que os tickets que ela atende, ou duas ferramentas chamadas uma após a outra quando uma bastaria. Conte as escolhas de ferramenta em relação a tickets rotulados (Meça com que frequência a ferramenta certa é escolhida) e corrija a frase que separa as duas ferramentas.
Valores de exemplo que o modelo envia como se fossem reais. Em um dos três tickets de reembolso, o modelo enviou o SKU de exemplo da descrição do parâmetro sku como se o cliente o tivesse escrito. KG-1031 é um produto real; sem a verificação de que o SKU está no pedido, a ferramenta teria cotado o produto errado. As descrições da loja mantêm seus IDs de exemplo reais apenas porque a gravação foi feita com eles. O sinal é um valor de exemplo que aparece nos argumentos com muito mais frequência do que o tráfego real explica. Mantenha verificações que vinculem cada argumento ao registro a que pertence e escolha exemplos que não possam ser reais, como IDs fora da faixa em uso.
Um schema de saída que se desvia do código. O cliente do SDK valida cada resultado contra o schema de saída que guardou em cache a partir de tools/list, e lança RuntimeError quando os dois não coincidem (mcp/client/session.py). Um servidor lançado com um campo removido ou alterado, sob um cliente que guardou em cache a lista antiga, falha em todas as chamadas a essa ferramenta. Você verá RuntimeError: Invalid structured content no host depois de um lançamento do servidor. Trate os schemas de saída como um contrato e teste-os (Verifique schemas como um contrato).
Falhas que o modelo não consegue ler. Toda exceção que não seja um ToolError ou um MCPError chega ao modelo como "Error executing tool" e nada mais. Procure um modelo que repete a mesma chamada, ou desiste, sem motivo na conversa. Leia o erro padrão do servidor e transforme cada falha que um modelo poderia corrigir em um ToolError.
Handles que morrem com o processo. As cotações da loja ficam na memória do servidor. Um reinício perde todas as cotações abertas, e o modelo recebe "There is no quote" para uma cotação que ele criou minutos antes. Várias réplicas atrás de um mesmo endereço perdem mais, porque uma cotação criada em uma réplica é desconhecida pela próxima. Mantenha os handles em armazenamento compartilhado assim que o servidor rodar como mais de um processo (Execute réplicas sem sticky sessions).
Nomes de ferramentas que colidem entre servidores. Um host conectado a dois servidores pode ver duas ferramentas chamadas get_order_status. A especificação diz que os hosts "SHOULD" desambiguar, por exemplo prefixando cada nome com um identificador do servidor (ferramentas, "Nomes de ferramentas"), e Nomeie ferramentas entre servidores constrói isso.
Dados pessoais em cabeçalhos. Um parâmetro marcado com x-mcp-header tem seu valor copiado para um cabeçalho HTTP no Streamable HTTP, onde proxies e logs podem vê-lo. A especificação diz que os servidores "SHOULD NOT" marcar parâmetros sensíveis, inclusive dados pessoais, dessa forma (ferramentas); por isso, nunca marque um ID de cliente ou um e-mail. Sirva sobre Streamable HTTP trata do cabeçalho.
Regra prática: Antes que as ferramentas da loja vão para produção, grave o modelo que você vai entregar escolhendo ferramentas para uma amostra rotulada de tickets reais, verifique que cada falha que um modelo poderia corrigir volte como um ToolError com uma mensagem útil, e coloque cada schema de saída sob um teste de contrato. Depois do lançamento, acompanhe as contagens de escolha de ferramenta, os valores de exemplo nos argumentos e os RuntimeErrors no host.
Decisões tomadas neste capítulo
- Cinco ferramentas de tarefa, e não uma ferramenta por endpoint:
find_orders,get_order_status,quote_refund,issue_refundecheck_stock, emlib.shop_tools. A recontagem de estoque fica fora do servidor de suporte. - Reembolsos divididos em cotação e emissão.
quote_refundcalcula o valor e devolve umquote_idválido por 15 minutos;issue_refundrecebe apenas esse identificador. - O servidor confia no
customer_idenviado pelo chamador, e umquote_idé aleatório, mas curto, e não está vinculado a nenhum cliente. Proteja as ferramentas contra uso indevido trata disso ao obter o usuário que age a partir do token verificado, e não de um argumento. - Ainda sem consentimento. Dentro do limite da política,
issue_refundé executada sem pedir confirmação a uma pessoa; o consentimento do host é tratado em Peça consentimento antes de efeitos colaterais. - As descrições são passadas como
description=, a partir de um único dicionário. Cada uma diz o que a ferramenta faz, quando usá-la em vez da ferramenta vizinha, suas entradas e seu resultado. Foram revisadas uma vez, com base nas escolhas registradas de um modelo em oito chamados, e a execução atribui o crédito à revisão como um todo, e não a qualquer frase isolada dela. - Cada argumento é tipado de forma restrita com
Annotated[..., Field(...)]: padrões para IDs, uma enumeração para status, limites paralimit, uma data paraplaced_since. - Cada ferramenta devolve um modelo pydantic, de modo que o SDK publica um esquema de saída e envia conteúdo estruturado sem o invólucro
{"result": ...}. - Argumentos rejeitados voltam como erros de execução, como a página de ferramentas da especificação e o SDK os definem, para que o modelo possa lê-los e corrigir sua chamada.
ToolErrorpara o que um modelo pode corrigir, com os valores válidos na mensagem;MCPErrorpara uma chave de API rejeitada; todo o resto continua sendo uma falha genérica.- Cada ferramenta é anotada. As ferramentas de leitura são somente leitura e de mundo fechado.
issue_refundé aditiva, de mundo fechado e idempotente, com a verificação de execução única do servidor por trás da dica. - Anotações de outros servidores não são confiáveis, e o consentimento nunca depende somente delas.
- As cotações ficam na memória do servidor, o que vale para um único processo stdio. Réplicas precisam de um armazenamento compartilhado.
Este capítulo, nesta edição
Edição 2026.11.14Exemplos aprovados em 19 de nov de 20267 de 7 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.14.