Cómo Diseñar Herramientas para Agentes de IA: Prácticas de Trabajo y Errores Comunes

La calidad de un agente de IA se determina no solo por el poder del modelo de lenguaje, sino también por cómo están diseñadas sus herramientas. Machine Learning Mastery analizó qué es lo que hace que las herramientas de agentes sean efectivas — y qué errores convierten a un agente inteligente en uno caótico.

El nombre y la descripción lo deciden todo

El modelo de lenguaje no ve el código fuente de la herramienta. Solo ve su nombre, descripción y esquema de parámetros — y basándose en esto, decide cuándo llamarla y con qué argumentos. Ejemplo de una herramienta débil: `get_data()` con descripción "obtiene datos". Ejemplo de una herramienta fuerte: `get_user_purchase_history(user_id)` — "devuelve una lista de compras en los últimos 90 días, ordenadas por fecha. Utiliza cuando necesites analizar gastos o construir personalización". La segunda opción explica no solo qué hace la herramienta, sino cuándo llamarla — estos son niveles fundamentalmente diferentes de utilidad para el agente.

Un nombre lleva semántica: `process_file` — demasiado amplio. `extract_invoice_line_items` — el modelo entiende inmediatamente el contexto y la aplicabilidad. Buena fórmula: verbo + objeto + aclaración.

"La descripción de la herramienta es un prompt para la herramienta misma.

Si es vaga, el agente alucinará argumentos o llamará a la herramienta incorrecta."

Una herramienta — una responsabilidad

El error más común es una "navaja suiza": una función con una docena de parámetros que hace cinco cosas diferentes dependiendo de una combinación de banderas. Señales de una herramienta mal diseñada:

• Parámetro `mode` o `action` con un conjunto de valores de cadena
• Más de 5–6 parámetros en una sola función
• La descripción contiene "o" — "busca contacto o crea uno nuevo"
• Devuelve diferentes tipos de datos dependiendo de los argumentos de entrada
• Parámetros opcionales que cambian drásticamente el comportamiento

Si una herramienta hace varias cosas — divídela en herramientas separadas. Un agente elegirá más fácilmente entre `search_contact` y `create_contact` que adivinar la combinación correcta de banderas en `manage_contact`. Con más de 20 herramientas en contexto, la precisión de los modelos para elegir la correcta disminuye notablemente — mantén el conjunto compacto.

Parámetros y valores de retorno

El tipo de parámetro afecta la calidad de la generación. `string` sin descripción — una fuente de alucinaciones. `enum` con una lista explícita de valores permitidos — no. Para parámetros numéricos, especifica el rango y las unidades de medida: no `timeout`, sino `timeout_seconds: integer, 1–30`. El valor de retorno debe ser predecible y compacto: el agente agrega toda la salida de la herramienta al contexto. Si una herramienta devuelve miles de tokens de HTML sin procesar — esto es un cuello de botella para toda la cadena de llamadas. Principios de un buen valor de retorno:

• JSON con estructura fija — el modelo analiza mejor los formatos predecibles
• Errores — datos estructurados, no excepciones no capturadas
• Campos meta: `total_results`, `truncated: true`, `next_cursor`
• Solo lo que el agente necesita para el siguiente paso — nada más
• En caso de error — un mensaje claro con instrucciones para acciones futuras

Qué significa esto

Las herramientas para agentes no son solo envoltorios alrededor de APIs. Esta es una interfaz entre el modelo de lenguaje y el mundo real, que requiere la misma atención que una API pública: documentación, tipos bien pensados, pruebas en aislamiento. Un agente no corregirá una herramienta mal diseñada — la llamará incorrectamente una y otra vez.