Tool use (function calling) es la capacidad que convierte a Claude de un generador de texto en un agente que puede interactuar con el mundo real. Con herramientas, Claude puede consultar APIs, leer bases de datos, ejecutar cálculos o llamar a cualquier función que le definas.

Cómo funciona el ciclo tool use

El flujo es un ciclo de 3 pasos:

  1. Envías a Claude una lista de herramientas disponibles con su descripción y schema
  2. Claude decide si necesita usar una herramienta y devuelve un tool_use block con los parámetros
  3. Ejecutas la herramienta, devuelves el resultado y Claude genera la respuesta final
import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Obtiene el tiempo actual para una ciudad",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Nombre de la ciudad"}
            },
            "required": ["city"]
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "¿Qué tiempo hace en Madrid?"}]
)

Procesando la respuesta de tool use

Claude puede devolver tool_use en el stop_reason. Tienes que manejar este caso:

if response.stop_reason == "tool_use":
    tool_block = next(b for b in response.content if b.type == "tool_use")
    tool_name = tool_block.name
    tool_input = tool_block.input

    # Ejecuta tu función real aquí
    result = call_your_function(tool_name, tool_input)

    # Devuelve el resultado a Claude
    final_response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "¿Qué tiempo hace en Madrid?"},
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": tool_block.id, "content": str(result)}
            ]}
        ]
    )

Múltiples herramientas y tool choice

Puedes definir varias herramientas y Claude elegirá la apropiada. Con tool_choice puedes forzar el uso de una herramienta específica o desactivar la selección automática.

# Forzar una herramienta específica
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[...]
)

Cuándo usar tool use vs prompt simple

Tool use añade latencia y complejidad. Úsalo cuando necesites datos externos en tiempo real, ejecutar acciones con efectos secundarios, o cuando el resultado depende de información que no está en el contexto. Para razonamiento puro o generación de texto, un prompt directo es más rápido y barato.