El problema real del tool_use: cuándo los agentes eligen mal sus herramientas
Tiempo estimado de lectura: 4 min
- Diseña cada tool como un contrato: propósito claro, condición binaria de activación, restricciones negadas y un schema de salida.
- Reduce la superficie de decisión: retrieval dinámico y máquinas de estado cuando el catálogo supera ~10–15 tools.
- Valida estrictamente: enums, formatos concretos y validación back-end (ej. Zod) para evitar argumentos corruptos.
- Mide lo que importa: precisión de selección, retries, tokens gastados y casos de misuse en staging.
Si tu agente tiene acceso a muchas herramientas y no defines reglas explícitas, no estás ante un fallo del modelo: estás ante un diseño roto. Este artículo explica por qué ocurren elecciones equivocadas y cómo diseñar descripciones de herramientas que reducen errores de selección hasta en ~80% en implementaciones reales. Conectar APIs es trivial; conseguir que un LLM seleccione la herramienta correcta, con argumentos válidos y sin invocar capacidades fuera de scope, es ingeniería.
Resumen rápido (lectores con prisa)
Define cada herramienta como un contrato: una frase de propósito, una condición de activación binaria, restricciones explícitas de uso y un schema de salida mínimo. Usa retrieval dinámico para reducir opciones y máquinas de estado para limitar permisos. Valida en back-end (ej. Zod) y mide precisión de selección y retries.
El problema real del tool_use: cuándo los agentes eligen mal sus herramientas — causas
Tres causas estructurales explican la mayoría de las fallas en producción:
- Solapamiento semántico. Dos o más tools parecen válidas para la misma intención; el modelo elige por probabilidades.
- Ausencia de fronteras negativas. Documentas qué hace la tool pero no cuándo está prohibida; el modelo probará usos peligrosos.
- Sobrecarga del contexto. Inyectar 30–40 esquemas en el prompt produce “lost in the middle” y pérdida de atención (ver estudio).
Si no mitigues estas tres fuentes de ambigüedad, el agente duplicará llamadas, generará argumentos corruptos o intentará acciones destructivas.
Cómo diseñar descripciones que reducen errores de selección (estructura de 4 campos)
Piensa la descripción de cada herramienta como un contrato para una red neuronal: precisa, restrictiva y ejecutable. Sigue estos cuatro campos en todas las tools:
- Propósito (What) — Una sola frase: acción exacta.
- Condición de activación (When) — “Úsalo SOLO cuando…” (condición binary o claramente verificable).
- Restricción excluyente (When NOT) — “NO lo uses para…” y alternativa sugerida.
- Formato de salida (Expected Output) — JSON schema mínimo que el agente puede comprobar antes de llamar.
Ejemplo práctico
Descripción:
“Recupera el estado y el último comentario de un ticket de Jira. Úsalo SOLO con un ticket ID válido (PROJ-123). NO lo uses para búsquedas por texto; usa
search_jira_ticketspara eso.”
Schema (JSON / Zod-like)
{
“type”: “object”,
“properties”: {
“ticketId”: { “type”: “string”, “pattern”: “^[A-Z]+-\\d+$” }
},
“required”: [“ticketId”]
}
Ese nivel de precisión elimina ambigüedad en cuándo y cómo llamar la tool.
Schemas como enrutadores: reglas prácticas
- Evita tipos genéricos. Si esperas fecha, exige format: “date-time”.
- Describe cada propiedad. El LLM usará esa descripción para construir el valor.
- Forza enums para valores discretos. Los LLM respetan enums con alta consistencia.
- Implementa validación estricta (Zod) en el back-end y devuelve errores estructurados (Result pattern) si el LLM envía datos inválidos.
Arquitectura para catálogos grandes: Dynamic Tool Retrieval y State Machines
Cuando tienes >10–15 tools, las descripciones no bastan. Aplica dos patrones:
- Dynamic Tool Retrieval (RAG de herramientas). Embeddiza la intención del usuario y busca en una DB vectorial las 3–4 tools más relevantes; solo esas se inyectan en el prompt. Implementaciones prácticas usan pgvector o sistemas vectoriales gestionados. Reducir la superficie de decisión aumenta la precisión drásticamente.
- Máquinas de estado / orquestación. Divide responsabilidades entre sub-agentes con permisos limitados. Herramientas de orquestación: n8n, LangGraph o XState. El nodo de “consulta” solo expone tools de lectura; el nodo de “modificación” habilita herramientas de escritura tras condiciones de validación.
Restricción por estado = seguridad + predictibilidad.
Métricas y pruebas que importan
No te fíes de sensaciones. Mide:
- Precisión de selección (tool chosen vs. tool expected).
- Retries por tipo de error.
- Tokens gastados en reintentos inútiles.
- Casos de “tool misuse” detectados en staging.
Introduce tests que simulen entradas ambiguas y fallos de herramientas. Si una nueva tool aumenta la entropía del sistema, el pipeline debe bloquear el cambio hasta ajustar descripciones/schemas o introducir retrieval/state gating.
Conclusión operativa
El problema real del tool_use no se arregla con prompts más largos ni con nombres más creativos. Se arregla con contratos: descripciones inmutables que indiquen qué hacer y qué no hacer; schemas que validen argumentos; retrieval que reduzca la superficie de decisión; y orquestación que limite permisos por estado. En la práctica, aplicar esta disciplina reduce los errores de selección de herramientas en la mayoría de despliegues (hasta ~80% en nuestras pruebas) y convierte agentes ruidosos en sistemas previsibles y auditablemente seguros.
Si vas a exponer nuevas herramientas a un agente, no te preguntes si el LLM “entenderá”. Pregunta primero: ¿puede automatizarse la verificación de la condición de activación y la restricción excluyente? Si la respuesta es no, no la expongas todavía. Limita opciones, mejora instrucciones y mejora tus probabilidades de tener un agente que elige bien.
Para experimentos, plantillas y recursos relacionados con agentes y workflows, revisa Dominicode Labs. Es una extensión natural de las prácticas descritas aquí, con ejemplos aplicables a despliegues reales.
FAQ
¿Por qué el LLM elige la herramienta equivocada?
Porque hay ambigüedad: solapamiento semántico entre tools, falta de fronteras negativas o sobrecarga del contexto. Si no se reducen estas fuentes, el modelo elige por probabilidades y puede fallar.
¿Qué debe contener una descripción de tool?
Cuatro campos: Propósito (una frase), Condición de activación (¿cuándo usarla? — binaria), Restricción excluyente (¿cuándo NO usarla? con alternativa) y Formato de salida (schema mínimo verificable).
¿Qué es Dynamic Tool Retrieval y cuándo usarlo?
Es el patrón de embeddizar la intención y recuperar las N tools más relevantes desde una DB vectorial (RAG de herramientas). Úsalo cuando tengas más de ~10–15 tools para reducir la superficie de decisión.
¿Cómo aplicar validación estricta en producción?
Define schemas concretos (fechas con format, enums, patterns), valida en back-end (ej. Zod) y devuelve errores estructurados. Bloquea ejecuciones si la validación falla.
¿Qué métricas debo medir primero?
Precisión de selección (tool chosen vs. expected), retries por tipo de error y tokens gastados en reintentos. También monitorea casos de tool misuse en staging.
¿Cuándo no exponer una nueva tool al agente?
Si no puedes automatizar la verificación de la condición de activación y de la restricción excluyente, no la expongas. Mejor ajusta instrucciones, schemas o añade gating por retrieval/state antes de desplegar.
Leave a Reply