Blog
#0135 min de lectura

Herramientas para agentes de IA: diséñalas como si fueran para alguien nuevo en el equipo

Las herramientas son la forma en que un agente de IA actúa sobre tus sistemas, y la parte que más cambia sus resultados. Cómo elegirlas, nombrarlas, describirlas y hacer que sea difícil usarlas mal.

Cuando un agente de IA falla, lo primero que se revisa es el prompt. Muchas veces el problema está en otro lado: en las herramientas que le diste. Una herramienta con un nombre ambiguo, una descripción de una línea o una respuesta de diez mil registros confunde a un modelo igual que confundiría a una persona nueva en tu equipo.

Anthropic lo resume en una idea que me gusta: tus herramientas son la interfaz entre el agente y tu sistema, y merecen el mismo cuidado que una interfaz para personas (Building effective agents). En su sistema de investigación, solo reescribir las descripciones de las herramientas redujo un 40 % el tiempo para completar las tareas (How we built our multi-agent research system).

Esta es la segunda nota de la serie sobre cómo construir agentes de IA. Aquí van las reglas que sigo, la mayoría de la guía de Anthropic sobre herramientas para agentes (Writing effective tools for agents, 2025).

Pocas herramientas, pensadas para el trabajo

El error más común es envolver cada endpoint de tu API en una herramienta. El agente termina con cuarenta opciones parecidas y elige mal. Más herramientas no dan mejores resultados.

La alternativa es diseñar pocas herramientas que hagan un trabajo completo:

  • En vez de listar_contactos, que devuelve todos, una herramienta buscar_contactos que devuelve los que importan.
  • En vez de ver_disponibilidad y crear_evento por separado, una agendar_cita que revisa la agenda y reserva en un solo paso.
  • En vez de tres llamadas para armar el historial de un cliente, una ver_cliente que devuelve lo que un asesor querría ver.

Una buena prueba: si una persona de tu equipo nunca haría ese paso por separado, el agente tampoco debería tener que hacerlo.

Nombres que no se confunden

Cuando hay herramientas de varios sistemas, agrúpalas con un prefijo por servicio y recurso: crm_buscar_clientes, crm_ver_cliente, agenda_buscar_horarios. El agente elige mejor cuando el nombre ya dice de dónde viene la herramienta y sobre qué actúa.

Lo mismo con los parámetros. cliente_id es mejor que cliente, porque no deja dudas sobre si espera un nombre, un correo o un número.

Descripciones escritas para alguien nuevo

La descripción de una herramienta es parte del prompt. Escríbela como se la explicarías a alguien que entró ayer al equipo: qué hace, cuándo usarla, qué significa cada término y qué formato esperan los datos.

herramienta-floja.json
{
"name": "citas",
"description": "Gestiona citas.",
"input_schema": {
"type": "object",
"properties": { "fecha": { "type": "string" }, "id": { "type": "string" } }
}
}
herramienta-clara.json
{
"name": "agenda_buscar_horarios",
"description": "Busca horarios libres para un servicio en un rango de fechas. Úsala antes de ofrecerle un horario al cliente. No reserva nada: para reservar usa agenda_agendar_cita.",
"input_schema": {
"type": "object",
"properties": {
"servicio_id": { "type": "string", "description": "ID del servicio, tomado de agenda_listar_servicios. Ej: 'srv_limpieza'." },
"desde": { "type": "string", "format": "date", "description": "Primer día a buscar, en formato AAAA-MM-DD." },
"hasta": { "type": "string", "format": "date", "description": "Último día a buscar. Máximo 14 días después de 'desde'." }
},
"required": ["servicio_id", "desde", "hasta"]
}
}

La segunda dice cuándo usarla, qué no hace y de dónde sale cada dato. Con eso, el modelo deja de adivinar.

Hazla difícil de usar mal

Anthropic usa un término de manufactura japonesa: poka-yoke, diseñar algo para que sea difícil cometer el error. En su caso, el agente se equivocaba con rutas de archivo relativas, así que cambiaron la herramienta para que solo aceptara rutas absolutas, y el error desapareció.

En un negocio se ve así:

  • Fechas con un formato fijo, no “el martes”.
  • Listas cerradas (enum) cuando hay pocas opciones válidas, en vez de texto libre.
  • Montos en un campo numérico con su moneda, no “unos 200 mil”.
  • Para acciones riesgosas, un paso de confirmación separado que tu sistema valida, no el modelo.

Cada restricción que pones en la herramienta es una falla que no tienes que detectar después.

Respuestas que el agente pueda usar

Lo que devuelve una herramienta entra completo al contexto del agente. Por eso:

  • Devuelve lo que importa. Nombres y estados legibles, no solo identificadores internos. Si el agente necesita un ID para la siguiente llamada, inclúyelo junto al nombre.
  • Cuida el tamaño. Paginación, filtros y un límite por defecto. Claude Code, por ejemplo, corta por defecto las respuestas de herramientas en 25.000 tokens. Una respuesta enorme no solo cuesta más: empuja fuera del foco lo que el agente necesitaba recordar.
  • Ofrece niveles de detalle. Un parámetro como formato: "resumido" | "detallado" le deja al agente elegir cuánto necesita.

Errores que explican qué hacer

Un error que dice 400 Bad Request no le enseña nada al agente. Uno que dice qué salió mal y cómo arreglarlo, sí:

errores.txt
Malo: Error 400
Bueno: La fecha "4/11" no tiene el formato AAAA-MM-DD. Usa, por ejemplo, "2026-11-04".
Bueno: No hay horarios libres para ese servicio entre esas fechas. Prueba un rango más amplio
o ofrécele al cliente hablar con una persona.

Un buen mensaje de error es la diferencia entre un agente que se recupera solo y uno que repite la misma llamada cinco veces.

El banco de herramientas: pocas herramientas bien marcadas, y el agente elige la correcta en cada paso.

Pruébalas con tareas reales

Las herramientas se diseñan con datos, no con intuición. Arma un grupo de tareas reales de varios pasos, con un resultado que se pueda verificar, y mira cómo el agente usa tus herramientas: cuántas llamadas hace, cuáles fallan, cuáles ignora y cuántos tokens gasta. Lee las transcripciones. Ahí aparece la herramienta que el agente confunde con otra o el parámetro que nunca entiende.

El método completo está en cómo evaluar un agente de IA.