Des descriptions d'outils MCP qui empêchent les erreurs en production

Une description d'outil MCP peut empêcher un appel dangereux vers la production avant même son lancement, ou dissimuler le risque derrière un verbe rassurant. La plupart des actions accidentelles en production ne commencent pas par la décision d'un agent de causer un dommage. Elles commencent lorsqu'une description vague donne à un outil destructeur l'apparence d'un outil d'inspection.

Rédigez la description de chaque outil qui modifie un état comme un petit contrat opérationnel : nommez le système cible, indiquez l'effet secondaire et précisez l'exigence de confirmation. Si l'un de ces éléments manque, la description demande au modèle de deviner une limite de sécurité que votre code aurait dû rendre explicite.

J'ai examiné suffisamment d'interfaces d'action pour me méfier de libellés comme « manage », « sync », « deploy » et « cleanup ». Ils sont pratiques pour leur auteur et coûteux pour la personne qui devra expliquer pourquoi une demande de test a abouti dans un compte actif. Une bonne description rend les détails gênants impossibles à manquer.

Une description d'outil est un avertissement d'exécution, pas un texte marketing

Les descriptions d'outils MCP doivent dire à l'agent et à l'opérateur humain ce qui se passera si l'appel réussit. Elles ne doivent pas vendre la capacité, résumer un sous-système interne ni répéter le nom de l'outil dans une phrase plus longue.

Le schéma d'outil du Model Context Protocol comprend une description lisible par les humains, לצד du nom de l'outil et de inputSchema. La spécification MCP autorise aussi des annotations comme readOnlyHint et destructiveHint. Ces annotations aident un client à présenter les outils, mais la spécification précise que les clients doivent les traiter comme des indications. Ce ne sont pas des contrôles d'autorisation. La description reste donc l'endroit où l'opérateur peut lire la conséquence réelle avant que l'appel n'atteigne votre service.

Considérez ces deux définitions :

{
  "name": "delete_backup",
  "description": "Deletes a backup.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": { "type": "string" }
    },
    "required": ["backup_id"]
  }
}

{
  "name": "delete_production_backup",
  "description": "Permanently deletes one backup from the Production PostgreSQL backup store. This removes a recovery point and cannot be undone. Ask the user to confirm the backup ID and its timestamp before calling this tool.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": {
        "type": "string",
        "description": "Immutable backup ID returned by list_production_backups."
      }
    },
    "required": ["backup_id"],
    "additionalProperties": false
  },
  "annotations": {
    "destructiveHint": true,
    "readOnlyHint": false
  }
}

La seconde définition ne se contente pas de paraître prudente. Elle donne à l'agent une cible, un résultat irréversible, un moyen d'identifier l'objet sans risque et une pause conversationnelle obligatoire. Elle fournit aussi au réviseur assez d'informations pour refuser un appel avant d'examiner les détails de l'implémentation.

Ne supposez pas qu'un verbe plus fort suffira. « Destroy » avertit mieux que « delete », mais ne dit toujours rien du compte concerné, de la catégorie de données ni de la façon dont l'outil gère la confirmation. C'est à la description de fournir ce contexte.

Placez le système cible dans la première phrase

La première phrase doit identifier le système exact concerné, y compris l'environnement ou la limite du compte. Une action contre « la base de données » peut viser un conteneur local jetable, un service de test partagé, un tenant de préproduction ou le registre client de production. Ce sont des actions différentes, même si le point d'accès de l'API est identique.

Utilisez des noms que l'opérateur reconnaît dans son travail. Dites « compte de paiements de production », « cluster Kubernetes de préproduction », « tenant client northwind » ou « branche de publication du dépôt mobile-api ». Évitez les surnoms internes, sauf si tous les opérateurs concernés les connaissent et si le nom apparaît dans les arguments.

Cet ordre fonctionne parce qu'il place le risque avant la mécanique :

[Système cible]. [Action et résultat]. [Règle de confirmation].

Par exemple :

Répertoire d'identités de production. Désactive le compte utilisateur sélectionné et ferme les sessions actives. Demandez à l'utilisateur de confirmer le nom d'utilisateur avant l'appel.

La cible doit correspondre au gestionnaire, pas à l'intention de l'auteur. Si l'outil accepte un argument environment, une description affirmant « Met à jour la préproduction » devient fausse dès qu'un appelant transmet production. Séparez alors l'opération en outils propres à chaque environnement ou indiquez clairement ce que l'argument autorise.

Une séparation est généralement plus facile à exploiter :

list_staging_feature_flags
set_staging_feature_flag
list_production_feature_flags
request_production_feature_flag_change

Cette conception peut sembler répétitive. La répétition coûte moins cher qu'un sélecteur d'outil qui décide que set_feature_flag convient, puis découvre seulement après coup qu'un argument facultatif pointait vers la production.

Les noms méritent la même discipline, mais ils ne peuvent pas porter tout l'avertissement. Les listes d'outils tronquent les noms. Les agents se concentrent parfois sur une description en choisissant entre des noms proches. Sous pression, les humains parcourent les deux. Placez la cible aux deux endroits lorsque c'est possible, puis rendez la description complète même si le nom disparaît de l'écran.

Il existe une exception : un outil qui reçoit une URI de ressource immuable dont l'hôte fixe déjà l'environnement. Même dans ce cas, indiquez l'hôte ou la catégorie de compte dans la description. Un UUID ne dit pas à un humain s'il identifie un enregistrement de développement ou un client réel.

Décrivez l'effet secondaire comme un résultat obtenu

Une description sûre indique à quoi ressemble le monde après la réussite de l'appel. Cela oblige l'auteur à distinguer une observation d'une modification, un changement réversible d'un changement définitif, et une demande de son exécution.

Comparez le verbe vague « manage » :

Manages service deployments.

Il dissimule plusieurs résultats très différents. Un outil de déploiement peut créer une publication, promouvoir une publication existante, redémarrer des instances, modifier la répartition du trafic, annuler du code ou simplement récupérer un état. Chaque opération mérite son propre outil lorsqu'elle présente un mode d'échec ou une règle d'approbation différente.

Employez plutôt un résultat explicite :

Creates a deployment request for the Production catalog service. It does not change running instances. A release manager must approve the request in the deployment system.

Ou :

Changes Production catalog traffic so the specified release receives 100 percent of requests. Existing requests may finish on the prior release. Ask the user to confirm the release version before calling.

La différence entre créer une demande et l'exécuter compte davantage que la différence entre HTTP POST et PATCH. Un objet de demande peut tout de même créer du travail, consommer un quota ou notifier des personnes, alors décrivez aussi cet effet secondaire. Mais ne le présentez pas comme un déploiement actif s'il ouvre seulement un élément d'approbation.

Évitez les euphémismes. « Retire » peut signifier archiver, désactiver, supprimer ou mettre fin à une facturation. « Nettoie » peut signifier retirer des fichiers temporaires ou supprimer l'unique copie conservée d'un export client. Écrivez le verbe et l'objet réels : supprime, désactive, renouvelle, promeut, transfère, envoie, facture ou publie.

Pour les opérations dont l'effet est différé, indiquez le délai. Une modification DNS peut se propager après le retour de l'API. La suppression d'un utilisateur peut bloquer les accès futurs tout en conservant les journaux d'audit. La rotation d'un credential peut invalider les clients qui utilisent encore l'ancien secret. L'agent a besoin de ce contexte pour décider s'il doit d'abord examiner les systèmes dépendants.

Les descriptions doivent aussi mentionner l'étendue matérielle lorsqu'un seul appel concerne de nombreux objets. « Supprime l'enregistrement sélectionné » est différent de « Supprime tous les enregistrements correspondant à la requête fournie ». Un endpoint par lots caché derrière un verbe au singulier crée des problèmes prévisibles.

Le langage de confirmation doit décrire un véritable contrôle

Une phrase de confirmation n'est utile que si l'implémentation et le processus opérationnel la respectent. Écrire « confirmation requise » sur un outil dont le gestionnaire s'exécute immédiatement relève du théâtre, et les agents finiront par le révéler.

Il existe trois modèles distincts, et les descriptions doivent nommer celui que vous utilisez réellement.

1. L'agent demande confirmation à l'utilisateur dans sa propre conversation, puis appelle l'action. Cela dépend du respect de la description par l'agent et n'arrête pas un client modifié ou imprudent.
2. L'outil crée une demande destinée à une autre personne ou à un autre système pour approbation. L'appel a lui-même un effet secondaire, mais la modification de production décrite attend.
3. Une passerelle d'exécution interrompt l'action et exige une approbation humaine avant d'envoyer des credentials ou de contacter le système cible.

Ne réduisez pas ces modèles à « confirmation requise ». Ils offrent des protections et des éléments d'audit différents.

Utilisez des verbes qui indiquent l'acteur et le moment :

Before calling, ask the user to confirm the repository name and release tag.

Calling this tool submits a change request. The deployment system requires a release manager to approve it before any production release begins.

This action gateway asks a human to approve every call before it sends the request to the Production payments API.

La dernière formulation décrit une limite imposée. La première décrit une instruction destinée à l'agent. Les deux peuvent convenir, mais elles ne sont pas équivalentes.

Ne demandez jamais à l'agent d'obtenir une confirmation vague. Dites-lui quels faits la personne doit approuver. Pour une suppression, il peut s'agir du nom de la ressource, du compte et de la durée de conservation. Pour un transfert, de la source, de la destination, du montant et de la devise. Pour une publication, du service, de la version et de l'étendue du trafic. La description ne doit pas imposer un rituel, mais demander les faits qui permettent de repérer une mauvaise cible.

Une règle de confirmation a aussi besoin d'une portée. « Obtenir une approbation avant les changements de production » est faible lorsqu'une session peut exécuter dix appels après une seule approbation. Si le contrôle réel approuve un processus pendant toute sa durée de vie, indiquez-le dans la documentation du produit et ne prétendez pas que chaque appel bénéficie d'une pause individuelle.

Les affirmations de lecture seule échouent quand les gestionnaires effectuent un travail caché

Ne qualifiez un outil de lecture seule que si son gestionnaire ne modifie pas intentionnellement le système cible. Le terme décrit le comportement, pas la méthode HTTP, le nom d'une permission de base de données ou les espoirs de l'auteur.

Une requête GET peut renouveler une session, mettre à jour un champ de dernière consultation, générer un export, lancer une tâche de rapport ou déclencher un remplissage de cache dont le coût est réel. Une requête POST peut être inoffensive si elle évalue une simulation sans rien conserver. Examinez le gestionnaire et ses appels en aval avant de choisir le libellé.

L'annotation MCP readOnlyHint est utile pour un client qui veut réduire les frictions autour des outils d'inspection. Cela reste une indication, le serveur doit donc imposer sa propre limite. Plus important encore, la description doit préciser toute exception qui pourrait surprendre un opérateur.

Cette description est trompeuse :

Read-only tool for checking invoice status.

Elle échoue si l'endpoint crée un événement de consultation de document, renouvelle un token tiers ou démarre un calcul distant. Une formulation plus honnête serait :

Retrieves the current status of one Production invoice. It does not edit the invoice or charge the customer. The billing provider records this request in its access log.

Un journal d'accès est généralement acceptable pour une action d'inspection. Il devient important si la cible applique des règles de conformité, facture chaque récupération ou déclenche un workflow en réaction aux lectures. Indiquez ces effets sans transformer chaque description en notice juridique.

Séparez autant que possible les simulations de l'exécution. Un outil deploy doté d'un booléen dry_run réunit deux profils de sécurité dans une même définition. Les agents peuvent omettre une valeur par défaut, mal comprendre si le serveur la respecte ou réutiliser un payload sans le modifier. plan_production_deployment et execute_production_deployment rendent la distinction visible dans la sélection des outils, les journaux et les revues.

La même règle s'applique aux outils de validation. « Valider la configuration » semble sûr, mais certains fournisseurs allouent une ressource ou contactent une dépendance active pendant la validation. Si c'est le cas, décrivez l'opération comme une action et appliquez la règle de confirmation correspondante.

Un outil trop large crée des erreurs d'approbation

Les outils doivent regrouper les opérations selon leur conséquence et leur limite d'approbation communes, pas selon la commodité d'un client d'API unique. Un outil d'administration général transforme les descriptions en catalogue d'exceptions qu'un modèle ou un humain ne lira jamais de façon fiable.

Voici le modèle à éviter :

{
  "name": "admin",
  "description": "Administer users, deployments, secrets, and configuration across environments.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": { "type": "string" },
      "environment": { "type": "string" },
      "payload": { "type": "object" }
    },
    "required": ["operation", "environment", "payload"]
  }
}

Cette définition détruit l'unité utile de revue. Un réviseur ne peut pas savoir depuis la fiche de l'outil si l'appel récupérera un état, renouvellera des credentials ou supprimera un utilisateur. La chaîne operation déplace la sémantique importante dans un argument tardif, facile à négliger.

Séparez plutôt les outils selon l'intention et le risque :

get_production_deployment_status
plan_production_deployment
submit_production_deployment_request
rotate_production_service_credential
create_production_user_access_request

Vous n'avez pas besoin d'un outil pour chaque endpoint. Il vous faut des outils distincts lorsque la cible, l'effet secondaire ou la confirmation change. Un outil par lots peut rester un outil par lots s'il touche toujours le même type de ressource délimité et exige toujours la même approbation. Sa description doit indiquer qu'il peut concerner plusieurs objets et montrer comment l'appelant limite la sélection.

Les arguments ont eux aussi besoin de descriptions. La description de l'outil explique ce que fait l'opération, les descriptions des arguments limitent les choix dangereux. Utilisez des énumérations pour les environnements et les types d'action lorsque c'est possible. Rejetez les valeurs inconnues côté serveur. Ne placez pas « production » dans une chaîne libre en espérant que la description vous protège.

Un outil précis produit aussi de meilleurs enregistrements d'audit. Quand le journal indique rotate_production_service_credential, l'enquêteur comprend la catégorie d'action avant d'ouvrir les arguments. Quand il indique admin, il doit reconstituer l'intention à partir d'un payload.

Rédigez la description avant le gestionnaire

Rédiger le contrat opérationnel avant l'implémentation révèle les exigences vagues tant que la modification de l'interface reste peu coûteuse. Si vous ne pouvez pas écrire une phrase simple sur le résultat obtenu, la limite de votre outil n'est pas encore stable.

Utilisez cette séquence pour examiner chaque outil d'action :

1. Écrivez la cible comme un opérateur l'identifierait, avec l'environnement, le compte ou le tenant.
2. Écrivez le résultat obtenu avec un verbe concret et indiquez si le changement peut être annulé.
3. Nommez l'acteur de la confirmation, le moment où l'approbation intervient et précisez si elle s'applique à chaque appel ou à chaque session.
4. Comparez la phrase au comportement du gestionnaire, aux valeurs par défaut, aux nouvelles tentatives et aux API en aval.
5. Ajoutez des descriptions d'arguments pour les identifiants, les contrôles d'étendue et toute valeur qui modifie la cible.

Le quatrième point repère les défaillances que des documents bien rédigés ne montrent pas. Les nouvelles tentatives peuvent facturer ou envoyer un message deux fois si la requête en aval n'utilise pas de mécanisme d'idempotence. Les valeurs par défaut peuvent transformer un environment omis en production. Un gestionnaire peut associer un nom convivial à plusieurs ressources. La description ne peut pas réparer ces erreurs d'implémentation, mais sa rédaction les force à apparaître.

Un test interne utile consiste à retirer le nom de l'outil et à ne montrer à un autre ingénieur que la description et le schéma d'entrée. Demandez-lui de prédire ce qui se passera après un appel réussi et quelle approbation il attend. Si sa réponse diffère du gestionnaire, corrigez le contrat ou le code.

Testez aussi des demandes en langage courant. « Efface les anciennes données », « rends la nouvelle version active » et « répare le compte de Jordan » sont précisément le genre de demandes qui rendent un outil large tentant. Un agent sûr doit d'abord utiliser un outil d'inspection, demander l'identifiant manquant ou présenter l'action concrète à approuver. S'il peut passer directement de cette demande à une suppression en production, l'échec commence dans la conception de l'interface, bien avant le comportement du modèle.

Les messages d'erreur et les résultats doivent préserver la limite de sécurité

Une description soigneuse perd une grande partie de sa valeur lorsque le résultat de l'outil masque la cible exécutée ou lorsqu'une erreur invite l'agent à tenter une action plus large. Renvoyez assez d'éléments pour que l'agent et l'opérateur vérifient ce qui s'est passé.

Pour une modification d'état réussie, renvoyez l'identifiant canonique de la cible, l'action effectuée et l'état obtenu. Ne répondez pas seulement ok.

{
  "status": "completed",
  "target": {
    "environment": "production",
    "service": "catalog",
    "release": "2025.06.14-3"
  },
  "action": "traffic_promoted",
  "traffic_percent": 100,
  "request_id": "relreq_8a2f"
}

Lors d'une pause d'approbation, indiquez que rien n'a atteint la cible. Cette distinction empêche un agent de compenser un appel qui attend simplement une personne.

{
  "status": "approval_required",
  "action": "rotate_production_service_credential",
  "target": "production/catalog-api",
  "executed": false,
  "approval_scope": "this call"
}

Les erreurs exigent la même attention. « Interdit » est techniquement exact et opérationnellement inutile. Indiquez si la cible a été rejetée, si l'environnement est invalide, si l'approbation manque ou si la demande a échoué après avoir atteint le système distant. N'exposez jamais de secret dans cette explication et ne conseillez jamais à l'agent de répéter aveuglément une demande qui modifie un état.

L'idempotence mérite un résultat visible pour les actions importantes vers l'extérieur. Si un délai réseau survient après qu'un service distant a accepté un transfert ou créé une publication, l'agent doit consulter l'état de la demande avec un identifiant stable. Le chemin de nouvelle tentative ne doit pas deviner. Les descriptions ne peuvent pas exprimer toutes les règles de nouvelle tentative, mais un outil qui lance des appels irréversibles devrait avoir un outil d'état associé et une forme de résultat permettant la récupération.

Les descriptions doivent être accompagnées de contrôles

Le langage clair réduit les mauvaises sélections, mais ne peut pas arrêter un processus qui détient déjà un token de production sans restriction. Placez les credentials et l'action réseau finale derrière une limite capable de refuser, d'approuver et d'enregistrer l'appel.

Sallyport utilise cette organisation pour les agents connectés à MCP : l'agent utilise le composant fourni sp mcp, tandis que l'application conserve les credentials API et SSH dans son coffre chiffré et exécute elle-même les actions approuvées. Son autorisation par session et ses approbations facultatives par clé et par appel rendent la formulation de confirmation réellement applicable, au lieu d'en faire une simple demande de bonne conduite.

Cela ne justifie pas une conception faible des outils. La passerelle voit l'appel qui arrive. Votre schéma d'outil détermine toujours si l'appel dit « supprimer cette sauvegarde de production » ou dissimule la suppression derrière une opération générique admin. Imposez la validation des arguments dans le gestionnaire, limitez les credentials à la cible prévue lorsque le système distant le permet et conservez un journal d'audit identifiant le processus et l'action.

Les recommandations d'autorisation du Model Context Protocol soulignent le même point à un autre niveau : l'autorisation doit appartenir à un flux de protocole comportant des contrôles explicites, pas à une instruction destinée au modèle. Traitez les descriptions comme un contrat lisible par les humains. Traitez l'autorisation du serveur, la garde des credentials et l'approbation comme les contrôles qui rendent ce contrat vrai.

Prenez l'outil le plus dangereux que vous exposez aujourd'hui et réécrivez sa description sans regarder son nom. Si vous ne pouvez pas nommer la cible de production, l'effet secondaire obtenu et la portée de l'approbation en deux ou trois phrases directes, ne proposez pas encore cet outil à un agent autonome.