Tool use (function calling): cómo un modelo pide acciones
Tool use o function calling es el mecanismo con el que un modelo pide ejecutar una función de tu aplicación. El modelo decide cuándo; tu código la ejecuta.
¿Qué hace realmente el modelo?
Un modelo de lenguaje solo produce texto. No puede abrir un archivo ni consultar una base de datos. Lo que hace con tool use es producir una petición estructurada: “quiero llamar la herramienta buscar_pedido con este número”. Esa petición no hace nada hasta que tu código la recibe y la ejecuta.
Según la documentación de Claude, el modelo “determines when to call a tool based on the user’s request and the tool’s description” (decide cuándo llamar una herramienta según la petición del usuario y la descripción de la herramienta). Después devuelve la llamada, tu aplicación la ejecuta y el resultado vuelve al modelo en un mensaje aparte. Con ese resultado, el modelo responde.
Hay dos tipos de herramientas según dónde corre el código:
| Tipo | Quién la ejecuta | Ejemplos en la API de Claude |
|---|---|---|
| Herramientas de cliente | Tu aplicación | Las que tú defines, bash, text_editor |
| Herramientas de servidor | El proveedor | web_search, web_fetch, code_execution |
Tool use es la base de los agentes de IA: sin herramientas, el modelo solo habla; con ellas, puede actuar en un ciclo. Cuando las herramientas vienen de un servidor externo y no de tu propio código, el protocolo abierto para conectarlas es MCP.
¿Cómo se define una herramienta?
Una herramienta que tú defines tiene tres partes obligatorias:
- Nombre (
name). Corto, con verbo y sin ambigüedad:buscar_pedido, noprocesar. En la API de Claude solo admite letras, números, guion y guion bajo, hasta 128 caracteres. - Descripción (
description). Qué hace, cuándo usarla y cuándo no, qué significa cada parámetro y qué no devuelve. Anthropic la llama “by far the most important factor in tool performance” y recomienda al menos 3 o 4 frases. - Esquema de entrada (
input_schema). Un JSON Schema que dice qué parámetros existen, de qué tipo y cuáles son obligatorios.
Una cuarta parte es opcional: input_examples, una lista de entradas de ejemplo que deben cumplir el esquema. Sirve para herramientas con parámetros complejos o con formato delicado.
Compara dos descripciones para la misma herramienta. Floja: “Busca un pedido”. Útil: “Busca un pedido por su número y devuelve estado, fecha de envío y monto. Úsala cuando el cliente pregunte por un pedido concreto. No sirve para buscar por nombre del cliente. El número tiene el formato PED-000000.” La segunda le dice al modelo cuándo aplica, cuándo no y qué esperar.
Anthropic también recomienda agrupar operaciones parecidas en una sola herramienta con un parámetro accion, en lugar de tres casi iguales.
¿Qué ciclo sigue una llamada?
- Tu aplicación envía la conversación y la lista de herramientas.
- El modelo responde con un bloque
tool_useque trae unid, el nombre de la herramienta y los argumentos. - Tu código valida y ejecuta la función.
- Envías el resultado en un bloque
tool_resultcon el mismo identificador (tool_use_id). Si algo falló, lo marcas conis_error: true. - El modelo responde al usuario con ese resultado, o pide otra herramienta.
Ese ciclo se repite. Cada vuelta es un turno del loop de un agente.
Tú también controlas cuánta libertad tiene el modelo con el parámetro tool_choice: auto (el modelo decide; es el valor por defecto), any (debe usar alguna), tool (debe usar una concreta) y none (no puede usar ninguna). No todos los modelos admiten forzar una herramienta: revisa la documentación del modelo que uses.
¿Por qué le importa a un diseñador?
Porque las herramientas definen lo que la IA puede hacer dentro del producto, y eso es una decisión de diseño de interacción. Algunas preguntas que conviene hacer antes de construir:
- ¿Qué acciones puede disparar la IA sin que el usuario lo vea?
- ¿Qué pasa cuando la herramienta falla? El mensaje de error también es UX.
- ¿Qué nombre y descripción entiende la persona cuando ve la acción en pantalla?
- ¿Qué acciones necesitan aprobación antes de ejecutarse?
- ¿Qué herramienta no debería existir, aunque sea técnicamente posible?
Una herramienta mal descrita produce llamadas en el momento equivocado. Una herramienta con demasiados permisos produce daños difíciles de deshacer. Y el texto que devuelve una herramienta también es contenido: si viene de una página web, un correo o una API de terceros, Anthropic advierte que puede traer instrucciones escondidas que intenten desviar al modelo (inyección de prompt indirecta).
Prueba rápida: abre una herramienta que use tu producto o tu equipo y lee su nombre y su descripción como si fueras el modelo. ¿Sabrías cuándo usarla? ¿Sabrías qué parámetro falta si la llamada está incompleta? Si no, reescribe la descripción. Después pruébala con una petición que no debería activarla y comprueba que no lo hace.
¿Cuándo NO conviene usar herramientas?
- Cuando la respuesta sale de conocimiento general y no necesita datos actuales o del sistema.
- Cuando la acción es crítica y no hay paso de aprobación. Conviene que una persona confirme antes de ejecutar.
- Cuando una función determinista (una consulta SQL fija, un cálculo) resuelve el caso sin pasar por el modelo.
- Cuando solo necesitas una respuesta con forma fija y no una acción: para eso están las salidas estructuradas.
Anthropic explica que, con tool_choice en auto, el modelo decide en cada turno si llama una herramienta o responde directo, y que esa frontera se puede orientar con el system prompt. Orientar no es bloquear: para impedir algo siempre, usa un control técnico, como permisos o un hook. En Claude Code, por ejemplo, un hook PreToolUse puede bloquear una llamada antes de que se ejecute.
Ejemplo
Ejemplo ilustrativo: una herramienta de soporte tiene la función reembolsar_pedido con parámetros pedido_id y monto. El modelo la llama cuando el cliente lo pide. Un diseño cuidadoso no la deja ejecutar directo: la aplicación muestra al agente humano el monto y el pedido, y solo ejecuta tras confirmación. Si el monto supera un límite, la herramienta devuelve un tool_result con is_error: true y un texto claro: “El monto supera el límite de reembolso automático. El caso debe pasar a una persona.” El modelo usa ese texto para explicarle al cliente qué sigue.
¿Cómo se valida lo que pide el modelo?
El modelo puede pedir una herramienta con argumentos mal formados, fuera de rango o con valores que no existen. Tu código debe validar antes de ejecutar: tipos, rangos, identificadores reales y permisos de la persona detrás de la sesión.
La API de Claude tiene un modo estricto: con strict: true en la definición, las entradas de la herramienta siempre cumplen el esquema exacto. Eso no reemplaza la validación de negocio. El esquema puede decir que monto es un número; solo tu código sabe si ese pedido existe y si ese monto es razonable.
Si la validación falla, devuelve el error como resultado. La documentación de Anthropic recomienda mensajes instructivos en lugar de un genérico “failed”: qué salió mal y qué probar después, por ejemplo “Rate limit exceeded. Retry after 60 seconds.” Según la misma documentación, cuando falta un parámetro y se lo indicas en el error, Claude suele reintentar 2 o 3 veces con correcciones antes de disculparse con el usuario.
Errores comunes
- Descripciones vagas como “útil para cosas de pedidos”. El modelo no sabe cuándo usarla.
- Herramientas con un solo parámetro libre de texto, sin tipos ni restricciones.
- Muchas herramientas casi iguales que compiten entre sí por la misma petición.
- Confiar en la descripción o en el system prompt como única defensa frente a acciones peligrosas.
- Devolver errores genéricos. El modelo no sabe si reintentar, corregir o avisar al usuario.
- Tratar el resultado de una herramienta como texto confiable cuando viene de fuentes externas.
- Dar a una herramienta más permisos que los que necesita la tarea (ver sandboxing y permisos).