Granularidad de herramientas en agentes LLM: lo que nos enseñaron 20 configuraciones de flujo de trabajo

La sabiduría popular en torno a las herramientas de los agentes LLM tiende a converger en uno de dos lemas: "dale al modelo menos herramientas para que no se confunda", o "expón cada operación como una herramienta para que el modelo pueda componer con libertad". Ambos están equivocados de maneras interesantes. Construimos AgentDoc –un editor de documentos impulsado por MCP– en parte para disponer de un banco de pruebas creíble para esta cuestión, y ejecutamos 20 configuraciones de flujo de trabajo (A–T) en 13 escenarios de referencia para ver qué marca realmente la diferencia.

Esta entrada recoge lo que encontramos; aquí nos centramos en las conclusiones prácticas para cualquiera que diseñe herramientas para agentes LLM, ya sea para un servidor MCP, una API de llamada a funciones o un orquestador personalizado.

El montaje, en breve

Cada configuración es una combinación distinta de (a) superficie de herramientas –atómica frente a compuesta frente a mixta–; (b) control del flujo de trabajo –prompting ReAct puro frente a FSM ReAct restringido por estado–; y (c) política de verificación –opcional frente a obligatoria de get_document_context después de cada mutación. Las configuraciones van desde una línea base monolítica de cero ejemplos (una única herramienta gigante edit_document, sin FSM) hasta un FSM estrechamente controlado con 35 primitivas atómicas.

La puntuación usa la distancia de Levenshtein sobre el documento final, además del consumo de tokens y recuentos explícitos de alucinaciones (llamadas a herramientas que hacen referencia a índices que no existen).

Hallazgo 1: "menos herramientas" gana en tokens, pierde en precisión

La línea base monolítica de edit_document es, con diferencia, la más barata en tokens: el modelo emite una única llamada grande y listo. Pero sus puntuaciones de Levenshtein son aproximadamente 3 veces peores que las de las configuraciones de herramientas atómicas en tareas de varios pasos, porque el modelo tiene que planificar la mutación entera en una sola pasada hacia adelante, sin oportunidad de verificar el estado intermedio.

En documentos largos, este régimen falla por completo: el modelo emite una edición que hace referencia a un encabezado que ya no existe en el desplazamiento supuesto (porque ediciones hipotéticas anteriores "dentro del mismo plan" desplazaron los índices), y el resultado es un documento corrupto sobre el que es difícil razonar incluso para el siguiente turno del agente.

Hallazgo 2: "cada operación como una herramienta" gana en precisión, pierde en tokens... y en precipicios

Las herramientas puramente atómicas (find, delete_substring, insert_string, etc. por separado) empujan la verificación al bucle de razonamiento del modelo. Con modelos de frontera ajustados por instrucciones, la precisión es alta, pero los recuentos de tokens se disparan, y observamos un precipicio abrupto en torno a superficies de 25 herramientas: por encima de eso, el modelo empieza a seleccionar mal entre herramientas casi sinónimas (insert_paragraph frente a insert_text frente a append_text), lo cual es su propio modo de fallo que no aparece en las configuraciones de 8 herramientas.

El número de herramientas interactúa con la entropía de los nombres. Veinte herramientas cuyos nombres se agrupan semánticamente (insert_*, append_*, prepend_*) son más difíciles para el modelo que treinta herramientas que abarcan verbos obviamente distintos.

Hallazgo 3: un conjunto pequeño de macros bien nombradas es el punto óptimo

Las configuraciones que obtuvieron la puntuación más alta en el equilibrio conjunto precisión/tokens comparten una estructura: primitivas atómicas para la cola larga, más de tres a cinco macros bien nombradas para las rutas comunes evidentes (replace_all, format_all_matches, convert_paragraph_to_heading). Las macros eliminan las secuencias de varios pasos más habituales –reduciendo 4 idas y vueltas a 1– sin forzar al modelo a componerlas desde cero.

El truco no es el número de macros; es que cada macro debe corresponder a una petición en lenguaje natural que los usuarios realmente hacen. Las macros inventadas por elegancia de código ("composeFormatBatch") son ignoradas por el modelo en favor de las primitivas atómicas. Las macros nombradas según peticiones comunes ("reemplazar todos los X por Y") se usan de inmediato y correctamente.

Hallazgo 4: la verificación estructural vence a la verificación por prompt

Decirle al modelo "vuelve siempre a leer el documento antes de mutar" funciona parte del tiempo. Un FSM ReAct restringido por estado que bloquea las herramientas de escritura hasta que se completa una llamada a get_document_context funciona todo el tiempo. Las configuraciones con FSM redujeron los errores de índice alucinado del ~14 % en la condición solo con prompt a menos del 2 %, y el coste es una única ida y vuelta adicional cada pocos turnos, algo barato frente a una edición corrupta.

Esta es la conclusión práctica más fuerte de todo el estudio: si tu agente opera sobre estado sensible a índices (un documento, un búfer, un árbol de sintaxis), no confíes en los prompts por sí solos. Haz que la verificación sea estructuralmente inevitable en la propia superficie de herramientas.

Hallazgo 5: la deriva de índices es un fallo de diseño de herramientas, no del modelo

Vimos repetidamente que las configuraciones con peor rendimiento no eran "débiles" según ninguna métrica de capacidad: simplemente exponían herramientas cuyos contratos permitían al modelo tener éxito localmente y fallar globalmente. Una herramienta que toma un índice de carácter y devuelve éxito sin avisar al modelo de que todo lo posterior a ese índice se ha desplazado es el fallo. Los modelos de frontera acabarán aprendiendo a compensarlo. Tu superficie de herramientas no debería obligarlos a ello.

En concreto: cada herramienta de mutación en AgentDoc devuelve una carga útil estructurada que incluye un descriptor de rango modificado ({shifted_after: 412, delta: -23}). La siguiente llamada a herramienta lo ve, y el FSM controla una relectura. Como resultado, las alucinaciones cayeron casi hasta el suelo.

Qué significa esto si estás construyendo un agente

Tres reglas generales que valen más que cualquier cifra concreta de arriba:

• Usa primitivas atómicas por defecto y añade macros para las rutas en lenguaje natural. No optimices de antemano el coste en tokens; es más barato que una edición corrupta.
• Mantén la superficie de herramientas por debajo de 25, o divídela en familias con nombres distintos. La ambigüedad por agrupación es un modo de fallo real.
• Haz la verificación estructural. Un FSM que coloca las herramientas de escritura detrás de una relectura reciente cuesta casi nada y elimina toda la clase de fallos por deriva de índices.

La siguiente entrada de esta serie trata sobre la arquitectura centrada en la voz –incluyendo por qué decidimos conectar Gemini Live directamente a la superficie MCP en lugar de hacerlo a través de un proxy de transcripción. La decisión deriva precisamente de los hallazgos anteriores.