Ce qui rend une liste d'outils lisible pour un agent

Un agent ne voit jamais votre documentation. Il voit une liste de noms d'outils, des descriptions d'une ligne et un schéma JSON de paramètres. Voilà tout le briefing. Si le bon outil ne s'en déduit pas, l'agent choisit le mauvais — ou pose à l'utilisateur une question qui n'aurait pas dû être nécessaire.

Nous évaluons et notons chaque surface d'outils lisible du catalogue. Après en avoir lu des milliers, les échecs se regroupent.

1. Des outils qui se chevauchent

Deux outils susceptibles de répondre à la même demande constituent l'erreur la plus coûteuse, car l'agent n'a aucun critère de départage. Si vous avez search_docs et find_document, l'un des deux doit dire ce qu'il fait que l'autre ne fait pas.

2. Des paramètres sans signification

Un paramètre nommé query de type string n'apprend rien à l'agent. Qu'y met-on : un mot-clé, une question, un identifiant ? Sensible à la casse ? Que se passe-t-il s'il est vide ? Cela appartient au schéma, pas au README.

3. Pas d'exemples sur les outils ambigus

La plupart des outils n'ont pas besoin d'exemple. Celui qui accepte un objet libre, une expression de filtre ou un identifiant métier en a absolument besoin. Dans nos évaluations, « manque d'exemples d'utilisation » est l'une des faiblesses les plus fréquentes — et cela vise presque toujours un outil précis, pas le serveur entier.

4. Contraintes silencieuses

Limites de débit, nombre maximal de résultats, délais d'exécution, coût éventuel d'un appel. Un agent qui ignore la limite va la heurter. Les serveurs les mieux notés sont ceux qui l'écrivent noir sur blanc dans la description.

La version courte

• Des noms distincts qui impliquent des rôles distincts.
• Chaque paramètre décrit par ce qu'on doit y mettre.
• Des exemples sur les outils au sujet desquels un humain poserait une question.
• Des limites écrites là où l'agent les lira vraiment.

Rien de tout cela n'exige plus d'outils. L'essentiel en exige moins, mieux décrits.