Les outils sont les actions et les données que le serveur MCP d’un plugin expose à ChatGPT et à Codex. Définissez-les après avoir exploré les cas d’utilisation et avant d’implémenter le serveur.
Chaque outil doit aider l’utilisateur à atteindre un objectif. Ne reproduisez pas une API interne sans réfléchir à la façon dont les utilisateurs demanderont et utiliseront la fonctionnalité.
Associez les cas d’utilisation aux outils
Pour chaque cas d’utilisation pris en charge :
- Décrivez le résultat attendu par l’utilisateur.
- Dressez la liste des informations nécessaires pour obtenir ce résultat.
- Identifiez les opérations de lecture, d’écriture ou les actions externes que le serveur doit effectuer.
- Regroupez les opérations qui constituent une seule action cohérente.
- Séparez les opérations lorsque leurs autorisations, leurs risques de sécurité ou leurs exigences de confirmation diffèrent.
Par exemple, un plugin de gestion de projets pourrait exposer :
list_projectspour trouver des projets.get_projectpour examiner un projet.create_projectpour créer un projet.update_projectpour modifier les détails d’un projet.archive_projectpour effectuer un changement d’état aux conséquences importantes.
Séparez les opérations de lecture et d’écriture afin que le modèle et l’utilisateur puissent distinguer la récupération d’informations des actions qui modifient l’état.
Définissez chaque contrat
Consignez les éléments suivants pour chaque outil proposé :
| Champ | Éléments à définir |
|---|---|
| Nom | Un identifiant stable qui exprime une action. |
| Titre | Un libellé d’action concis et compréhensible. |
| Description | L’objectif de l’utilisateur et les conditions qui doivent déclencher l’outil. |
| Schéma d’entrée | Les paramètres obligatoires et facultatifs, les types, les valeurs autorisées et les limites. |
| Schéma de sortie | Les champs structurés que le modèle peut examiner et réutiliser. |
| Autorisation | Le compte, le rôle ou les droits d’accès aux ressources que le serveur doit vérifier. |
| Effets de bord | Les données ou l’état externe que l’outil peut modifier. |
| Comportement en cas d’échec | Les erreurs que le modèle peut expliquer ou dont il peut se remettre. |
Utilisez des entrées explicites. Ne comptez pas sur le modèle pour deviner les identifiants, le périmètre du compte ou d’autres valeurs nécessaires au bon fonctionnement.
Renvoyez des identifiants stables et suffisamment d’informations structurées pour les appels suivants. Excluez des résultats les secrets, les jetons d’accès, les diagnostics internes et les données personnelles superflues.
Rédigez des descriptions qui guident la sélection
Le modèle s’appuie sur les descriptions des outils pour déterminer si un outil convient à une demande. Décrivez l’intention de l’utilisateur, pas l’implémentation.
De bonnes descriptions :
- Indiquent ce que fait l’outil.
- Expliquent quand l’utiliser.
- Le distinguent des outils similaires.
- Signalent les limites ou les prérequis importants.
Évitez les descriptions qui se contentent de reformuler le nom de l’outil ou qui emploient une terminologie propre aux services internes que les utilisateurs ne connaissent pas.
Prévoyez les annotations de sécurité
Attribuez les annotations en fonction du comportement réel. Consultez le
schéma
ToolAnnotations de MCP
pour connaître les définitions de référence, les valeurs par défaut et les interactions entre ces indications :
readOnlyHintvauttrueuniquement lorsque l’outil ne peut pas modifier l’état.destructiveHintvauttruelorsque l’outil peut avoir des effets irréversibles ou difficiles à annuler.openWorldHintvauttruelorsque l’outil accède à l’Internet public ou à des entités externes sans périmètre prédéfini, y compris par des actions en lecture seule comme la recherche web. Un compte ou un espace de travail privé au périmètre délimité ne constitue pas un environnement ouvert du seul fait qu’il est hébergé à l’extérieur.
Les annotations ne remplacent ni les contrôles d’autorisation côté serveur, ni la validation des entrées, ni la confirmation des actions aux conséquences importantes.
Vérifiez la couverture et les limites
Comparez les outils proposés à l’inventaire complet des cas d’utilisation :
- Confirmez que chaque cas d’utilisation pris en charge permet d’aboutir à un résultat utile.
- Identifiez les outils qui ne répondent à aucun cas d’utilisation documenté.
- Repérez les opérations de lecture manquantes dont les utilisateurs ont besoin avant d’effectuer une opération d’écriture.
- Vérifiez que les demandes non prises en charge donnent lieu à une explication claire de la limite rencontrée plutôt qu’à une approximation risquée.
- Testez si les descriptions de deux outils similaires se recoupent au point de rendre leur sélection ambiguë.
Conservez le plan des outils ainsi obtenu comme liste de contrôle pour l’implémentation et l’évaluation. Ensuite, développez le serveur MCP et testez chaque contrat avec des entrées représentatives, invalides et non autorisées.