Fiche concept

Spécification des outils MCP — JSON Schema et annotations

À jour au 2026-07-24T14:00:00Z

Édité par Cédric-Olivier Mâry, éditeur et directeur de la publication — 27 ans d'écosystème SAP. Comment ces pages sont produites, et où intervient l'automatisation.

Qu'est-ce que Spécification des outils MCP — JSON Schema et annotations ?

La plupart des échecs de production des outils MCP ne sont pas des bugs de handler — ce sont des descriptions sous-spécifiées et des schémas d'entrée laxistes qui induisent le modèle en erreur sur la sélection d'outil ou la génération d'arguments.

Un outil MCP est entièrement décrit par quatre artefacts : un nom, une description, une spécification d'entrée en JSON Schema, et un bloc d'annotations optionnel. La qualité de ces quatre artefacts détermine si un client LLM choisit le bon outil, l'appelle avec des arguments valides, et interprète correctement le résultat. La majorité des échecs en production sur les serveurs MCP ne sont pas des bugs dans le gestionnaire ; ce sont des descriptions sous-spécifiées et des schémas d'entrée trop permissifs qui induisent le modèle en erreur, que ce soit dans le choix de l'outil ou dans la génération d'arguments invalides.

Ce que porte chaque artefact

Pourquoi c'est important

Une description vague comme « Cherche des firmes » sera mal sélectionnée dans un contexte multi-outil; nommer l'action, les entrées, la forme de sortie et l'outil de suivi lève l'ambiguïté.
Une propriété faiblement typée comme {type: string, description: pays} produit des codes ISO aléatoires ou des noms de pays complets selon le modèle; la contraindre avec un enum explicite corrige l'ambiguïté au niveau du schéma.
Le pattern Zod-first (une seule définition de schéma émettant à la fois le validateur runtime et le JSON Schema) élimine la dérive de schéma entre ce que le handler impose et ce que le LLM voit.

Points clés

Quatre artefacts par outil — nom (snake_case stable), description (verbe+objet en tête), spec d'entrée (JSON Schema 2020-12), annotations (hints de planification).
La qualité de description pilote la sélection — verbe + objet, entrées et forme de sortie, contraintes ; les descriptions vagues égarent le LLM.
Spec d'entrée — JSON Schema 2020-12 avec required, properties (type+description+enum/pattern), additionalProperties:false pour rejeter les fautes.
Pattern Zod-first — schéma défini une fois en TypeScript, émet validateur runtime et JSON Schema pour le LLM.
Annotations (rév 2025-06-18) — title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint ; hints planification, pas application runtime.

Termes employés sur cette page

JSON Schema 2020-12: Le dialecte de schéma (draft IETF) utilisé par les spécifications d'entrée des outils MCP ; types, required, properties, enum, pattern, additionalProperties — le LLM le lit pour savoir comment construire un appel valide.
Tool annotations: Indications optionnelles portées aux côtés de name/description/inputSchema depuis la révision de spec 2025-06-18 : title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint — le modèle les utilise pour sa planification, le serveur ne les impose pas à l'exécution.
Zod-first schema pattern: Définir un schéma d'entrée une seule fois en TypeScript avec Zod, puis en dériver à la fois le validateur d'exécution et la chaîne JSON Schema que voit le LLM — source unique de vérité, aucun écart entre ce que la spec annonce et ce que le handler accepte.
Tool mis-routing: Le mode de défaillance où le LLM choisit le mauvais outil pour une intention utilisateur parce que les descriptions de deux outils se chevauchent ou sont trop vagues ; la première classe de bugs en production dans les serveurs MCP, corrigée par des descriptions chirurgicales et des annotations claires.
Decision owner: La personne responsable qui assume l'arbitrage et finance l'action suivante.
Semantic contract: La définition partagée des termes métier, métriques, entités et règles d'accès utilisée par les outils et les équipes.
Control plane: La couche qui applique la politique, l'accès, la traçabilité, la supervision et l'escalade à travers le modèle opérationnel.
Evidence grade: Une étiquette qui distingue le fait vérifié, le signal directionnel, l'hypothèse modélisée et l'observation de terrain.

Sources

Fiche complète réservée aux abonnés. Ce que la fiche complète ajoute : le cadre de décision complet · la comparaison SAP · Snowflake · Databricks · Fabric · les pièges courants et leur correctif · l'aide-mémoire · les schémas d'architecture · les blocs de code · les chiffres à citer.

Ouvrir dans l'application →