Les outils donnent à ChatGPT et à Codex accès aux actions et aux données que propose le serveur MCP d’un plugin. Définissez-les après avoir exploré les cas d’usage et avant d’implémenter le serveur.
Chaque outil doit aider l’utilisateur à atteindre un objectif. Avant de reproduire une API interne, réfléchissez à la façon dont les utilisateurs formuleront leurs demandes et utiliseront la fonctionnalité.
Associez les cas d’usage aux outils
Pour chaque cas d’usage pris en charge :
- Décrivez le résultat attendu par l’utilisateur.
- Listez les informations nécessaires pour obtenir ce résultat.
- Identifiez les opérations de lecture ou d’écriture et les actions externes que le serveur doit effectuer.
- Regroupez les opérations qui forment une seule action cohérente.
- Séparez les opérations si elles nécessitent des autorisations différentes, présentent des risques distincts ou exigent des confirmations différentes.
Par exemple, un plugin de gestion de projets pourrait proposer les outils suivants :
list_projectspour trouver des projets.get_projectpour consulter un projet en particulier.create_projectpour créer un projet.update_projectpour modifier les informations d’un projet.archive_projectpour changer l’état d’un projet, avec des conséquences importantes.
Séparez les opérations de lecture et d’écriture pour que le modèle et l’utilisateur puissent distinguer la consultation d’informations des actions qui modifient l’état du système.
Définissez le contrat de chaque outil
Pour chaque outil envisagé, consignez les éléments suivants :
| Champ | Éléments à définir |
|---|---|
| Nom | Un identifiant stable qui indique l’action effectuée. |
| Titre | Un libellé court qui décrit clairement l’action. |
| Description | L’objectif de l’utilisateur et les conditions dans lesquelles le modèle doit appeler l’outil. |
| Schéma d’entrée | Les paramètres obligatoires et facultatifs, leurs 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 d’un système 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 laissez pas le modèle deviner les identifiants, le périmètre du compte ou d’autres valeurs indispensables au bon fonctionnement de l’outil.
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 informations de diagnostic internes et les données personnelles superflues.
Rédigez des descriptions qui facilitent le choix de l’outil
Le modèle s’appuie sur les descriptions des outils pour déterminer lequel convient à une demande. Décrivez l’intention de l’utilisateur plutôt que les détails d’implémentation.
Pour chaque description :
- Indiquez ce que fait l’outil.
- Expliquez quand l’utiliser.
- Précisez ce qui le distingue des outils similaires.
- Signalez les limites ou les prérequis importants.
Évitez les descriptions qui se contentent de reformuler le nom de l’outil ou qui reprennent des termes propres à vos services internes que les utilisateurs ne connaissent pas.
Prévoyez les annotations de sécurité
Attribuez les annotations en fonction du comportement réel de l’outil. Consultez le schéma MCP ToolAnnotations pour connaître les définitions de référence, les valeurs par défaut et les interactions entre les indications suivantes :
readOnlyHintvauttrueuniquement si l’outil ne peut pas modifier l’état du système.destructiveHintvauttruesi l’outil peut avoir des effets irréversibles ou difficiles à annuler.openWorldHintvauttruesi l’outil accède à l’Internet public ou à un ensemble non délimité d’entités externes, y compris par des actions en lecture seule comme la recherche web. Le simple fait qu’un compte privé ou un espace de travail privé au périmètre défini soit hébergé à l’extérieur ne suffit pas à en faire un environnement ouvert.
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 les cas couverts et les limites des outils
Comparez les outils proposés à l’inventaire complet des cas d’usage :
- Vérifiez que, pour chaque cas d’usage pris en charge, les outils permettent d’obtenir un résultat utile.
- Repérez les outils qui ne répondent à aucun cas d’usage 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, face à une demande non prise en charge, le système explique clairement ses limites au lieu de fournir un résultat approximatif qui présente un risque.
- Testez le choix entre deux outils similaires pour vérifier si leurs descriptions se recoupent au point de prêter à confusion.
Conservez le plan des outils ainsi obtenu et utilisez-le comme liste de contrôle pour l’implémentation et l’évaluation. Ensuite, créez le serveur MCP et testez chaque contrat avec des entrées représentatives, invalides et non autorisées.