Bien écrire ses tools : une action claire, un contrat précis

La responsable d’un magasin demande à son assistant : « Supprime cette veste du catalogue de Lyon. » Elle veut arrêter sa vente dans ce magasin et conserver les commandes déjà passées.

L’agent dispose de trois outils : masquer un produit, supprimer une entrée de catalogue et supprimer une fiche produit commune à tous les magasins. Le nom « supprimer un produit » ne suffit pas pour choisir la bonne action.

Le problème : une intention claire, plusieurs effets possibles

Pour la responsable, le périmètre est évident. Pour l’agent, il faut encore savoir quel magasin est concerné, quel identifiant utiliser et quelles données seront touchées.

Une description vague peut conduire à un appel techniquement valide qui ne correspond pas à la demande. Le contrat doit donc expliquer l’effet métier autant que les paramètres.

La solution : décrire six informations

Pour notre outil supprimer_article_catalogue, nous préciserions :

Action et objet : supprimer une entrée du catalogue produit.
Périmètre : uniquement le magasin indiqué.
Entrées : identifiants du magasin et de l’article, types et champs obligatoires.
Résultat : identifiant concerné, confirmation de suppression ou erreur explicite.
Effet : arrêter les nouvelles commandes de cet article dans ce catalogue ; conserver les commandes historiques.
Différence : le masquage est temporaire ; la suppression de la fiche commune toucherait un autre périmètre.

Ces engagements décrivent notre exemple fictif. Ils doivent correspondre au comportement réel du service.

Du besoin au bon outil

Le choix commence par l’effet demandé et le périmètre concerné. Si ces informations manquent, l’agent doit demander des précisions. Dans notre scénario, la suppression locale est la branche à retenir.

Clarifier l’effet et le périmètre, puis choisir entre masquage temporaire, suppression d’une entrée locale et suppression d’une fiche commune. Vérifier ensuite les identifiants, les droits et la confirmation applicable avant l’appel. — Les noms d’outils sont fictifs. La branche centrale retire l’entrée du catalogue de Lyon ; les contrôles d’exécution restent à appliquer par l’application et le service. Ouvrir le schéma en grand.

Le fonctionnement technique : de la fiche à l’appel

Une fiche de rédaction peut servir à valider le besoin avec l’équipe métier. Voici un exemple YAML ; il ne constitue pas une définition MCP exécutable.

nom: supprimer_article_catalogue
action: Supprimer une entrée du catalogue produit
perimetre: Le catalogue du magasin indiqué
entrees:
  magasin_id: string, obligatoire
  article_id: string, obligatoire
resultat:
  article_id: Identifiant concerné
  supprime: true si la suppression a réussi
effet: >
  Arrête les nouvelles commandes dans ce catalogue.
  Conserve les commandes historiques.
difference: >
  Supprime l’entrée, contrairement au masquage temporaire.
  Conserve la fiche produit commune et les autres magasins.
erreurs:
  - magasin_inaccessible
  - article_absent

L’équipe traduit ensuite cette fiche en contrat exploitable : description de l’outil, schémas d’entrée et de sortie, puis traitement des erreurs. Un champ marqué obligatoire dans la prose doit aussi être obligatoire dans le schéma.

Si une API HTTP existe, OpenAPI peut porter descriptions, paramètres et réponses. La fiche Markdown est un support de rédaction possible, pas une obligation de stockage. Spécification OpenAPI

Dans notre scénario, l’application obtient les deux identifiants, contrôle les accès, applique sa politique de confirmation et appelle le service. Elle annonce la suppression après son succès effectif. Un nouvel appel après suppression renvoie ici article_absent : c’est un choix de contrat à documenter.

Les avantages d’un contrat précis

L’agent peut distinguer les actions voisines. La différence entre masquer, retirer d’un catalogue et supprimer une fiche commune est explicite.
L’équipe peut relire les conséquences avant de coder. La conservation des commandes devient un engagement vérifiable.
Les tests ont des résultats attendus. « Masque cette veste », « retire-la de Lyon » et « supprime-la partout » doivent conduire à des décisions différentes.

Une source de vérité permet aussi de générer les représentations nécessaires sans maintenir plusieurs descriptions à la main.

Les limites : la description ne suffit pas

Les règles doivent être appliquées par le service. Une phrase sur les permissions ne bloque pas un accès interdit. La conservation des commandes doit être garantie par l’implémentation.
Les erreurs doivent guider la reprise. Après un délai d’attente, l’état de la suppression peut être inconnu. Prévoir une vérification d’état ou un mécanisme de reprise adapté avant de répéter l’appel.
Le bon outil doit rester découvrable. Une excellente fiche est inutile si la recherche du catalogue ne la retrouve pas. Tester la sélection avec des formulations proches et des identifiants manquants.
Le contrat doit suivre les changements. Pour une CLI, les options, codes de retour et sorties structurées font aussi partie de ce contrat. Guide de conception des CLI

Pour poursuivre : comprendre MCP et comparer MCP, API et CLI.