Diseña herramientas que un modelo pueda usar

Unos 36 minutos de lectura, con 7 ejemplos en 10 secciones.

Edición 2026.11.14 Ejemplos verificados el 19 de nov de 2026 70 de 70 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.14. Lee el original

Al terminar este capítulo podrás convertir la API de la tienda en herramientas del Model Context Protocol cuyos nombres, descripciones, esquemas de entrada, resultados y errores un modelo pueda utilizar, y medir cómo un cambio en una descripción modifica la herramienta que el modelo elige. Lo que sigue vale para la revisión 2026-07-28 de la especificación y para el SDK de Python, mcp 2.3.0.

Cada herramienta de este capítulo existe para ayudar a un modelo a responder uno de los tickets de clientes de la tienda, y el servidor de la tienda, shop-support, tiene por ahora solo una: get_order_status, de Envuelve un endpoint como herramienta. Lo que MCP añade a una API le dio además un recurso y un prompt, pero una sola herramienta no puede responder a la mayoría de los tickets. Los clientes también preguntan qué pedido era cuál, cuánto sería un reembolso, que se les reembolse un pedido y si un producto está en stock.

Las herramientas de un servidor del Model Context Protocol (MCP) son la única parte de la tienda que un modelo ve. El modelo nunca lee el código de la tienda ni su API. Lee el nombre, la descripción y el esquema de entrada de cada herramienta, elige una y rellena sus argumentos. Después lee lo que se le devuelve, incluido cualquier error. Por eso una herramienta es una interfaz pensada para un lector que no puede hacer preguntas, y cada parte de su definición es un lugar donde ayudar a ese lector o confundirlo.

Este capítulo construye el conjunto completo de herramientas para esos tickets y pone a prueba cada decisión de diseño.

Esta parte aún no está traducida, así que está en inglés.

Shape tools around tasks, not endpoints

Último cambio en la edición 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 Superado
"""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())
Salidapython 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.

Escribe descripciones que el modelo lee

Último cambio en la edición 2026.11.11

Las herramientas de tarea de la sección anterior solo sirven si el modelo elige la correcta, y la elige a partir de lo que le muestra el host. El bucle del host del libro, lib.host, muestra al modelo el nombre, la descripción y el esquema de entrada de cada herramienta. La especificación llama a la descripción una "pista" que los clientes pueden usar "para mejorar la comprensión que el LLM tiene de las herramientas disponibles" (esquema, Tool.description).

La mayoría de las descripciones publicadas son deficientes. Un estudio de 856 herramientas de 103 servidores encontró que el 97.1 % tenía al menos un defecto, y que el 56 % no decía con claridad para qué sirve la herramienta (Hasan y otros, 2026). En una prueba controlada con dos herramientas de interfaces idénticas, editar solo la descripción de una de ellas le dio más de 10 veces el uso del original con dos de los modelos probados (Faghih y otros, 2025). Más largo no es automáticamente mejor. En el primer estudio, las descripciones reescritas por completo elevaron el éxito de la tarea una mediana de 5.85 puntos, pero añadieron un 67 % más de pasos y empeoraron 1 caso de cada 6.

Una descripción que ayuda dice cuatro cosas: qué hace la herramienta, cuándo usarla en lugar de su vecina, cómo son sus entradas y qué devuelve. En el SDK de Python, la descripción de una herramienta es el docstring de su función, salvo que pases description= al decorador (herramientas). En 3.12.15, el entorno de ejecución del libro, el SDK pasa el docstring tal cual (mcp/server/mcpserver/tools/base.py), así que un docstring de varias líneas envía al modelo sus saltos de línea y sangrías. El servidor de la tienda guarda sus descripciones en un solo diccionario, DESCRIPTIONS, y pasa cada una como description=.

El ejemplo muestra al modelo ocho tickets y las cinco herramientas de la tienda tres veces, con un conjunto distinto de descripciones cada vez. Solo cambian las descripciones.

  • El conjunto vago tiene una línea por herramienta, del tipo que escribe un generador de endpoints, como "Cotización de reembolso."
  • El conjunto borrador es el primer borrador de la tienda, escrito como docstrings.
  • El conjunto revisado es el segundo borrador de la tienda, escrito después de leer los resultados del borrador.

Los ocho se eligieron a mano de la cola de tickets de la tienda, no se tomaron al azar: dos preguntan qué pedidos tiene un cliente, dos dónde está un pedido, tres sobre reembolsos y uno sobre existencias. Ninguno lleva instrucciones inyectadas ni un ID de pedido mal escrito. Antes de ejecutarlo, predice cuántas primeras llamadas acertará el conjunto vago y cuántas el borrador.

El modelo es el mismo que usan todas las grabaciones de este libro: Qwen3-4B-Instruct-2507, ejecutado en la CPU con llama.cpp, tal como lo configuró Deja que un modelo elija la herramienta. El script recordings/description_choices.py hizo esta grabación, description-choices, muestreando una respuesta por ticket con temperatura 0.7 y una semilla fija. La puntuación mira solo la primera herramienta que llama el modelo, no sus argumentos. La primera herramienta correcta de un ticket es la que los datos de la tienda le etiquetan, con un cambio: issue_refund necesita un quote_id, así que una solicitud de reembolso empieza con 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 Superado
"""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())
Salidapython 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

El conjunto vago eligió la primera herramienta correcta en 5 of 8 tickets, y el borrador lo hizo en 5 of 8. Los nombres y parámetros por sí solos bastaron para los cuatro tickets de pedidos y el de existencias, así que los tres conjuntos eligieron la misma herramienta correcta en cada caso. La redacción más larga del borrador no ayudó con los tres tickets de reembolso, donde las elecciones diferían. El ticket T-0006, sobre un pedido que "llegó con la sartén esmaltada agrietada. ¿qué me pueden reembolsar?" (cita traducida; si se mantiene el original en inglés, dejarlo sin traducir), obtuvo get_order_status del conjunto vago y get_order_status del borrador.

El borrador decía qué hace quote_refund, pero no que hace innecesario consultar el pedido. La revisión lo dice en ambas herramientas. get_order_status envía las preguntas sobre reembolsos a quote_refund, y quote_refund pide que se llame primero porque "comprueba el pedido por sí misma". Sin embargo, la revisión cambió más que eso. Reescribió el inicio de la descripción de quote_refund y, pasada como description= en lugar de como docstring, eliminó los saltos de línea y sangrías del borrador. Con los tres cambios, el conjunto revisado eligió la primera herramienta correcta en 8 of 8 tickets. La prueba no muestra cuál de los cambios importó.

La revisión corrigió la elección de herramienta, pero no los argumentos: ninguna de las tres llamadas de reembolso habría funcionado. Para T-0006 el modelo envió el SKU KG-1031, el ejemplo de la propia descripción del parámetro sku, y ninguno de los tres SKU que envió estaba en su pedido. Informa de los fallos como resultados de herramienta muestra cómo el servidor de la tienda detecta ese error. La fecha de T-0013 fue incorrecta con los tres conjuntos, como muestra la siguiente sección.

Trata estos recuentos como una sola medición. Proceden de un modelo con una semilla, en ocho tickets elegidos a mano, y otra semilla podría cambiar algunas elecciones. La revisión se escribió después de leer los resultados sobre esos mismos ocho tickets, así que su puntuación está inflada. Mide con qué frecuencia se elige la herramienta correcta mide las elecciones sobre toda la cola de tickets, que es la prueba que decide.

Regla práctica: Escribe cada descripción en dos a cuatro frases: qué hace la herramienta, cuándo usarla en lugar de la que más se confunde con ella, cómo son sus entradas y qué devuelve. Pásala como description= en lugar de confiar en un docstring de varias líneas, para que el modelo lea exactamente el texto que escribiste. Después graba el modelo que vas a enviar eligiendo herramientas para tickets reales, lee las elecciones erróneas y cambia las descripciones a las que apuntan. Cambia una cosa por grabación cuando necesites saber qué cambio funcionó, y comprueba el resultado en tickets que no usaste para escribir el cambio.

Tipifica las entradas con JSON Schema

Último cambio en la edición 2026.11.11

Una descripción de la sección anterior le indica al modelo lo que una herramienta necesita, y un esquema de entrada hace que el servidor lo cumpla. Cada herramienta tiene un inputSchema, un objeto JSON Schema cuya raíz tiene "type": "object". En la revisión fijada puede aparecer cualquier palabra clave de JSON Schema 2020-12 (registro de cambios), incluidas oneOf, if, then, else y $ref (esquema, Tool.inputSchema). Un esquema sin el campo $schema se interpreta como 2020-12, y las implementaciones "MUST NOT" seguir automáticamente un $ref que apunte a una URI de red (protocolo base), así que, por defecto, un esquema no puede hacer que un cliente descargue nada.

El esquema cumple dos funciones. Muestra al modelo la forma de una llamada válida y permite al servidor rechazar una no válida antes de que se ejecute cualquier código de la herramienta. La especificación convierte la parte del servidor en un requisito: los servidores "MUST" validar todas las entradas de las herramientas (herramientas, "Consideraciones de seguridad").

El SDK de Python construye el esquema a partir de las anotaciones de tipo de la función, y Annotated[..., Field(...)] de pydantic añade restricciones a esas anotaciones (herramientas). El servidor de la tienda define sus tipos de ID una sola vez. OrderId es una cadena con pattern=r"^O-\d{4}$", y CustomerId y Sku funcionan igual. find_orders recibe status como Literal de los cinco estados de pedido, placed_since como date y limit como entero con ge=1, le=50. El esquema que el SDK construyó a partir de esas anotaciones se muestra primero. Después, find_orders se llama de tres maneras: con tres argumentos incorrectos a la vez, con un número enviado como cadena y con la fecha que el modelo registrado envió para el ticket T-0013 en Escribe descripciones que el modelo lee. Ese ticket pedía pedidos "desde el 12 jun".

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 Superado
"""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())
Salidapython 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

Cada anotación se convirtió en una palabra clave del esquema: pattern para el ID de cliente, enum para el estado, "format": "date" para la fecha, y minimum y maximum para el límite. La llamada con tres argumentos incorrectos devolvió un único resultado fallido, y su texto nombra cada argumento que falló, la regla que incumplió y el valor enviado. Un modelo puede corregir los tres en su siguiente llamada.

El SDK es más flexible que el esquema en un aspecto. El esquema dice que limit es un entero, pero la llamada con "5" tuvo éxito y devolvió 5 pedidos. Pydantic, que valida los argumentos, convierte por defecto una cadena numérica en entero. Aquí eso es inocuo. Cuando una cadena y un número deben seguir siendo distintos, declara el campo con Field(strict=True). Pydantic también descarta, sin error, cualquier argumento que el esquema no declare (mcp/server/mcpserver/utilities/func_metadata.py), algo en lo que se apoya Evita que el servidor actúe como un diputado confundido.

La fecha es el error que ningún esquema detecta. El "12 jun" del ticket no tiene año, y el modelo envió 2023-06-12, una fecha válida, tres años anterior al final de los datos de la tienda. La llamada pasó la validación y devolvió 5 pedidos, todos los pedidos del cliente, en lugar de los 1 realizados desde el 12 de junio del año de la tienda. El esquema comprueba la forma. El significado tiene que venir de otra parte, por ejemplo, de que el host incluya la fecha del ticket en el prompt, o de que la descripción indique cómo interpretar una fecha sin año.

La especificación no es coherente sobre adónde va un argumento rechazado. Su página de herramientas incluye la validación de entradas entre los errores de ejecución de herramientas, que se devuelven como resultado. Su referencia de esquema incluye "invalid tool arguments" bajo el código de error JSON-RPC -32602 (esquema, InvalidParamsError). El SDK sigue la página de herramientas, y este libro también. Los clientes "SHOULD" pasar los errores de ejecución al modelo, pero solo "MAY" pasar los errores de protocolo, que la especificación describe como "less likely to result in successful recovery" (herramientas, "Manejo de errores"). Un resultado es la vía que el modelo puede contar con leer.

Regla práctica: Tipa cada argumento de la forma más estricta que permita la API: un patrón para los ID, un enum para los valores fijos, límites para los conteos y un formato para las fechas. Deja que el SDK rechace las llamadas incorrectas antes de que se ejecute tu código, y devuelve todos los fallos de una vez. No confíes en que el esquema exprese el significado, porque una fecha válida puede ser la fecha equivocada. Comprueba dentro de la herramienta lo que el esquema no puede expresar, y di en la descripción cómo completar un valor que los tickets suelen dejar incompleto.

Esta parte aún no está traducida, así que está en inglés.

Return structured content with an output schema

Último cambio en la edición 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 Superado
"""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())
Salidapython 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.

Informa de los fallos como resultados de la herramienta

Último cambio en la edición 2026.11.11

La cotización de la sección anterior es el resultado cuando una llamada funciona. Cuando una llamada falla, la especificación le asigna uno de dos caminos (herramientas, "Manejo de errores"). Un error de protocolo es un error JSON-RPC, por ejemplo para una herramienta desconocida, una solicitud que no encaja con el esquema de tools/call, o un fallo del servidor. Un error de ejecución de la herramienta es un resultado ordinario con isError en true, por ejemplo un fallo de la API, una entrada no válida o una regla de negocio rota. Los errores de herramienta, como los llama el resto de este libro, según la especificación, "contienen retroalimentación accionable que los modelos de lenguaje pueden usar para autocorregirse", y los clientes "DEBERÍAN" pasarlos al modelo.

Como los clientes DEBERÍAN pasar los errores de ejecución al modelo y solo PUEDEN pasar los errores de protocolo (es opcional), el camino decide quién puede corregir el fallo. En el SDK de Python, lanzar ToolError produce un error de ejecución con tu mensaje. Lanzar MCPError produce un error de protocolo. Cualquier otra excepción cuenta como un fallo inesperado: el resultado dice solo "Error al ejecutar la herramienta" y el nombre de la herramienta, y la excepción queda en el registro del servidor (manejo de errores). La guía del SDK plantea la elección como una pregunta: ¿podría un modelo más inteligente haber evitado este fallo? Si es así, lanza ToolError; si no, lanza MCPError.

El servidor de la tienda sigue esa prueba. Un pedido inexistente, un pedido que no se puede reembolsar, un SKU que no está en el pedido y una cotización desconocida o caducada son todos ToolError, cada uno con un mensaje que indica qué hacer en su lugar. Un 401 de la API de la tienda significa que la clave del servidor es incorrecta, algo que ningún modelo puede corregir, así que el servidor lanza MCPError con el código de error interno de JSON-RPC. Cualquier otra cosa, como que la API esté caída, sigue siendo un bloqueo. Cinco llamadas fallan a propósito, enumeradas en el orden en que las hace el código:

  1. la llamada registrada del ticket T-0006 de las descripciones revisadas en Escribe descripciones que el modelo lea, con su SKU inventado;
  2. issue_refund con una cotización que el servidor nunca emitió;
  3. una herramienta que no existe;
  4. una llamada a un servidor iniciado con la clave incorrecta;
  5. una llamada después de que la API de la tienda haya dejado de funcionar.
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 Superado
"""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())
Salidapython 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

El SKU inventado volvió como error de ejecución, y su texto le da al modelo lo que le faltaba: "Error executing tool quote_refund: Order O-2289 has no line for KG-1031. Its SKUs are KG-1043." Un modelo que lea eso puede volver a llamar con el SKU correcto. El mensaje de la cotización desconocida funciona de la misma forma: "Error executing tool issue_refund: There is no quote Q-0000000000. Call quote_refund for the order to get a quote_id."

La herramienta desconocida muestra una desviación respecto de la especificación. El ejemplo de la especificación responde a una herramienta desconocida con el error JSON-RPC -32602, pero el servidor del SDK devuelve un error de ejecución (mcp/server/mcpserver/tools/tool_manager.py). El resultado se marca como error, y su texto es "Unknown tool: refund_order". Para un modelo, esa respuesta es más útil, porque muestra que el nombre era incorrecto. Un host que cuente los errores de protocolo para detectar un modelo confundido no los verá, así que cuenta también los errores de ejecución.

La clave incorrecta tomó el otro camino. El cliente lanzó MCPError, y el ejemplo lo capturó como el error JSON-RPC -32603, con el mensaje "The shop's API rejected this server's key. The server needs reconfiguring." El código del host lo ve, y el modelo solo lo ve si el host se lo pasa. Cuando la API estaba caída, el modelo recibió solo "Error executing tool get_order_status", y la excepción quedó en el registro del servidor (manejo de errores).

Un error más se salta ambos caminos: una herramienta que devuelve un mensaje de error como cadena ordinaria. El SDK envía una cadena devuelta con isError en false, así que el modelo lee el error como una respuesta exitosa (manejo de errores). Lanza una excepción en su lugar.

Regla práctica: Lanza ToolError para cada fallo que un modelo podría corregir, con un mensaje que indique qué estaba mal y qué enviar en su lugar, incluidos los valores válidos cuando sean pocos. Lanza MCPError solo para fallos que ningún modelo puede corregir, como la configuración, y deja que las excepciones inesperadas sigan siendo genéricas para que los detalles internos permanezcan en el servidor. Nunca devuelvas un error como cadena simple.

Esta parte aún no está traducida, así que está en inglés.

Mark what a tool changes with annotations

Último cambio en la edición 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 Superado
"""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())
Salidapython 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.

Trata las anotaciones como pistas, no como garantías

Nada en el protocolo verifica una anotación contra lo que hace la herramienta. La especificación dice que las anotaciones "no están garantizadas para ofrecer una descripción fiel del comportamiento de la herramienta", y que los clientes "DEBEN" considerarlas no confiables a menos que provengan de servidores de confianza (esquema, ToolAnnotations; herramientas). Un servidor que marca una herramienta de reembolso como de solo lectura burla a cualquier host que le crea. Detecta descripciones de herramientas envenenadas muestra un servidor cuyas definiciones de herramientas mienten a propósito.

Para el autor del servidor, una pista es una promesa que el código tiene que cumplir. El issue_refund de la tienda es idempotente porque el almacén de cotizaciones lo garantiza, no porque lo diga la anotación. Si un reinicio hiciera perder el almacén, una llamada reintentada recibiría "No existe ninguna cotización" en lugar de un segundo reembolso, lo cual sigue siendo seguro. Mantén la comprobación en el servidor y trata la anotación como una descripción de ella.

Regla práctica: Anota cada herramienta, porque omitir las pistas indica a un host prudente que debe suponer lo peor. Marca una herramienta como idempotente solo cuando el servidor lo garantice, y mantén los reembolsos, los pagos y cualquier otra operación que deba ocurrir una sola vez detrás de una comprobación en el servidor. Como host, usa las anotaciones de un servidor de confianza para decidir qué mostrar al usuario, nunca como permiso para omitir el consentimiento (Pide consentimiento antes de los efectos secundarios), y trata las anotaciones de cualquier otro servidor como afirmaciones no verificadas.

Mantén corta la lista de herramientas

Último cambio en la edición 2026.11.11

El host coloca cada herramienta de las secciones anteriores, con su descripción y su esquema de entrada, en el prompt del modelo en cada turno, y el modelo lee la lista completa antes de elegir. Más herramientas cuestan más tokens y además dificultan la elección. En una prueba con servidores MCP, recuperar solo las herramientas relevantes para una solicitud más que triplicó la precisión de selección, pasando de 13.62 % a 43.13 % (Gan and Sun, 2025). En dispositivos de borde, ofrecer a modelos pequeños menos herramientas aumentó su tasa de éxito en la llamada a funciones y redujo el tiempo de ejecución hasta en un 70 % (Paramanayakam and others, 2025). Ambos son estudios individuales con sus propias configuraciones, así que léelos como la dirección del efecto, no como cifras para la tienda.

El costo es más fácil de medir que de adivinar. Cuando se ejecutó el script de grabación, también contó, con el tokenizador del modelo de grabación, cuántos tokens ocupa cada herramienta en el prompt del host. La comprobación suma esos recuentos para las herramientas revisadas, las vagas de Escribe descripciones que el modelo lea y las herramientas de endpoint, y mide sus bytes. Se niega a ejecutarse si una herramienta ha cambiado desde que se contaron sus tokens.

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 Superado
"""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())
Salidapython 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

La mayor parte del costo está en los esquemas. Las cinco herramientas revisadas de la tienda ocupan 970 tokens en el prompt, frente a 136 para el resto de las instrucciones del host. Con descripciones vagas ocupan 620, así que las descripciones revisadas representan cerca de un tercio del costo de la lista. Las herramientas de endpoint ocupan 288: descripciones de una línea y esquemas sin patrones, enumeraciones ni descripciones propias. Los esquemas revisados son los mismos que detectaron los argumentos incorrectos en Tipifica las entradas con JSON Schema. El resultado completo de tools/list es todavía mayor, porque también incluye esquemas de salida, títulos y anotaciones que el prompt del host omite, como muestran los recuentos de bytes de la salida.

Con unos 194 tokens por herramienta, 20 herramientas como estas ocuparían unos 3880 tokens antes de que el modelo lea el ticket: casi todo el contexto de 4096 tokens con el que se ejecutan las grabaciones. Esa cifra es un cálculo, no una medición, y las herramientas reales varían de tamaño. Una lista más corta también reduce la probabilidad de que dos descripciones se solapen, que fue el problema del borrador con get_order_status y quote_refund (Escribe descripciones que el modelo lea).

Un servidor mantiene corta su lista si atiende a una sola audiencia. El servidor de la tienda atiende tickets de soporte, así que el recuento de existencias no está en él. En la revisión fijada, un servidor no puede recortar su lista para una sola conexión, aunque la lista puede variar según la autorización que presente una solicitud, y llega en un orden fijo (Almacena en caché los resultados de la lista). Esa sección cubre las indicaciones de caché del resultado, y Limita las herramientas según lo que permita el token muestra una lista que varía según el token.

Regla práctica: Asigna a cada servidor una sola audiencia y las pocas herramientas que necesitan las tareas de esa audiencia, y mide cuánto cuesta la lista en el prompt de tu host. Dedica los tokens a los esquemas y a la frase que separa dos herramientas que un modelo podría confundir, y elimina el texto de descripción que repita el esquema. Cuando un host necesite más herramientas de las que su modelo puede elegir bien, reparte las herramientas entre varios servidores y conecta solo los servidores que necesite una conversación, en lugar de hacer que la lista de un servidor dependa de la conexión.

Qué sale mal en producción

Último cambio en la edición 2026.11.11

El servidor de la tienda funciona con ocho tickets en una sola máquina. A lo largo de una cola completa de tickets y de un despliegue real, el diseño de herramientas falla de algunas formas reconocibles.

Dos herramientas que un modelo no puede distinguir. Los borradores de descripciones en Escribe descripciones que el modelo lea hacen que el modelo consulte pedidos que debería haber citado. En producción, la señal es una herramienta que se llama mucho más o mucho menos que los tickets a los que sirve, o dos herramientas llamadas una tras otra cuando bastaría con una. Cuenta las elecciones de herramienta frente a tickets etiquetados (Mide con qué frecuencia se elige la herramienta correcta) y corrige la frase que separa las dos herramientas.

Valores de ejemplo que el modelo envía como si fueran reales. En uno de los tres tickets de reembolso, el modelo envió el SKU de ejemplo de la descripción del parámetro sku como si el cliente lo hubiera escrito. KG-1031 es un producto real, así que sin la comprobación de que el SKU está en el pedido, la herramienta habría citado el producto equivocado. Las descripciones de la tienda conservan sus IDs de ejemplo reales solo porque la grabación se hizo con ellos. La señal es un valor de ejemplo que aparece en los argumentos mucho más a menudo de lo que explica el tráfico real. Conserva comprobaciones que vinculen cada argumento con el registro al que pertenece, y elige ejemplos que no puedan ser reales, como IDs fuera del rango en uso.

Un esquema de salida que se desvía del código. El cliente del SDK valida cada resultado contra el esquema de salida que almacenó en caché a partir de tools/list, y lanza RuntimeError cuando no coinciden (mcp/client/session.py). Un servidor publicado con un campo eliminado o modificado, bajo un cliente que tenía en caché la lista antigua, hace fallar cada llamada a esa herramienta. Verás RuntimeError: Invalid structured content en el host tras una publicación del servidor. Trata los esquemas de salida como un contrato y pruébalos (Comprueba los esquemas como un contrato).

Caídas que el modelo no puede leer. Cada excepción que no sea un ToolError ni un MCPError llega al modelo como "Error executing tool" y nada más. Busca un modelo que reintente la misma llamada, o que se rinda, sin ninguna razón en la conversación. Lee el error estándar del servidor y convierte cada fallo que un modelo podría corregir en un ToolError.

Identificadores que mueren con el proceso. Las cotizaciones de la tienda viven en la memoria del servidor. Un reinicio pierde todas las cotizaciones abiertas, y el modelo recibe "There is no quote" por una cotización que creó hace minutos. Varias réplicas detrás de una misma dirección pierden más, porque una cotización creada en una réplica es desconocida para la siguiente. Guarda los identificadores en almacenamiento compartido en cuanto el servidor funcione con más de un proceso (Ejecuta réplicas sin sesiones fijas).

Nombres de herramientas que chocan entre servidores. Un host conectado a dos servidores puede ver dos herramientas llamadas get_order_status. La especificación dice que los hosts "SHOULD" desambiguar, por ejemplo anteponiendo a cada nombre un identificador del servidor (tools, "Tool names"), y Asigna nombres a las herramientas entre servidores lo construye.

Datos personales en cabeceras. Un parámetro marcado como x-mcp-header tiene su valor copiado en una cabecera HTTP con Streamable HTTP, donde los proxies y los registros pueden verlo. La especificación dice que los servidores "SHOULD NOT" marcar de esa forma los parámetros sensibles, incluidos los datos personales (tools), así que nunca marques un ID de cliente ni un correo electrónico. Sirve con Streamable HTTP explica la cabecera.

Regla práctica: Antes de que las herramientas de la tienda pasen a producción, graba el modelo que vas a publicar eligiendo herramientas para una muestra etiquetada de tickets reales, comprueba que cada fallo que un modelo podría corregir llega como un ToolError con un mensaje útil, y pon cada esquema de salida bajo una prueba de contrato. Tras la publicación, vigila los recuentos de elección de herramienta, los valores de ejemplo en los argumentos y los RuntimeError en el host.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.11
  • Cinco herramientas de tarea, no una herramienta por endpoint: find_orders, get_order_status, quote_refund, issue_refund y check_stock, en lib.shop_tools. El reconteo de existencias queda fuera del servidor de soporte.
  • Los reembolsos se dividen en una cotización y una emisión. quote_refund calcula el importe y devuelve un quote_id válido durante 15 minutos; issue_refund solo acepta ese identificador.
  • El servidor confía en el customer_id del llamador, y un quote_id es aleatorio pero corto y no está vinculado a ningún cliente. Proteger las herramientas contra el uso indebido lo aborda tomando el usuario que actúa desde el token verificado, no desde un argumento.
  • Todavía no hay consentimiento. Dentro del límite de la política, issue_refund se ejecuta sin preguntar a una persona; el consentimiento del host llega en Pedir consentimiento antes de los efectos secundarios.
  • Las descripciones se pasan como description=, desde un único diccionario. Cada una dice qué hace la herramienta, cuándo usarla en lugar de su vecina, sus entradas y su resultado. Se revisaron una vez, frente a las elecciones registradas de un modelo en ocho tickets, y la ejecución acredita la revisión en su conjunto, no a ninguna frase en particular.
  • Cada argumento tiene un tipo restringido con Annotated[..., Field(...)]: patrones para los identificadores, una enumeración para el estado, límites para limit, una fecha para placed_since.
  • Cada herramienta devuelve un modelo pydantic, así que el SDK publica un esquema de salida y envía contenido estructurado sin envoltorio {"result": ...}.
  • Los argumentos rechazados se devuelven como errores de ejecución, tal como lo establecen la página de herramientas de la especificación y el SDK, para que el modelo pueda leerlos y corregir su llamada.
  • ToolError para lo que un modelo puede corregir, con los valores válidos en el mensaje; MCPError para una clave de API rechazada; todo lo demás sigue siendo un fallo genérico.
  • Cada herramienta está anotada. Las herramientas de lectura son de solo lectura y de mundo cerrado. issue_refund es aditiva, de mundo cerrado e idempotente, con la verificación de una sola vez del servidor detrás de la indicación.
  • Las anotaciones de otros servidores no son de confianza, y el consentimiento nunca depende solo de ellas.
  • Las cotizaciones viven en la memoria del servidor, lo cual vale para un único proceso stdio. Las réplicas necesitan un almacén compartido.

Este capítulo, en esta edición

Edición 2026.11.14Ejemplos verificados el 19 de nov de 2026Superan la prueba 7 de 7 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.14.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 3 de 12: Diseña herramientas que un modelo pueda usar

  1. Shape tools around tasks, not endpoints
  2. Escribe descripciones que el modelo lee
  3. Tipifica las entradas con JSON Schema
  4. Return structured content with an output schema
  5. Informa de los fallos como resultados de la herramienta
  6. Mark what a tool changes with annotations
  7. Trata las anotaciones como pistas, no como garantías
  8. Mantén corta la lista de herramientas
  9. Qué sale mal en producción
  10. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos