Tool use: herramientas que Claude elige y usa bien

Quieres que un asistente de compras consulte el estado de un pedido en SAP y, si hace falta, prepare una reclamación al proveedor. Claude no puede entrar en tu sistema. Lo que sí puede es pedirte que ejecutes una función con unos argumentos concretos. Tu código decide si la ejecuta, con qué permisos y qué le devuelve.

Ese contrato es el tool use (o function calling), y es la pieza sobre la que se construye todo lo demás: agentes, MCP, Claude Code. En el examen aparece en el dominio 8 (herramientas y MCP, un 10,6 %), pero también en preguntas de agentes, seguridad y coste.

Quién ejecuta qué

La documentación clasifica las herramientas por dónde se ejecuta el código, y esa es la distinción que más se pregunta:

Una regla práctica de la propia documentación: si estás escribiendo una expresión regular para sacar una decisión de un texto libre, esa decisión debería haber sido una llamada a herramienta.

El ciclo tool_use y tool_result

Recorre una vuelta completa con una herramienta de cliente:

En código, el bucle manual cabe en pocas líneas:

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "sap_consultar_pedido_compra",
    "description": (
        "Devuelve el estado de un pedido de compra de SAP S/4HANA: proveedor, posiciones, "
        "cantidades recibidas y fecha de entrega prevista. Úsala cuando el usuario pregunte por "
        "un pedido concreto y dé su número. No sirve para buscar pedidos por proveedor ni por fecha. "
        "Solo lee datos: no modifica nada."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "numero_pedido": {"type": "string", "description": "Número de pedido de 10 dígitos, por ejemplo 4500012345"}
        },
        "required": ["numero_pedido"],
        "additionalProperties": False,
    },
    "strict": True,
}]

messages = [{"role": "user", "content": "¿Ha llegado ya el material del pedido 4500012345?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5-5", max_tokens=4096, tools=tools, messages=messages
    )
    messages.append({"role": "assistant", "content": response.content})  # tal cual, con thinking
    if response.stop_reason != "tool_use":
        break

    resultados = []
    for block in response.content:
        if block.type != "tool_use":
            continue
        try:
            salida = ejecutar_herramienta(block.name, block.input)  # tu código, tus permisos
            resultados.append({"type": "tool_result", "tool_use_id": block.id, "content": salida})
        except PedidoNoEncontrado:
            resultados.append({
                "type": "tool_result", "tool_use_id": block.id, "is_error": True,
                "content": "No existe ese pedido. Pide al usuario que confirme los 10 dígitos.",
            })
    messages.append({"role": "user", "content": resultados})

print("".join(b.text for b in response.content if b.type == "text"))

Tres reglas de formato que dan un 400 si las incumples: el tool_result va justo después del tool_use que responde, sin mensajes en medio; dentro del mensaje user, los tool_result van primero y cualquier texto después; y cada tool_use necesita su resultado.

Si no quieres escribir el bucle, los SDK de Python y TypeScript traen el Tool Runner (en beta): decoras una función con @beta_tool, el SDK deduce el esquema de los tipos y el docstring, y client.beta.messages.tool_runner(...) ejecuta las herramientas y reenvía los resultados por ti.

Herramientas que Claude elige bien

La documentación es tajante: la descripción es, con diferencia, el factor que más influye en el rendimiento de una herramienta. Compara:

name: get_data
description: Gets data from SAP.
input_schema: { id: string }

Las buenas prácticas oficiales, resumidas:

• Descripciones largas y concretas: al menos tres o cuatro frases. Qué hace, cuándo usarla y cuándo no, qué significa cada parámetro, qué no devuelve.
• input_examples para herramientas con entradas complejas o formatos delicados. Cada ejemplo debe cumplir el esquema, o la API devuelve 400.
• Menos herramientas y más capaces: mejor una herramienta con un parámetro action que tres casi iguales (create_pr, review_pr, merge_pr). Menos ambigüedad al elegir.
• Espacios de nombres con prefijo de servicio (sap_…, slack_…) cuando crece el catálogo.
• Respuestas con señal: identificadores estables y solo los campos útiles. Un volcado de 300 columnas gasta contexto y confunde.
• strict: true para que los argumentos cumplan siempre el esquema. Necesita additionalProperties: false en cada objeto.

Sobre tool_choice: tiene cuatro modos (auto, any, tool y none). Pero Opus 5.5, Sonnet 5.5 y Fable 5.1 no admiten forzar una herramienta: any y tool devuelven 400. La alternativa documentada es auto con strict: true y decir en el prompt cuándo usarla, o structured outputs si lo que quieres es una respuesta con forma fija. Para evitar llamadas en paralelo existe disable_parallel_tool_use: true.

Errores, aprobaciones y contenido no fiable

Errores. Si tu herramienta falla, devuelve el error en el tool_result con "is_error": true y un mensaje que sirva para recuperarse: no «failed», sino qué pasó y qué probar («límite de tasa, reintenta en 60 segundos»). Ante una llamada inválida, Claude suele corregir y reintentar un par de veces antes de rendirse. Con las herramientas de servidor no gestionas is_error: la API lo resuelve.

Aprobaciones. El examen habla de «patrones de aprobación». El más útil: separa las herramientas de lectura de las de escritura, y para las que tienen efectos irreversibles (crear un pedido, enviar un correo, borrar) pon una confirmación humana en tu código antes de ejecutar. Claude propone; tu aplicación enseña la propuesta y ejecuta solo si alguien la aprueba. Y el ejecutor usa credenciales con el mínimo privilegio necesario, no las de un administrador.

Contenido no fiable. Los resultados de herramientas traen texto que no controlas: páginas web, correos, campos libres de un ERP. La documentación recomienda mantenerlo dentro de los bloques tool_result y no copiarlo al system ni a texto del usuario, porque puede contener instrucciones inyectadas. Y, sobre todo, que una instrucción inyectada no pueda disparar una acción sensible sin pasar por tu control.

Herramienta integrada, propia, Skill o MCP

El subdominio de «agentic customization» (4,1 %) pregunta cuál elegir en cada caso. Esta tabla resume el criterio:

Fíjate en la última fila: una Skill no da acceso a ningún sistema, da saber hacer. Y una trampa habitual es pensar que una herramienta integrada puede llegar a tu API interna: no puede. Para eso está la herramienta propia o el servidor MCP, que vemos en la siguiente lección.

Un detalle de coste: las herramientas no salen gratis. Sus definiciones cuentan como tokens de entrada en cada petición, y activar tools añade además un system prompt interno (en Opus 5.5, 286 tokens). Con catálogos grandes, la herramienta tool search carga las definiciones bajo demanda.

Para el examen

Siguiente parada

Próxima lección: MCP para desarrolladores. Qué es un servidor MCP, sus primitivas, cómo construir uno en Python y conectarlo a Claude Code, al Agent SDK y a la API, sin filtrar credenciales.