Uso de herramientas con Claude

El "tool use" (uso de herramientas) permite que Claude llame a funciones que tú defines o que Anthropic proporciona. Claude determina cuándo llamar a una herramienta según la solicitud del usuario y la descripción de la herramienta. Luego devuelve una llamada estructurada que tu aplicación ejecuta (herramientas de cliente) o que Anthropic ejecuta (herramientas de servidor).

Aquí tienes un ejemplo mínimo usando una herramienta de servidor, la herramienta de búsqueda web, que Anthropic ejecuta por ti:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude ejecuta la búsqueda en la infraestructura de Anthropic y devuelve los resultados citados en la misma respuesta. Para que Claude llame a una función que tú defines, pasa una herramienta con un input_schema y luego ejecuta la llamada cuando Claude devuelva un bloque tool_use. Cómo funciona el uso de herramientas muestra ese recorrido de ida y vuelta de principio a fin. Obtén más información sobre definir herramientas y manejar llamadas a herramientas.



Cómo funciona el uso de herramientas

Las herramientas se diferencian principalmente por dónde se ejecuta el código. Las herramientas de cliente (incluidas las herramientas definidas por el usuario y las herramientas con esquemas definidos por Anthropic, como bash y text_editor) se ejecutan en tu aplicación. Claude responde con stop_reason: "tool_use" y uno o más bloques tool_use. Tu código ejecuta la operación y devuelve un tool_result. Las herramientas de servidor (como web_search, web_fetch, code_execution y tool_search) se ejecutan en la infraestructura de Anthropic: ves los resultados directamente sin manejar la ejecución, a menos que Claude llame a la herramienta en el mismo grupo de llamadas a herramientas en paralelo que una de tus herramientas de cliente (consulta Razones de detención y respaldo).

Aquí está ese recorrido completo de ida y vuelta para una herramienta de cliente. La primera solicitud define una herramienta get_weather, y Claude responde la pregunta llamándola: la respuesta lleva un bloque tool_use, tu código ejecuta la consulta, y una segunda solicitud envía el resultado de vuelta en un bloque tool_result para que Claude pueda responder con la respuesta.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude responde con un bloque tool_use que indica la herramienta y sus argumentos.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # Pide como máximo una llamada a herramienta por turno.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Ejecuta la herramienta y luego devuelve el resultado en un bloque tool_result.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude usa el resultado para responder la pregunta original.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Manejar llamadas a herramientas cubre cada paso en detalle, incluido el formato de resultados y la señalización de errores; Uso de herramientas en paralelo cubre las respuestas que llaman a varias herramientas a la vez. Para evitar escribir este recorrido de ida y vuelta tú mismo, usa Tool Runner: los SDKs ejecutan tus herramientas y devuelven los resultados automáticamente.

Para el modelo conceptual completo, incluido el bucle agéntico y cuándo elegir cada enfoque, consulta Cómo funciona el uso de herramientas.

Para conectarte a servidores de Model Context Protocol (MCP), consulta el conector MCP. Para construir tu propio cliente MCP, consulta la guía de Model Context Protocol para construir un cliente MCP.



Cuándo Claude usa herramientas

Con el valor predeterminado de tool_choice de {"type": "auto"}, Claude determina en cada turno si llamar a una herramienta o responder directamente. Llama a una herramienta cuando la solicitud corresponde a la capacidad descrita de esa herramienta y la respuesta no está ya en el contexto. Responde directamente para conocimiento estable, tareas creativas y turnos conversacionales.

Este límite se puede dirigir a través de tu indicación del sistema. Si Claude no está llamando a las herramientas cuando lo esperas, una instrucción ligera como "Use the tools to investigate before responding." aumenta el uso de herramientas. Una forma más fuerte como "Always call a tool first before responding." lo impulsa aún más. Por el contrario, "Use your judgment about whether to call a tool or respond directly." mantiene el comportamiento de activación conservador.

Para requerir una llamada a herramienta en lugar de depender del prompting, configura tool_choice.

La página de cada herramienta de servidor describe su propio límite de activación con más detalle.



Elige una herramienta

Para las cadenas de type, versiones y encabezados beta, consulta la Referencia de herramientas.



Tus propias herramientas

Para las herramientas que defines, tú escribes el esquema y tu aplicación ejecuta cada llamada.



Herramientas de cliente con esquema de Anthropic

Anthropic publica el esquema y entrena a Claude con él. Tu aplicación sigue ejecutando cada llamada y devuelve el tool_result.



Herramientas de servidor

Las herramientas de servidor se ejecutan en la infraestructura de Anthropic, sin código de manejo en tu aplicación. Consulta Herramientas de servidor para conocer la mecánica que comparten.



Precios

Las solicitudes de uso de herramientas se cobran en función de:

1. El número total de tokens de entrada enviados al modelo (incluidos los del parámetro tools)
2. El número de tokens de salida generados
3. Para las herramientas del lado del servidor, precios adicionales basados en el uso (por ejemplo, la búsqueda web cobra por cada búsqueda realizada)

Las herramientas del lado del cliente tienen el mismo precio que cualquier otra solicitud a la API de Claude, aunque las herramientas del lado del servidor pueden generar cargos adicionales según su uso específico.

Los tokens adicionales del uso de herramientas provienen de:

• El parámetro tools en las solicitudes a la API (nombres, descripciones y esquemas de las herramientas)
• Bloques de contenido tool_use en las solicitudes y respuestas de la API
• Bloques de contenido tool_result en las solicitudes a la API

Cuando usas tools, la API también incluye automáticamente una indicación del sistema especial para el modelo que habilita el uso de herramientas. El número de tokens de uso de herramientas requeridos para cada modelo se indica en la siguiente tabla (sin incluir los tokens adicionales mencionados anteriormente). Ten en cuenta que la tabla asume que se proporciona al menos 1 herramienta. Si no se proporcionan tools, entonces una elección de herramienta de none usa 0 tokens adicionales de indicación del sistema.

Estos recuentos de tokens se suman a tus tokens normales de entrada y salida para calcular el costo total de una solicitud.

Consulta la tabla de Descripción general de modelos para ver los precios actuales por modelo.

Cuando envías un prompt de uso de herramientas, como cualquier otra solicitud de API, la respuesta incluye tanto el recuento de tokens de entrada como de salida en las métricas de usage reportadas.

Algunas herramientas de servidor agregan cargos basados en el uso además de los tokens: consulta la herramienta de búsqueda web y la herramienta de ejecución de código para conocer sus tarifas.



Próximos pasos