Concevoir : cas d'usage et outils — Apps SDK et plugins ChatGPT — serveurs MCP et interfaces

Leçon réécrite le 3 novembre 2026 d’après les pages Brainstorm plugin use cases et Define tools de la documentation Plugins d’OpenAI. L’ancienne leçon installait un paquet @openai/apps-sdk et un manifeste chatgpt-app.json qui n’existent pas ; l’installation des vrais outils (SDK MCP officiels) se fait à la leçon 4. Sources : Brainstorm plugin use cases · Define tools.

Partir des attentes, pas de l’API

La documentation d’OpenAI fait commencer un plugin avant la première ligne de code : par la liste de ce que les gens attendront de lui. Le nom du plugin, sa description, ses skills, ses outils et le produit auquel il se rattache créent des attentes ; l’implémentation doit y répondre, ou avoir une raison délibérée de ne pas le faire.

Imaginez quelqu’un qui a installé votre plugin sans lire sa documentation. Que lui demandera-t-il ? Pour le savoir, puisez dans les tâches que vos utilisateurs accomplissent déjà dans votre produit, dans les demandes au support, les recherches, les demandes de fonctionnalités, le vocabulaire qu’ils emploient, les contournements qui les obligent à copier des données d’un outil à l’autre. Notez les demandes directes, qui nomment le plugin, et les demandes indirectes, qui énoncent seulement l’objectif : un plugin de gestion de projets doit traiter « Affiche le tableau du lancement Acme » comme « Qu’est-ce qui bloque le lancement ? ».

Ne limitez pas cet inventaire à ce que votre API sait déjà faire. Recensez d’abord les attentes, comparez-les ensuite à ce que vous pouvez fournir de façon sûre et fiable.

L’inventaire des cas d’usage

Pour chaque cas d’usage, OpenAI propose de répondre à sept questions :

Champ	Question
Objectif	Que cherche à accomplir la personne ?
Exemples de demandes	Comment le formulerait-elle, directement ou non ?
Résultat attendu	Qu’est-ce qui rendrait l’échange réussi ?
Contexte requis	Quelles informations, quel accès au compte, quel état préalable ?
Capacité	Une skill suffit-elle, ou faut-il un outil MCP ?
Limite de sécurité	Peut-il exposer des données, modifier un état, dépenser de l’argent, toucher un tiers ?
Décision	Première version, plus tard, ou exclusion volontaire ?

Regroupez les demandes qui partagent un objectif : « Liste mes tâches ouvertes », « Qu’ai-je à faire aujourd’hui ? » et « Montre le travail en retard » relèvent sans doute d’un même cas d’usage de revue des tâches, avec des filtres différents.

Puis vérifiez la couverture. Chaque cas retenu doit avoir un chemin complet de la demande au résultat ; les écritures doivent prévoir autorisation et confirmation ; et le plugin doit savoir dire ce qu’il ne fait pas en proposant une suite utile. Un plugin qui permet de créer des projets sans permettre de les lister, de les consulter ni de les modifier promet plus qu’il ne tient : complétez-le, ou resserrez son positionnement.

Exclure, et l’écrire

Vous n’avez pas à tout implémenter, mais chaque exclusion importante mérite une raison : un risque inacceptable pour la sécurité ou la vie privée, une API qui ne le permet pas de façon fiable, des permissions invérifiables, un résultat trompeur faute d’informations, ou un périmètre de première version que la fiche du plugin annonce clairement. Consignez ces décisions : elles nourrissent les limites des skills, les descriptions d’outils, les refus, les tests et le texte de la fiche publique.

Des cas d’usage aux outils

Un outil doit servir un objectif d’utilisateur. Ne recopiez pas votre API interne telle quelle. Pour chaque cas retenu, écrivez le résultat attendu, listez les informations nécessaires, repérez les lectures, écritures et actions externes, regroupez ce qui forme une action cohérente — et séparez ce qui diffère par les permissions, le risque ou le besoin de confirmation.

L’exemple d’OpenAI pour un plugin de projets :

list_projects pour trouver des projets ;
get_project pour en examiner un ;
create_project pour en créer un ;
update_project pour en modifier les détails ;
archive_project pour un changement d’état lourd de conséquences.

Lectures et écritures sont séparées, pour que le modèle et l’utilisateur distinguent ce qui consulte de ce qui modifie.

Le contrat de chaque outil

Champ	À définir
Nom	Un identifiant stable, orienté action
Titre	Une action concise, lisible par un humain
Description	L’objectif de l’utilisateur et les conditions qui doivent déclencher l’outil
Schéma d’entrée	Paramètres obligatoires et facultatifs, types, valeurs permises, limites
Schéma de sortie	Champs structurés que le modèle peut examiner et réutiliser
Autorisation	Le compte, le rôle ou l’accès que le serveur doit vérifier
Effets de bord	Les données ou l’état externe que l’outil peut modifier
Échecs	Les erreurs que le modèle peut expliquer ou rattraper

Trois règles complètent ce tableau. Des entrées explicites : ne comptez pas sur le modèle pour deviner un identifiant ou une portée de compte. Des résultats réutilisables : renvoyez des identifiants stables et assez d’informations pour l’appel suivant. Des résultats propres : ni secrets, ni jetons d’accès, ni diagnostics internes, ni données personnelles inutiles.

Des descriptions écrites pour être choisies

Le modèle choisit ses outils sur leur description : décrivez l’intention de l’utilisateur, pas l’implémentation. Une bonne description dit ce que fait l’outil, quand s’en servir, en quoi il diffère de ses voisins, et quelles sont ses limites ou ses prérequis. Évitez celles qui répètent le nom de l’outil ou emploient un jargon interne que vos utilisateurs ignorent.

Les annotations de sécurité

Chaque outil porte des annotations, à fixer d’après son comportement réel :

readOnlyHint vaut true seulement si l’outil ne peut modifier aucun état ;
destructiveHint vaut true si l’outil peut produire un résultat irréversible ou difficile à défaire ;
openWorldHint vaut true si l’outil accède à l’internet public ou à des entités externes ouvertes, même en lecture seule comme une recherche web. Un compte ou un espace de travail privé et délimité n’est pas « ouvert » du seul fait d’être hébergé ailleurs.

Les annotations aident ChatGPT et Codex à choisir le bon niveau de confirmation, mais elles ne remplacent ni l’autorisation côté serveur, ni la validation des entrées, ni la confirmation des actions importantes.

Un plan qui sert de plan de test

Gardez l’inventaire et le plan d’outils : ils deviennent votre liste de contrôle. Ajoutez-y des demandes directes, indirectes, limites et hors périmètre, et vérifiez que le plugin fini se comporte comme prévu sur chacune. Cherchez aussi les outils qui ne servent aucun cas documenté, les lectures manquantes avant une écriture, et les descriptions trop proches qui pourraient faire hésiter le modèle.

Points clés à retenir

Partez de ce que les utilisateurs attendront, puis comparez à ce que vous pouvez fournir de façon sûre
Un inventaire en sept questions par cas d’usage, exclusions volontaires comprises
Un outil par action cohérente ; lectures et écritures séparées
Un contrat par outil : nom, titre, description, schémas, autorisation, effets de bord, échecs
Les annotations (readOnlyHint, destructiveHint, openWorldHint) suivent le comportement réel et ne remplacent pas l’autorisation