Concevoir des definitions d'outils MCP que les agents savent vraiment utiliser

Un agent lit vos definitions d'outils comme un nouvel ingenieur decouvre une API inconnue pour la premiere fois, sauf qu'il n'a aucun canal Slack ou poser ses questions et aucun collegue chez qui copier un appel qui fonctionne. Il dispose du nom de l'outil, de la description et du schema d'entree, et a partir de ces seuls trois elements il doit decider si votre outil est le bon pour la tache et comment l'appeler correctement du premier coup. Quand ces trois elements sont clairs, l'agent choisit le bon outil et remplit correctement les arguments. Quand ils sont flous, l'agent devine, et un agent qui devine appelle le mauvais outil, invente des parametres, ou renonce et dit a l'utilisateur qu'il ne peut pas l'aider. La difference tient presque entierement a la maniere dont vous avez ecrit la definition.

Ceci est un guide independant pour concevoir des definitions d'outils, pour un serveur Model Context Protocol, qu'un agent sait vraiment utiliser. Il est ecrit du cote de l'equipe qui construit le serveur, le producteur, car c'est la que se prennent les choix qui rendent un agent fiable ou non. Le Model Context Protocol est un standard ouvert, et les details evoluent, alors considerez les specificites ici comme la forme du travail plutot que comme une specification figee ; verifiez les details actuels dans la specification du Model Context Protocol. Ce qui ne change pas, c'est le savoir-faire : nommer les outils pour qu'un agent les distingue, les decrire pour qu'il sache quand recourir a chacun, typer les entrees pour qu'il ne puisse pas envoyer n'importe quoi, delimiter le perimetre pour que le choix reste reduit, et relier chaque outil a une action reelle pour que l'appel fasse ce qu'il annonce. C'est ce savoir-faire que couvre ce guide.

Il complete notre explication de ce qu'est le MCP, notre guide sur le MCP pour le SaaS et notre tutoriel pour construire votre premier serveur MCP, afin de situer le travail sur les definitions d'outils dans la tache plus large d'exposer votre produit aux agents.

L'essentiel en 60 secondes

• La definition est toute l'interface. Un agent voit le nom de l'outil, la description et le schema d'entree, et rien d'autre. Ces trois elements doivent porter tout le sens.
• Nommez les outils pour la tache, pas pour l'endpoint. Un nom comme create_invoice indique a l'agent ce que fait l'outil ; un nom comme post_v2_billing ne lui dit rien sur quoi raisonner.
• Ecrivez la description pour un lecteur qui n'a jamais vu votre produit. Dites ce que fait l'outil, quand l'utiliser et quand ne pas l'utiliser, en langage clair, car c'est ainsi que l'agent decide quel outil choisir.
• Typez chaque entree avec un vrai schema. Un schema type, avec champs requis, enumerations et formats, empeche l'agent d'envoyer des arguments que votre endpoint refusera.
• Delimitez le perimetre aux taches qui comptent. Vingt outils qui se recoupent troublent un agent plus que cinq outils nets. Exposez les actions qui meritent de l'etre et laissez le reste de cote.
• Reliez chaque outil a une action claire. Un outil qui fait exactement une chose est un outil que l'agent peut choisir avec assurance ; un outil qui en fait cinq derriere un indicateur de mode est un outil qu'il se trompe.
• Renvoyez des resultats lisibles par un agent. La sortie fait partie de l'interface elle aussi, alors renvoyez des resultats structures et previsibles sur lesquels l'agent peut agir, pas un mur de texte brut.

Pourquoi la definition est toute l'interface

Avec une API destinee aux humains, la definition est un point de depart. Un developpeur lit votre documentation, essaie un appel, lit l'erreur, consulte Stack Overflow et converge vers un usage correct au fil d'un apres-midi. Rien de tout cela n'est disponible pour un agent au moment ou il doit choisir. Il a vos definitions d'outils chargees dans son contexte, une requete utilisateur devant lui, et une seule chance de relier la requete a un outil et a un ensemble d'arguments. La definition n'est pas une documentation qui soutient la vraie interface. La definition est l'interface.

Ce changement de cadrage modifie le soin que merite la definition. Si l'agent choisit le mauvais outil, l'utilisateur obtient une mauvaise reponse ou une action ratee, et il y a rarement un humain dans la boucle pour le rattraper avant que cela ne se concretise. Si l'agent choisit le bon outil mais remplit mal un argument parce que le schema le permettait, votre endpoint soit rejette l'appel, soit, pire, l'accepte et fait quelque chose que l'utilisateur ne voulait pas. Le cout d'une definition floue n'est pas un developpeur plus lent. C'est un agent qui fait avec assurance la mauvaise chose, ce qui est le mode de defaillance qui erode la confiance dans toute l'integration.

Les recommandations officielles sur les outils refletent cela. La documentation du Model Context Protocol sur les outils decrit un outil comme une capacite nommee, dotee d'une description et d'un schema d'entree type, qu'un modele peut invoquer, ce qui est exactement l'interface en trois parties sur laquelle raisonne un agent. Tout dans ce guide vise a rendre chacune de ces trois parties sans ambiguite, car un agent ne peut pas poser de question de clarification a votre schema. Il ne peut que lire ce que vous avez ecrit et agir.

Etape 1 : nommer les outils pour la tache

Le nom est la premiere chose qu'un agent lit et souvent celle sur laquelle il s'appuie le plus pour choisir entre des outils, il doit donc decrire la tache dans des termes sur lesquels l'agent peut raisonner. L'erreur frequente est de nommer les outils d'apres l'implementation sous-jacente, la route, la table, le service interne, parce que c'est ce a quoi le nom correspond dans votre code. L'agent n'a pas votre code. Il a un utilisateur qui veut faire quelque chose, et un nom qui correspond a ce quelque chose est celui qu'il choisira.

Les bons noms d'outils partagent quelques proprietes. Ils nomment une action et un objet, pour que l'agent lise l'intention directement dans le nom. Ils emploient le verbe qu'un utilisateur emploierait, pas votre jargon interne. Et ils sont assez distincts pour que deux outils ne soient jamais confondables au premier regard.

Une convention de nommage coherente entre vos outils aide aussi. Si vous employez verbe_objet pour un outil, employez-le pour tous, afin que l'agent apprenne le schema et puisse prevoir que l'outil pour annuler une commande est probablement cancel_order. La coherence reduit le risque que l'agent ait a deviner. C'est la meme discipline de clarte que nous appliquons aux API publiques dans nos conseils sur une API prete pour les partenaires : un nom qui decrit la tache est un nom que l'appelant, humain ou agent, peut utiliser sans lire le reste de la documentation.

Etape 2 : ecrire des descriptions pour un lecteur qui n'a jamais vu votre produit

La description est l'endroit ou la plupart des definitions d'outils gagnent ou perdent le bon choix de l'agent. Une description faible repete le nom dans une phrase complete et n'ajoute rien : "Cree une facture." Une description forte indique a l'agent les trois choses dont il a vraiment besoin pour decider si c'est le bon outil : ce que fait l'outil, quand l'utiliser et quand ne pas l'utiliser. Ecrivez-la pour un lecteur competent qui n'a jamais vu votre produit, car c'est exactement la position de l'agent.

Ce qu'inclut une description forte :

• Ce que fait l'outil, concretement. Non pas "gere la facturation" mais "cree une facture brouillon pour un client avec une ou plusieurs lignes et renvoie l'identifiant de la facture." L'agent a besoin de connaitre l'effet reel.
• Quand l'utiliser. Nommez la situation a laquelle cet outil correspond, pour que l'agent puisse la relier a une requete utilisateur. "Utilisez-le quand l'utilisateur veut facturer un client pour des articles precis."
• Quand ne pas l'utiliser, s'il existe un voisin proche. Si vous avez aussi send_invoice, precisez que celui-ci ne cree qu'un brouillon et ne l'envoie pas, pour que l'agent ne choisisse pas la mauvaise moitie d'une tache en deux temps.
• Les preconditions importantes. Si le client doit exister d'abord, dites-le, pour que l'agent sache appeler create_customer avant celui-ci si necessaire.
• Ce qu'il renvoie, en une ligne. L'agent planifie son etape suivante autour de la sortie, alors dites-lui que le resultat est un identifiant de facture qu'il peut passer a send_invoice.

Le test d'une description est simple : remettez-la, avec les noms de vos autres outils, a quelqu'un qui n'a jamais utilise votre produit, decrivez une requete utilisateur, et regardez s'il choisit le bon outil et sait quoi faire du resultat. S'il hesite ou se trompe, l'agent le fera aussi. Les descriptions vagues sont la raison la plus frequente pour laquelle un agent appelle le mauvais outil, et ce sont aussi la chose la moins couteuse a corriger, car la corriger consiste simplement a ecrire plus clairement.

Une mise en garde merite d'etre enoncee clairement : la description est aussi une surface qu'un attaquant peut viser a travers les donnees que renvoie votre outil, alors traitez les definitions d'outils et leurs sorties comme une partie de votre frontiere de securite. Le projet OWASP API Security est une reference independante utile pour reflechir aux risques que porte une action exposee, et nous approfondissons le volet specifique aux agents dans securiser un serveur MCP.

Etape 3 : typer chaque entree avec un vrai schema

Une description d'outil indique a l'agent quel outil choisir. Le schema d'entree lui indique comment appeler cet outil correctement, et un schema precis est ce qui se dresse entre l'agent et un appel malforme. L'erreur est de typer les entrees de maniere lache, un sac de chaines optionnelles, parce que c'est facile a implementer et accepte tout. Un agent lit un schema lache comme l'autorisation d'envoyer n'importe quoi, et il le fera, y compris des arguments que votre endpoint ne peut pas utiliser.

Les entrees d'outils MCP sont decrites avec JSON Schema, le meme vocabulaire utilise dans tout le monde des API, si bien que les contraintes que vous pouvez exprimer sont bien comprises et bien documentees. Les pratiques qui font qu'un schema joue son role :

• Marquez les champs requis comme requis. Un agent lisant un schema tout optionnel ne sait pas quels arguments il doit fournir, et il peut donc omettre celui sans lequel votre action ne peut pas s'executer. Requis veut dire requis.
• Utilisez des enumerations pour les choix fixes. Si un statut ne peut etre que draft, sent ou paid, faites-en une enumeration. L'agent choisira dans la liste au lieu d'inventer une quatrieme valeur que votre endpoint rejette.
• Contraignez les formats et les plages. Indiquez qu'un champ est une date dans un format precis, un e-mail, ou un entier dans une plage. L'agent respecte la contrainte, et vous interceptez une mauvaise entree avant qu'elle n'atteigne votre action.
• Decrivez chaque champ. Une description d'une ligne sur un parametre, et pas seulement sur l'outil, indique a l'agent ce que signifie le champ, pour qu'il relie l'intention de l'utilisateur au bon argument.
• Evitez les blocs libres la ou existe une structure. Une seule chaine data qui attend secretement du JSON force l'agent a deviner votre forme interne. Modelisez plutot les vrais champs.

Un rapide contraste entre un parametre lache et un parametre serre :

Pour comprendre ce que JSON Schema peut exprimer, la reference JSON Schema est la source faisant autorite, et sa section sur les contraintes d'objet couvre directement les champs requis et le typage des proprietes. Un schema qui dit exactement a quoi ressemble un appel valide transforme la tache de l'agent : de "deviner une forme que mon endpoint pourrait accepter" en "remplir des champs que le schema a deja contraints", ce qui fait la difference entre un appel qui fonctionne et un appel qui rebondit.

Etape 4 : delimiter le perimetre aux taches qui comptent

Plus d'outils, ce n'est pas plus de capacite. Au-dela d'un petit nombre, plus d'outils, c'est plus de confusion, car chaque outil ajoute est une option de plus que l'agent doit envisager et une chance de plus qu'il choisisse le mauvais. L'erreur est d'exposer tout ce que votre API sait faire, en partant du principe que l'exhaustivite est une generosite. Pour un agent, un ensemble d'outils plus reduit et plus net, couvrant les taches qui comptent, est bien plus utilisable qu'un ensemble exhaustif qui enterre les actions importantes parmi les rares.

Quelques principes pour garder le perimetre delimite :

• Partez des taches, pas des endpoints. Listez ce qu'un utilisateur demanderait reellement a un agent de faire avec votre produit, et exposez des outils pour cela. Un endpoint auquel aucune requete utilisateur ne correspond n'a pas besoin d'etre un outil.
• Fusionnez les quasi-doublons. Si trois endpoints ne different que par un parametre, envisagez un seul outil avec ce parametre plutot que trois outils entre lesquels l'agent doit choisir.
• Laissez de cote les actions rares ou dangereuses, au debut. Vous n'avez pas a tout exposer le premier jour. Commencez par les taches a forte valeur et faible risque, et ajoutez-en a mesure que vous voyez comment les agents utilisent la surface.
• Regroupez clairement les outils lies. Un nommage coherent et des descriptions qui se referencent entre elles aident l'agent a voir quels outils fonctionnent ensemble, pour qu'une tache en plusieurs etapes se lise comme une sequence plutot que comme un tas d'options.

C'est la meme concentration que nous recommandons au moment de choisir ce qu'il faut exposer, traitee dans MCP pour le SaaS : la premiere surface devrait etre le plus petit ensemble d'outils qui permet a un agent de faire quelque chose de reellement utile, pas un miroir mecanique de toute votre API. Une surface serree facilite aussi toutes les autres parties de ce guide, car il y a moins de noms a garder distincts, moins de descriptions a desambiguiser, et moins de schemas a reussir. Le perimetre n'est pas une limite dont vous vous excusez. C'est ce qui rend fiables les outils que vous exposez.

Etape 5 : relier chaque outil a une action claire

La derniere etape est celle ou la definition rencontre la realite : chaque outil doit correspondre a une action reelle qui fait exactement ce que la description promet. La defaillance ici est l'outil polyvalent, celui qui fait plusieurs choses differentes selon un indicateur de mode ou la forme de son entree, parce qu'il permet de couvrir beaucoup de cas avec une seule definition. Un agent ne peut pas raisonner proprement sur un outil dont le comportement change selon un interrupteur cache. Il choisit l'outil, regle mal l'indicateur, et obtient un resultat qu'il n'attendait pas.

La correction est : un outil, une tache. Un outil nomme update_order_status devrait mettre a jour le statut d'une commande et rien d'autre. Si vous devez aussi annuler des commandes, c'est cancel_order, un outil separe avec sa propre description et son propre schema, meme si les deux touchent le meme enregistrement par-dessous. L'agent raisonne par taches, et un outil par tache est ce qui lui permet de planifier une sequence : chercher la commande, verifier son statut, la mettre a jour, et les noms rendent chaque etape evidente.

Relier chaque outil a une action claire signifie aussi etre honnete dans la description au sujet des effets de bord. Si un outil envoie un e-mail, debite une carte ou supprime des donnees, la description doit le dire, car l'agent, et toute etape d'approbation humaine devant lui, doit connaitre le rayon d'impact avant l'appel. Un outil en lecture seule et un outil qui deplace de l'argent ne devraient jamais se ressembler dans vos definitions. C'est ici que la conception d'outils et la securite se rejoignent : plus la correspondance entre l'outil et l'action reelle est claire, plus il est facile de poser les bons garde-fous sur les actions qui en ont besoin, ce que nous traitons dans securiser un serveur MCP. Un outil auquel un agent peut se fier est un outil dont la definition dit la verite sur ce que l'appeler produit.

Erreurs frequentes, et comment les corriger

Nommer les outils d'apres les endpoints ou les services internes. La correction : nommez l'action et l'objet dans le langage de l'utilisateur, comme create_invoice, pas post_v2_billing. L'agent choisit les outils en raisonnant sur la tache, et un nom qui decrit la tache est celui qu'il peut choisir.

Des descriptions qui ne font que reformuler le nom. La correction : dites ce que fait l'outil, quand l'utiliser, quand ne pas l'utiliser, et ce qu'il renvoie, ecrit pour quelqu'un qui n'a jamais vu votre produit. Une description vague est la raison la plus frequente pour laquelle un agent choisit le mauvais outil.

Des schemas d'entree laches, tout optionnels. La correction : marquez les champs requis, utilisez des enumerations pour les choix fixes, contraignez les formats et decrivez chaque parametre. Un agent lit un schema lache comme l'autorisation d'envoyer n'importe quoi, et il le fera.

Exposer chaque endpoint comme un outil. La correction : delimitez le perimetre aux taches que les utilisateurs demandent vraiment, fusionnez les quasi-doublons et laissez de cote au debut les actions rares ou dangereuses. Plus d'outils au-dela d'un petit nombre, c'est plus de confusion, pas plus de capacite.

Des outils polyvalents avec un indicateur de mode. La correction : un outil, une tache, meme si plusieurs outils touchent le meme enregistrement par-dessous. Un agent ne peut pas raisonner proprement sur un outil dont le comportement change selon un interrupteur cache.

Cacher les effets de bord de la description. La correction : dites clairement quand un outil envoie, debite ou supprime, pour que l'agent et toute etape d'approbation connaissent le rayon d'impact. Un outil en lecture seule et un outil destructeur ne devraient jamais se ressembler.

FAQ

Que voit exactement un agent quand il considere un outil ? Le nom de l'outil, sa description et son schema d'entree, et en pratique rien d'autre au moment de choisir. Il n'a pas votre code source, ni votre documentation d'API complete, ni un moyen de poser une question de clarification. Il relie la requete de l'utilisateur a l'un de vos outils a partir de ces trois elements, puis remplit les arguments depuis le schema. C'est pourquoi les trois doivent etre sans ambiguite par eux-memes : ils sont toute l'interface sur laquelle l'agent raisonne.

Quelle longueur doit avoir une description d'outil ? Assez longue pour dire ce que fait l'outil, quand l'utiliser, quand ne pas l'utiliser s'il existe un voisin proche, et ce qu'il renvoie, et pas davantage. Une seule phrase reformulee est trop courte pour desambiguiser ; une page de prose enterre le signal. Visez quelques phrases claires qui permettraient a un inconnu competent de choisir le bon outil pour une requete decrite du premier coup. Si un inconnu hesiterait, l'agent hesitera aussi.

Pourquoi le typage des entrees compte-t-il autant pour un agent ? Parce que l'agent genere les arguments, et un schema lache lui permet de generer des arguments que votre action ne peut pas utiliser. Les champs requis, les enumerations, les contraintes de format et les descriptions par champ resserrent tous ce que l'agent peut envoyer vers ce que votre endpoint accepte. Un schema serre transforme l'appel d'une devinette en un remplissage de cases, ce qui fait la difference entre un appel qui reussit et un appel que votre endpoint rejette, ou pire, traite mal en silence.

Combien d'outils un serveur MCP devrait-il exposer ? Moins que vous ne le pensez, surtout au debut. Partez des taches que les utilisateurs demanderaient reellement a un agent de faire avec votre produit, exposez un outil pour chacune, et laissez le reste de cote jusqu'a ce que vous voyiez l'usage reel. Un petit ensemble d'outils nets et distincts est plus facile a choisir pour un agent qu'un grand ensemble qui copie toute votre API, ou les actions importantes sont enterrees parmi les rares. Vous pourrez toujours en ajouter.

Un seul outil devrait-il gerer plusieurs actions liees pour reduire le nombre ? Non. Reduire le nombre en surchargeant un seul outil avec un indicateur de mode echange une liste plus courte contre une liste plus confuse. Un agent raisonne par taches, et un outil dont le comportement change selon un interrupteur cache est un outil qu'il regle mal. Un outil, une tache est la regle, meme quand plusieurs outils touchent le meme enregistrement par-dessous, car une correspondance claire est ce qui permet a l'agent de planifier une tache en plusieurs etapes.

Quel rapport les definitions d'outils ont-elles avec la securite ? Un rapport etroit. Chaque outil est une action reelle qu'un agent peut invoquer, donc plus la correspondance entre l'outil et son effet est claire, plus il est facile de poser les bons controles sur les actions qui en ont besoin, comme des approbations sur les ecritures et des limites sur les donnees qui reviennent. Les descriptions honnetes des effets de bord en font partie, car une etape d'approbation ne peut proteger que ce qu'elle voit. Nous couvrons les controles specifiques aux agents dans securiser un serveur MCP.

Pour aller plus loin

• Specification du Model Context Protocol pour la definition de reference, a jour, de la maniere dont les outils et les serveurs sont decrits.
• Documentation du Model Context Protocol sur les outils pour la maniere dont le nom, la description et le schema d'entree d'un outil s'articulent.
• Reference JSON Schema pour le vocabulaire que vous employez afin de typer les entrees d'outils.
• Reference JSON Schema des objets pour les champs requis et le typage des proprietes en particulier.
• Projet OWASP API Security pour la perspective de securite sur l'exposition d'actions, puisque chaque outil est une action avec un rayon d'impact.

En bref

Un agent ne voit que le nom, la description et le schema d'entree de votre outil, ces trois elements sont donc toute l'interface et meritent un vrai soin. Nommez chaque outil pour la tache qu'il accomplit dans le langage de l'utilisateur, comme create_invoice, pas pour l'endpoint sur lequel il repose, car l'agent choisit en raisonnant sur la tache. Ecrivez la description pour un inconnu competent : ce que fait l'outil, quand l'utiliser, quand ne pas l'utiliser, et ce qu'il renvoie, puisqu'une description vague est la premiere raison pour laquelle un agent choisit le mauvais outil. Typez chaque entree avec un vrai schema, champs requis, enumerations, formats, descriptions par champ, car l'agent genere les arguments et un schema lache en appelle de mauvais. Delimitez le perimetre aux taches qui comptent plutot que de copier toute votre API, puisque plus d'outils au-dela d'un petit nombre, c'est plus de confusion, pas plus de capacite. Reliez chaque outil a exactement une action claire, effets de bord enonces honnetement, pour que l'agent puisse planifier une sequence et que toute etape d'approbation voie le rayon d'impact. Reussissez cela et l'agent choisit le bon outil et l'appelle correctement du premier coup, ce qui est tout l'enjeu.

Si vous voulez de l'aide pour concevoir une surface MCP que les agents savent utiliser de maniere fiable, un Partner Audit examine votre API, vos definitions d'outils et votre surface destinee aux agents, puis vous remet un plan concret de ce qu'il faut exposer et comment le definir.