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 decide cuándo llamar a una herramienta basándose en la solicitud del usuario y la descripción de la herramienta, y luego devuelve una llamada estructurada que tu aplicación ejecuta (herramientas de cliente) o que Anthropic ejecuta (herramientas de servidor).

Aquí tienes el ejemplo más simple usando una herramienta de servidor, donde Anthropic se encarga de la ejecución:

import anthropic

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)

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 esquema de 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 tú envías de vuelta un tool_result. Las herramientas de servidor (web_search, code_execution, web_fetch, tool_search) se ejecutan en la infraestructura de Anthropic: ves los resultados directamente sin tener que gestionar la ejecución.

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 MCP, consulta el conector MCP. Para crear tu propio cliente MCP, consulta modelcontextprotocol.io.

El acceso a herramientas es una de las primitivas de mayor impacto que puedes darle a un agente. En benchmarks como LAB-Bench FigQA (interpretación de figuras científicas) y SWE-bench (ingeniería de software del mundo real), añadir incluso herramientas básicas produce mejoras de capacidad desproporcionadas, a menudo superando los niveles de referencia de expertos humanos.

Cuándo usa Claude las herramientas

Con el valor predeterminado de tool_choice de {"type": "auto"}, Claude decide 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 cuando se trata de conocimiento estable, tareas creativas y turnos conversacionales.

Este límite se puede orientar mediante tu indicación del sistema. Si Claude no está llamando a herramientas cuando lo esperas, una instrucción ligera como "Use the tools to investigate before responding." aumenta de forma medible 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 un comportamiento de activación conservador.

Para una garantía firme en lugar de un empujón, usa tool_choice.

La página de cada herramienta de servidor describe su propio límite de activación con más detalle. Consulta por ejemplo la herramienta de búsqueda web o la herramienta de ejecución de código.

Ejemplos de uso de herramientas

Para un recorrido práctico completo, consulta el tutorial. Para ejemplos de referencia de conceptos individuales, consulta Definir herramientas y Gestionar llamadas a herramientas.

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 se 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 resumen de modelos para ver los precios actuales por modelo.

Cuando envías un prompt de uso de herramientas, al igual que cualquier otra solicitud de API, la respuesta mostrará los recuentos de tokens de entrada y salida como parte de las métricas de usage reportadas.

Próximos pasos

Elige tu camino