Un desarrollador descubre que el problema era el esquema de herramientas, no el prompt

Un desarrollador llevaba días peleándose con un agente que elegía mal la herramienta en un flujo bastante simple. Tenía cuatro disponibles y dos de ellas se parecían demasiado: una leía registros existentes y la otra creaba uno nuevo. El modelo se iba sistemáticamente a la equivocada.

La primera reacción fue la habitual: tocar el system prompt. Reglas explícitas, ejemplos, avisos, incluso una tabla de decisión diciéndole al modelo cuándo usar cada una. Nada. El comportamiento seguía igual. El problema no apareció hasta que registró las definiciones de herramientas que se estaban enviando al modelo.

Ahí estaba. Las descripciones venían copiadas de la documentación interna de la API. Eran técnicamente correctas, pero contaban qué hacía cada función, no cuándo debía usarla el agente. Una de ellas además tenía un parámetro llamado type que aceptaba varios valores sin explicar la diferencia semántica entre ellos. El modelo no estaba confundido: estaba tomando decisiones con información incompleta.

El esquema también es prompt

La corrección fue reescribir las descripciones de las herramientas y hacer mucho más explícitas las restricciones de los parámetros. El system prompt apenas cambió. La precisión en la selección de herramienta mejoró de inmediato.

La conclusión que saca el autor es sencilla y conviene tenerla a mano: el esquema de herramientas es parte del prompt, lo trates como tal o no. El modelo no distingue entre las instrucciones que le pones en el mensaje de sistema y los metadatos que acompañan a cada función. Todo eso entra en la misma ventana y compite por la misma atención. Si la descripción de una herramienta describe su implementación en lugar de su momento de uso, el agente tiene que adivinar, y adivina mal.

Esto encaja con lo que ya se ve en la práctica al construir agentes con function calling. La documentación de una API está pensada para que la lea una persona que ya sabe lo que quiere llamar; la descripción de una herramienta tiene que estar pensada para que la lea un modelo que aún no ha decidido nada. Son dos textos distintos y a menudo se reutiliza el primero como si sirviera para lo segundo.

Qué hacer con esto

La regla operativa que propone el desarrollador es directa: ante un error repetido de selección, revisar la definición de la herramienta antes de añadir otro párrafo al system prompt. Y cuando dos herramientas se solapan funcionalmente, la descripción tiene que dejar clarísima la frontera y el caso de uso de cada una. Los parámetros con valores enumerados necesitan explicar qué significa cada valor, no solo listarlos.

Queda por ver cuánto de esto termina siendo responsabilidad del que escribe el agente y cuánto lo van a absorber los propios frameworks, que ya empiezan a validar y generar esquemas. De momento, es trabajo de quien despliega el agente. Y cuesta menos revisar cuatro descripciones que reescribir un prompt durante una semana.