Tool Use (uso de herramientas)

Tool use es la funcionalidad de la API de Claude que le permite decidir cuándo y cómo invocar funciones externas que tú describes previamente. En lugar de limitarse a generar texto, Claude puede solicitar que ejecutes una búsqueda, una consulta a base de datos, un cálculo o una llamada a otra API, recibir el resultado y usarlo para responder. En inglés se le conoce también como function calling.

Cómo funciona

El flujo es un ciclo de peticiones entre tu código y Claude:

1. Defines una o varias herramientas en el parámetro tools de la petición. Cada herramienta lleva un nombre, una descripción y un esquema JSON de sus parámetros de entrada.
2. Envías el mensaje del usuario junto con esas definiciones. Claude analiza si necesita alguna herramienta para responder.
3. Si la necesita, en lugar de texto final devuelve un bloque tool_use con el nombre de la herramienta y los argumentos que ha inferido, con stop_reason: "tool_use".
4. Tu código ejecuta la función real (Claude no la ejecuta) y devuelve el resultado en un bloque tool_result dentro de un nuevo mensaje con rol user.
5. Claude integra ese resultado y genera la respuesta final, o pide otra herramienta si la tarea aún no está completa.

Un punto clave: Claude nunca ejecuta código por sí mismo. Solo decide qué herramienta usar y con qué argumentos. La ejecución, la seguridad y el control siguen estando en tu lado.

Por qué importa

Tool use es lo que convierte a Claude de un generador de texto en el cerebro de un agente. Le permite acceder a información actualizada que no está en su entrenamiento, actuar sobre sistemas reales (crear tickets, enviar correos, modificar registros) y encadenar varios pasos de razonamiento con datos verificables. Sin herramientas, Claude solo puede trabajar con lo que sabe y lo que hay en la ventana de contexto; con ellas, puede orquestar tareas de principio a fin.

Es también la base sobre la que se apoya el Model Context Protocol (MCP), que estandariza cómo se exponen herramientas y fuentes de datos para que sean reutilizables entre aplicaciones. Si quieres dar el salto hacia agentes e integraciones con MCP, entender bien el ciclo de tool use es el prerrequisito imprescindible.

Ejemplo de definición de herramienta

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

La calidad de la description es determinante: es lo que Claude lee para decidir cuándo usar la herramienta y cómo rellenar los argumentos. Una descripción vaga produce llamadas incorrectas u omitidas.

Errores comunes

• Creer que Claude ejecuta la función. No lo hace. Solo emite la intención; ejecutar y devolver el resultado es responsabilidad de tu backend.
• Descripciones pobres. Si el nombre o la descripción no dejan claro el propósito, Claude usará la herramienta cuando no debe o pasará argumentos erróneos.
• No cerrar el ciclo. Después de un tool_use hay que devolver siempre un tool_result; olvidarlo rompe la conversación.
• Confundirlo con MCP. Tool use es el mecanismo bruto de la API; MCP es un estándar construido encima para reutilizar y compartir herramientas.