Qué hace que una lista de herramientas sea legible para un agente

Un agente nunca ve tu documentación. Ve una lista de nombres de herramientas, descripciones de una línea y un esquema JSON de parámetros. Ese es todo el briefing. Si de ahí no se deduce cuál es la herramienta correcta, el agente elegirá la equivocada — o hará al usuario una pregunta que no debería haber hecho falta.

Evaluamos y puntuamos cada superficie de herramientas legible del catálogo. Tras leer miles, los fallos se agrupan.

1. Herramientas que se solapan

Dos herramientas que podrían responder razonablemente a la misma petición son el error más caro, porque el agente no tiene criterio de desempate. Si tienes search_docs y find_document, una de las dos debe decir para qué sirve que la otra no.

2. Parámetros sin significado

Un parámetro llamado query de tipo string no le dice nada al agente. ¿Qué va dentro: una palabra clave, una pregunta, un identificador? ¿Distingue mayúsculas? ¿Qué pasa si va vacío? Eso pertenece al esquema, no al README.

3. Sin ejemplos en las ambiguas

La mayoría de herramientas no necesita ejemplos. La que acepta un objeto libre, una expresión de filtro o un identificador propio del dominio, sin duda sí. En nuestras evaluaciones, "faltan ejemplos de uso" es una de las debilidades más frecuentes — y casi siempre se refiere a una herramienta concreta, no al servidor entero.

4. Restricciones silenciosas

Límites de tasa, número máximo de resultados, tiempos de espera, si la llamada cuesta dinero. Un agente que no conoce el límite lo alcanzará. Los servidores con mejor puntuación son los que lo dicen claramente en la descripción.

La versión corta

• Nombres distintos que impliquen trabajos distintos.
• Cada parámetro descrito en términos de qué poner dentro.
• Ejemplos en las herramientas por las que un humano preguntaría.
• Límites escritos donde el agente los va a leer de verdad.

Nada de esto exige más herramientas. Casi todo exige menos, mejor descritas.