Menos herramientas, mejores nombres: el costo oculto de darle todo al agente

Hay un reflejo muy común al construir un agente: si le doy más herramientas, va a poder hacer más cosas. Es intuitivo y es falso.

Las definiciones de herramientas viven dentro de la ventana de contexto, en cada llamada. Una definición típica ocupa entre cien y quinientos tokens. Un montaje de cinco servidores con cincuenta y ocho herramientas se lleva unos cincuenta y cinco mil tokens antes de que el agente lea una sola palabra del usuario. Hay integraciones populares que solas ocupan diecisiete mil.

Pero el costo en tokens es el menor de los dos.

El costo que importa es la indecisión

Si el agente ve cincuenta herramientas, tiene que leer y ordenar cincuenta descripciones para decidir cuál usar. Eso agranda el prompt, demora la respuesta y, lo peor, lo empuja a elegir la herramienta amplia cuando la angosta habría sido más segura.

Nosotros lo vimos con una herramienta genérica de "guardar archivo". Existía para casos legítimos, pero el agente empezó a usarla para todo, incluso para cosas que tenían su propia vía con validaciones. Nunca hizo nada catastrófico. Simplemente eligió el camino ancho porque estaba ahí.

La solución no fue mejorar el prompt. Fue sacar la herramienta genérica del catálogo de ese agente.

Cómo diseñamos las nuestras

El nombre es la mitad del trabajo. Una herramienta que se llama delegate_asset se usa distinto que una que se llama process_file. El nombre le dice al modelo qué clase de acción es, antes de leer la descripción.

La descripción dice cuándo NO usarla. Esto es lo que más nos sirvió. No alcanza con explicar qué hace; hay que decir en qué casos hay una alternativa mejor. "Usá esto solo si el archivo no está ya en el storage de la cuenta; si está, usá X."

Cada agente tiene su propio catálogo. El agente que conversa con el cliente y el que ejecuta tareas internas no comparten herramientas. Comparten infraestructura, no capacidades.

Las herramientas se testean. Tenemos un test que valida los esquemas de todas las herramientas y falla si alguna quedó con un tipo mal declarado o una descripción vacía. Suena obvio hasta que una descripción vacía se te va a producción y el agente empieza a elegir a ciegas.

Carga diferida

Hay una salida elegante para cuando el catálogo tiene que ser grande: no cargar todas las definiciones de entrada, sino buscarlas cuando hacen falta. Los números publicados son contundentes: un caso donde las definiciones ocupaban ciento treinta y cuatro mil tokens bajó a unos cinco mil con carga diferida, una reducción del ochenta y cinco por ciento.

Es la dirección correcta cuando el catálogo crece. Pero conviene decir lo otro: si tu agente necesita cincuenta herramientas, quizás no necesitás carga diferida. Quizás necesitás dos agentes.

La pregunta que hacemos antes de agregar una

Antes de sumar una herramienta nueva al catálogo, la pregunta no es "¿esto sería útil?". Casi todo sería útil. La pregunta es: ¿qué tarea concreta hoy no se puede hacer, y por qué ninguna de las que ya están alcanza?

Si no hay una respuesta clara en una oración, la herramienta no entra.