Guide de conception des outils

Un outil MCP n’est pas un appel de fonction. C’est un contrat. Il décrit ce que le système peut faire, qui peut l’appeler, ce qui se passe, et ce qui peut mal tourner. Ce contrat doit être lisible par les machines, typé et complet avant qu’un agent ou un utilisateur appelle l’outil.

Le standard de contrat d’outil

Chaque outil MCP est décrit selon un schéma unifié. Le schéma comprend non seulement les types d’entrée et de sortie, mais aussi le niveau de risque, les permissions, les effets secondaires, les audit events et les cas d’échec possibles. Seul qui connaît tous les champs peut utiliser un outil en toute sécurité, que ce soit par un agent, une webapp ou un workflow automatisé.

Les champs en aperçu :

• Name, identifiant unique lisible par les machines au format domain.verb
• Description, description en langage naturel du but pour les agents et les développeurs
• Category, classification métier (ex. : communication, files, billing)
• Risk Level, classification selon le modèle de risque (Low à Forbidden)
• Autonomous Execution, si un agent peut appeler l’outil sans approbation humaine
• Confirmation, si une confirmation explicite de l’utilisateur est requise
• Step-up Auth, si une authentification supplémentaire est nécessaire et quand
• Input Schema, paramètres typés incluant les champs optionnels
• Output Schema, valeurs de retour typées incluant les codes de statut
• Permissions, quelles permissions l’outil requiert
• Side Effects, tous les changements d’état en dehors de la valeur de retour
• Audit Event, quel événement est écrit dans le journal d’audit
• Failure Modes, liste complète de tous les codes d’erreur possibles

L’exemple suivant montre le contrat complet pour emails.send_external, un outil avec un risque critique qui déclenche des communications externes :

Chaque champ a une fonction dans le système : permissions pilote le moteur de politique, sideEffects informe l’UI de confirmation, failureModes sont évalués dans la gestion des erreurs, auditEvent est écrit dans le journal d’audit. Le contrat n’est donc pas seulement de la documentation, il fait partie de l’exécution.

Le modèle de risque

MCP-first classe chaque outil dans l’un des cinq niveaux de risque. Le niveau détermine si un agent peut appeler l’outil de manière autonome, si une confirmation est requise et si une authentification renforcée est exigée. La classification n’est pas optionnelle, elle fait partie du contrat.

Low

Les outils de ce niveau sont purement en lecture ou ne génèrent pas d’effets permanents. Ils peuvent être exécutés de manière autonome par les agents, sans confirmation ni authentification renforcée. Les requêtes de liste, les recherches et les ressources d’aide sont typiques.

Medium

Les outils de ce niveau créent des données ou des états, mais dans un périmètre étroitement limité sans effet externe. Ils peuvent être exécutés de manière autonome lorsque la portée et le contexte découlent clairement du workflow. En cas de contexte ambigu, une confirmation est conseillée.

High

Les outils de ce niveau modifient des états système pertinents ou concernent d’autres utilisateurs et ressources externes. Ils nécessitent en général une confirmation explicite. Un agent ne peut pas les exécuter silencieusement.

Critical

Les outils de ce niveau déclenchent des communications externes, des paiements, des suppressions de données ou des modifications de permissions. Ils nécessitent toujours une confirmation explicite et souvent une authentification renforcée. L’exécution autonome n’est pas autorisée.

Forbidden for AI

Les outils de ce niveau ne peuvent être ni lus ni exécutés par un agent IA. Ils sont entièrement masqués de la découverte d’outils pour les agents. La classification est une limite absolue, pas une décision de politique.

Idempotence

De nombreux outils sont appelés plusieurs fois dans les workflows d’agents, par des nouvelles tentatives, une exécution parallèle ou une planification défaillante. MCP-first recommande de concevoir les outils idempotents dans la mesure du possible : la même entrée produit le même résultat lors d’appels multiples, sans générer de doublons ou d’effets secondaires indésirables.

L’outil create_download_link est un bon exemple. Si pour un fichier avec le même fileId et le même expiresAt un lien valide existe déjà, l’outil retourne ce lien au lieu d’en créer un second :

create_download_link(fileId: "f_abc123", expiresAt: "2025-12-31T23:59:00Z")

→ Premier appel : crée un nouveau lien, retourne linkId + url
→ Deuxième appel (mêmes paramètres, lien encore valide) : retourne le même lien
→ Troisième appel (lien expiré) : crée un nouveau lien

L’idempotence doit être implémentée explicitement, elle ne se produit pas automatiquement. Le champ sideEffects du contrat d’outil devrait décrire le comportement en cas de répétition, afin que les agents et les clients puissent le planifier correctement.

Dry Run

Les outils risqués, en particulier ceux avec des effets de masse, devraient proposer un mode dry run. Le dry run effectue toutes les validations et vérifications, mais ne génère pas de vrais effets secondaires. Le résultat montre ce qui se passerait, sans que quoi que ce soit ne se passe vraiment.

emails.bulk_send avec dryRun: true fournit un aperçu complet :

// Request
{
  "tool": "emails.bulk_send",
  "params": {
    "templateId": "tmpl_newsletter_q3",
    "segmentId": "seg_active_customers",
    "dryRun": true
  }
}

// Response
{
  "dryRun": true,
  "recipientCount": 4821,
  "sampleMessages": [
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Liebe Anna, im dritten Quartal haben wir…"
    },
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Lieber Max, im dritten Quartal haben wir…"
    }
  ],
  "warnings": [
    "43 Empfänger haben keinen Vornamen, Fallback 'Hallo' wird verwendet.",
    "12 E-Mail-Adressen sind als unzustellbar markiert und werden übersprungen."
  ],
  "missingPermissions": [],
  "expectedSideEffects": [
    "4821 externe E-Mails werden versendet.",
    "4821 Audit-Events vom Typ email.external.sent werden erzeugt.",
    "Kampagnen-Status wird auf 'sent' gesetzt."
  ],
  "estimatedDurationMs": 18400
}

Ce n’est qu’après vérification du résultat du dry run et confirmation explicite par l’utilisateur que le vrai appel est effectué sans dryRun. L’agent ne peut pas sauter le dry run si l’outil le déclare comme obligatoire.