Cómo diseñar herramientas para agentes de IA: buenas prácticas y errores habituales

La calidad de un agente de IA no depende solo de la potencia del modelo de lenguaje, sino también de lo bien diseñadas que estén sus herramientas. Machine Learning Mastery ha analizado qué hace eficaces las tools para agentes 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, su descripción y el esquema de parámetros, y a partir de ellos decide cuándo invocarla y con qué argumentos.

Un ejemplo de herramienta débil: `get_data()` con la descripción «obtiene datos». Un ejemplo de herramienta sólida: `get_user_purchase_history(user_id)`, descrita como «devuelve la lista de compras de los últimos 90 días, ordenadas por fecha. Úsala cuando necesites analizar el gasto o construir personalización». La segunda opción explica no solo qué hace la herramienta, sino también cuándo invocarla, y para el agente eso supone un nivel de utilidad radicalmente distinto.

El nombre aporta semántica: `process_file` es demasiado amplio. Con `extract_invoice_line_items`, el modelo entiende de inmediato el contexto y su aplicabilidad. Una buena fórmula: verbo + objeto + matiz.

«La descripción de la herramienta es el prompt de la propia herramienta.

Si es vaga, el agente alucinará argumentos o invocará la herramienta equivocada».

Una herramienta, una responsabilidad

El error más frecuente es la «navaja suiza»: una función con una decena de parámetros que hace cinco cosas distintas según la combinación de flags.

Señales de una herramienta mal diseñada:

• Un parámetro `mode` o `action` con un conjunto de valores de tipo cadena
• Más de 5–6 parámetros en una sola función
• La descripción contiene la conjunción «o»: «busca un contacto o crea uno nuevo»
• Devuelve distintos tipos de datos según los argumentos de entrada
• Parámetros opcionales que cambian por completo el comportamiento

Si una herramienta hace varias cosas, divídela en herramientas independientes. Al agente le resulta más fácil elegir entre `search_contact` y `create_contact` que adivinar la combinación correcta de flags en `manage_contact`. Con más de 20 herramientas en el contexto, la precisión de los modelos al elegir la adecuada cae de forma notable, así que conviene mantener un conjunto compacto.

Parámetros y valores de retorno

El tipo del parámetro influye en la calidad de la generación. Un `string` sin descripción es una fuente de alucinaciones; un `enum` con una lista explícita de valores permitidos, no. En los parámetros numéricos, indica el rango y las unidades: no `timeout`, sino `timeout_seconds: integer, 1–30`.

El valor de retorno debe ser predecible y compacto, porque el agente añade toda la salida de la herramienta al contexto. Si una herramienta devuelve miles de tokens de HTML en bruto, se convierte en un cuello de botella para toda la cadena de llamadas.

Principios de un buen return value:

• JSON con una estructura fija: el modelo analiza mejor los formatos predecibles
• Los errores, como datos estructurados y no como excepciones sin capturar
• Metacampos: `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 sobre cómo proceder

Qué significa esto

Las herramientas para agentes no son simples envoltorios de una API. Son la interfaz entre el modelo de lenguaje y el mundo real, y requieren la misma atención que una API pública: documentación, tipos bien pensados y pruebas aisladas. El agente no corregirá una herramienta mal diseñada: la seguirá invocando de forma incorrecta una y otra vez.