Un agente es tan capaz como las herramientas que puede llamar. Los equipos se pasan semanas ajustando el prompt de sistema y después exponen su backend al modelo como treinta envoltorios finos sobre endpoints REST, y se preguntan por qué el agente elige el equivocado, pasa IDs mal formados y se ahoga en respuestas JSON de 50 kilobytes. Las herramientas para agentes son un nuevo tipo de API cuyo consumidor es un modelo de lenguaje. Requieren decisiones de diseño distintas a las de las APIs para programadores. Esta guía reúne esas decisiones, basadas en las recomendaciones de los proveedores, la investigación y lo que he visto funcionar.

Por qué las herramientas para agentes no son como las APIs

Un desarrollador que lee la documentación de tu API puede pasar una hora entendiéndola, escribir el código una vez y llamar a la API millones de veces de forma determinista. Un modelo lee las definiciones de herramientas en cada petición, debe decidir en el momento qué herramienta llamar y con qué argumentos, y paga cada token de entrada y salida en su limitada ventana de contexto.

La investigación sobre SWE-agent mostró que el diseño de la interfaz agente-ordenador —qué comandos existen, cómo se formatea la salida, cómo se informan los errores— cambia el rendimiento del agente tanto como la elección del modelo (Yang et al., 2024). La guía de ingeniería de Anthropic sobre cómo escribir herramientas para agentes llega a la misma conclusión desde la experiencia en producción: el diseño de herramientas es una de las cosas que más rendimiento da mejorar.

Principio 1: diseña para tareas, no para endpoints

Una correspondencia uno a uno entre endpoints REST y herramientas es el error más común. Si responder a "¿cuándo llega mi pedido?" requiere get_customer, list_orders, get_order, get_shipment y get_carrier_status, el agente tiene que encadenar cinco llamadas correctamente, y cada una cuesta latencia y contexto.

En su lugar, diseña las herramientas en torno a lo que el agente necesita conseguir:

Herramientas con forma de endpoint Herramienta con forma de tarea
list_orders, get_order, get_shipment, get_tracking get_order_status(order_ref) que devuelve estado, artículos, transportista y fecha estimada
list_users, list_events, create_event schedule_meeting(attendees, duration, window) que busca huecos libres y reserva
read_logs(service, from, to) que lo devuelve todo search_logs(service, query, time_range, max_results)

Las herramientas con forma de tarea consolidan las operaciones habituales de varios pasos, reducen el número de decisiones que tiene que tomar el modelo y mantienen limpio el contexto. Conserva un pequeño número de herramientas de bajo nivel para los casos inusuales.

Principio 2: los nombres y las descripciones son prompts

El modelo elige las herramientas por sus nombres y descripciones. Escríbelas como le explicarías la herramienta a un compañero nuevo:

{
  "name": "search_customer_tickets",
  "description": "Search support tickets for ONE customer. Use this when the user asks about their previous requests or a problem they reported before. Returns at most 10 tickets, newest first, each with id, subject, status and a 200-character summary. To read the full conversation of a ticket, call get_ticket_thread with its id. Does not search other customers' tickets.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {"type": "string", "description": "Internal customer id like CUS-48213. Get it from the session context, never ask the user for it."},
      "query": {"type": "string", "description": "Keywords in Spanish or English. Leave empty to list recent tickets."},
      "status": {"type": "string", "enum": ["open", "closed", "any"], "default": "any"}
    },
    "required": ["customer_id"]
  }
}

Las buenas descripciones dicen cuándo usar la herramienta, qué devuelve, qué no hace y cómo se relaciona con otras herramientas. Las descripciones de los parámetros especifican los formatos y de dónde salen los valores. Agrupar las herramientas relacionadas con un prefijo común (crm_search_contacts, crm_get_deal) ayuda cuando un agente tiene muchas herramientas de distintos sistemas.

Principio 3: devuelve lo que el agente necesita, no todo lo que tienes

La salida de una herramienta va directamente al contexto del modelo. Una fila de base de datos en bruto con 60 columnas, UUIDs internos y metadatos anidados desperdicia tokens y distrae al modelo.

  • Devuelve campos con mucha señal. Nombres legibles mejor que IDs opacos cuando sea posible; incluye los IDs solo cuando el agente los necesite para llamadas posteriores.
  • Ofrece una opción de nivel de detalle (response_format: "concise" | "detailed") para que el agente pueda pedir más cuando lo necesite.
  • Pagina y trunca con señales claras: "Mostrando 10 de 248 resultados. Acota la consulta o pide la página 2".
  • Da formato pensando en la lectura. Tanto el texto estructurado breve como el JSON compacto funcionan; la coherencia importa más que el formato.
  • Limita los tamaños en el código. Una herramienta que de vez en cuando puede devolver 2 MB acabará rompiendo una sesión.

El contexto es el recurso más escaso de un agente, como se explica en context engineering.

Principio 4: haz que los errores sean accionables

Cuando una herramienta falla, el mensaje de error es la única pista del modelo para recuperarse. Compara:

  • Error 400: el agente repetirá la misma llamada o se rendirá.
  • Fecha no válida "15.09.2026": usa el formato ISO AAAA-MM-DD, p. ej. 2026-09-15.: el agente corrige el argumento y lo consigue.
  • Cliente CUS-482 no encontrado. Los IDs de cliente tienen 5 dígitos tras "CUS-"; usa search_customers por nombre o correo para encontrar el ID correcto.: el agente sabe exactamente qué hacer a continuación.

Devuelve los errores como resultados de la herramienta en lugar de lanzar excepciones que terminen el bucle. Distingue los errores que el modelo puede arreglar (argumentos erróneos) de los que no (servicio caído), y dilo: "El servicio de facturación no está disponible. Dile al usuario que lo intente más tarde; no reintentes".

Principio 5: haz que los argumentos sean difíciles de equivocar

  • Usa enums para los conjuntos cerrados.
  • Acepta formatos naturales cuando sea barato normalizarlos en código (fechas, teléfonos, importes con o sin moneda).
  • Evita parámetros que el modelo tenga que calcular, como offsets, marcas de tiempo Unix o códigos internos. Deja que la herramienta traduzca "los últimos 7 días" o un nombre legible.
  • Valida de forma estricta y explica los fallos, como arriba.
  • Usa los modos de esquema estricto cuando el proveedor los admita, para que los argumentos cumplan siempre el esquema; consulta salidas estructuradas.

Principio 6: los permisos viven en la herramienta, no en el prompt

Tarde o temprano el modelo llamará a una herramienta de una forma que no pretendías, por un malentendido o por un prompt injection en el contenido que leyó. La seguridad debe imponerse en el código de la herramienta:

  • Ejecuta cada llamada con los permisos del usuario final, comprobados por el backend.
  • Separa las herramientas de lectura de las de escritura; da a las de escritura alcances estrechos y exige confirmación para las acciones con consecuencias.
  • Nunca aceptes la identidad del modelo. Toma el customer_id de la sesión autenticada, no de los argumentos de la herramienta, cuando determine qué datos son visibles.
  • Limita la frecuencia y registra cada llamada con usuario, argumentos y resultado.

El modelo de seguridad completo se describe en seguridad de agentes de IA y prompt injection.

Principio 7: mantén el conjunto de herramientas pequeño y diferenciado

Cada herramienta adicional añade tokens a cada petición y otra opción que el modelo puede confundir. Las herramientas que se solapan —search_docs, find_documents y query_kb— son una fuente segura de elecciones erróneas. Apunta a un conjunto pequeño de herramientas diferenciadas por agente; si necesitas decenas, reparte las responsabilidades entre agentes especializados o carga las definiciones de herramientas de forma dinámica según la tarea. Algunas plataformas admiten la búsqueda de herramientas, en la que el modelo descubre bajo demanda las herramientas poco usadas en lugar de ver todas las definiciones desde el principio.

Exponer herramientas mediante MCP

Si varios agentes, IDEs o clientes de chat necesitan las mismas capacidades, implementa las herramientas una sola vez como un servidor Model Context Protocol. MCP estandariza el descubrimiento y la invocación de herramientas, de modo que las mismas herramientas de CRM o ERP funcionan en Claude, en asistentes del IDE y en tus propios agentes. Todos los principios de diseño anteriores siguen aplicándose: MCP es un transporte, no un diseño. Mi introducción orientada a negocio está en MCP para empresas, y un ejemplo con un ERP en integración de IA con Odoo.

Probar las herramientas con evals

La calidad de las herramientas se puede medir. Construye un conjunto de evaluación de tareas realistas que requieran las herramientas, ejecuta el agente y mide:

Métrica Qué revela
Tasa de éxito de las tareas Utilidad global
Selección correcta de herramienta Nombres confusos o herramientas que se solapan
Tasa de errores en los argumentos Esquemas o formatos poco claros
Llamadas por tarea Faltan herramientas con forma de tarea, salidas pobres
Tokens por tarea Respuestas infladas
Recuperación tras errores Calidad de los mensajes de error

Después itera: lee las transcripciones en las que falló el agente, cambia descripciones, salidas o límites entre herramientas y vuelve a ejecutar. La guía de Anthropic recomienda dejar que un modelo analice las transcripciones fallidas y proponga mejoras en las herramientas, un bucle sorprendentemente eficaz. La metodología general de evaluación está en evals de LLM.

Una lista de comprobación para cada herramienta

  • Diseñada en torno a una tarea que el agente realiza de verdad
  • El nombre es específico; la descripción dice cuándo usarla, qué devuelve y qué no hace
  • Cada parámetro tiene una descripción con formato y origen
  • La salida contiene solo campos con mucha señal, con límites de tamaño y paginación
  • Los errores explican qué salió mal y qué hacer a continuación
  • Los permisos se imponen en el código y la identidad se toma de la sesión
  • Las acciones de escritura requieren confirmación cuando las consecuencias importan
  • Cubierta por tareas de evaluación; se siguen los errores de selección y de argumentos

Preguntas frecuentes

¿Cuántas herramientas puede manejar un agente? Los modelos actuales manejan decenas de herramientas bien diseñadas, pero tanto la precisión como el coste empeoran a medida que crece el conjunto. Empieza en pequeño y añade herramientas cuando los evals muestren la necesidad.

¿Las herramientas deberían devolver JSON o texto? Ambos funcionan. Elige según lo que facilite al modelo la lectura del contenido y mantén la coherencia dentro de un conjunto de herramientas.

¿Podemos generar las herramientas automáticamente a partir de nuestra especificación OpenAPI? Como punto de partida, sí. Después consolida los endpoints en herramientas con forma de tarea, reescribe las descripciones y recorta las respuestas: la versión generada rara vez es lo bastante buena.

¿Cómo versionamos las herramientas? Como las APIs: los cambios aditivos son seguros, los cambios incompatibles necesitan un nombre o una versión nuevos, y los evals deben ejecutarse con cada cambio.

Fuentes

  1. Anthropic (2025). Writing effective tools for agents — with agents.
  2. Yang et al. (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering.
  3. Anthropic. Tool use with Claude.
  4. OpenAI. Function calling guide.
  5. Model Context Protocol.
  6. Patil et al. (2023). Gorilla: Large Language Model Connected with Massive APIs.