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-4-8",
    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. Definir herramientas y Manejar llamadas a herramientas cubren ese ciclo completo.



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 envía de vuelta 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 paralelas a herramientas que una de tus herramientas de cliente (consulta Razones de detención y alternativa).

Para ver 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", o MCP, consulta el conector MCP. Para crear tu propio cliente MCP, consulta la guía de Model Context Protocol sobre cómo crear un cliente MCP.



Cuándo usa Claude las herramientas

Con el tool_choice predeterminado 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 ajustar mediante 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 de las indicaciones, 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 type, versiones y encabezados beta, consulta la Referencia de herramientas.



Tus propias herramientas

Para las herramientas que tú defines, 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 devolviendo 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, mientras que 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 a continuación (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 los recuentos de tokens de entrada y 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