Écrire des descriptions d'outils MCP que le modèle comprend vraiment
La description d'un outil MCP est ton interface utilisateur. Ce qu'elle doit contenir, les erreurs qui reviennent tout le temps, et le test qui révèle les ambiguïtés.
La description d'un outil MCP n'est pas de la documentation. C'est ton interface utilisateur.
C'est le seul élément que le modèle lit avant de décider s'il appelle ton outil, et c'est souvent aussi ce que voit l'utilisateur final. Une description approximative produit exactement le même effet qu'un bouton mal étiqueté : personne ne clique, ou tout le monde clique au mauvais moment.
La règle de base
Une description doit répondre à trois questions, dans cet ordre :
- Qu'est-ce que cet outil fait
- Quand faut-il l'utiliser plutôt qu'un autre
- Qu'est-ce qu'il ne fait pas
La plupart des serveurs ne répondent qu'à la première. C'est la deuxième qui détermine la sélection, et la troisième qui évite les appels absurdes.
Avant et après
Avant : « Récupère une liste d'éléments. »
Cette phrase ne dit ni ce qu'est un élément, ni quand cet outil est le bon, ni comment il se distingue des trois autres qui récupèrent aussi des listes.
Après : « Liste les formulaires de l'utilisateur, brouillons et publiés. À utiliser pour retrouver un formulaire existant avant de le modifier ou de lire ses réponses. Ne renvoie pas le contenu des réponses. »
On a gagné le périmètre, le moment d'usage et la limite. C'est trois phrases, et ça change le taux de sélection.
Les erreurs qui reviennent tout le temps
Écrire pour un développeur. « Effectue un GET sur /api/v2/items avec pagination » ne veut rien dire pour le modèle, qui n'appelle pas ton API mais ton outil.
Recopier le nom de l'outil. « create_form : crée un formulaire. » C'est une ligne perdue.
Oublier les paramètres. Chaque paramètre a aussi une description dans le schéma. Un paramètre non décrit sera rempli au jugement, et souvent mal. Les valeurs par défaut et les formats attendus se disent là.
Mettre de l'infrastructure dedans. Noms d'hôtes internes, identifiants de tenants, chemins. La description est lue par le modèle et souvent visible.
Traiter les messages d'erreur comme un détail. Ils font partie de l'interface. Un message d'erreur clair permet au modèle de se corriger tout seul. Une erreur brute de base de données le fait boucler, et elle fuite ton schéma.
Le vocabulaire de tes utilisateurs, pas le tien
C'est le point le plus rentable et le plus négligé.
Tes utilisateurs ne demandent pas « instancie une entité de type formulaire ». Ils disent « crée-moi un questionnaire de satisfaction ». Si le mot « questionnaire » n'apparaît nulle part dans tes descriptions, la correspondance se fait moins bien.
Procédé simple : prends vingt demandes réelles de tes utilisateurs, relève les noms qu'ils emploient, et vérifie que ces mots figurent dans tes descriptions.
Les annotations comptent autant que le texte
Un outil peut être annoté comme en lecture seule ou comme destructeur. Ce n'est pas décoratif.
C'est ce qui permet au client de demander une confirmation humaine avant une action irréversible. Sans annotation, tous tes outils se ressemblent, et un agent traitera la suppression comme la lecture.
Annote systématiquement. Ça coûte une ligne et ça change la façon dont ton serveur est perçu, y compris dans un dossier de soumission.
Le test
Donne ta liste d'outils, noms et descriptions seulement, à quelqu'un qui ne connaît pas ton produit. Demande-lui, pour dix demandes formulées en langage naturel, quel outil il choisirait.
Là où un humain hésite, le modèle se trompera. Et l'humain, lui, peut t'expliquer pourquoi.
FAQ
Quelle longueur ?
Deux à quatre phrases pour l'outil, une ligne par paramètre non évident. Plus long ne rend pas la sélection meilleure et consomme du contexte.
Faut-il des exemples dans la description ?
Un exemple court aide sur les formats ambigus, comme les dates ou les identifiants. Pas besoin ailleurs.
Faut-il traduire mes descriptions ?
Garde une langue unique et cohérente. Le modèle fait le pont avec la langue de l'utilisateur.
Faire relire ta surface d'outils
L'audit inclut la revue des noms, descriptions, paramètres, annotations et messages d'erreur, avec un test de sélection sur des demandes réelles. Sous 24 heures ouvrées.
Prêt à faire le point ? Faire auditer mon serveur MCP →
Lectures liées
Un serveur MCP à faire auditer ?
Cinq minutes pour le décrire. Je réponds sous 24 heures ouvrées avec un premier diagnostic écrit et gratuit.
Faire auditer mon serveur MCP