Spécification des outils MCP — JSON Schema et annotations

De quoi il s'agit

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.

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.
• Le passage de la spécification MCP à la révision du 28/07/2026 (elicitation, cadre d'extensions) a laissé inchangés le modèle à quatre artefacts et le bloc d'annotations de cette fiche — les annotations restent exactement l'ensemble readOnlyHint/destructiveHint/idempotentHint/openWorldHint du 18/06/2025.
• Pour un outil côté SAP — une action d'écriture contre Datasphere ou S/4HANA — un destructiveHint manquant ou faux est un échec de gouvernance, pas une coquetterie d'UX : il décide si le runtime d'agent conscient de MCP d'un client montre à un humain une étape de confirmation avant qu'une transaction SAP irréversible ne s'exécute.

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.

destructiveHint

L'annotation signalant qu'un appel d'outil peut provoquer un changement irréversible ou difficile à annuler. Pour des actions d'écriture SAP sans annulation triviale — une écriture comptabilisée, un bon de commande libéré —, mieux vaut pécher par excès en la fixant à true même quand la description de l'outil paraît routinière.

readOnlyHint

L'annotation marquant un outil comme sûr à appeler sans confirmation de l'utilisateur car il ne fait que lire des données, sans effet de bord. Le défaut correct pour des outils SAP en forme de consultation, comme interroger un modèle Datasphere ou lire une fiche de données de base.

Sources

1. MCP specification — Tools
2. JSON Schema 2020-12 draft
3. SAP Generative AI — official product page
4. Model Context Protocol — Server features, specification revision 2026-07-28
5. Model Context Protocol — Extensions overview (Tasks, Skills over MCP, MCP Apps)
6. SAP Community — Public release of the MCP server for SAP BTP administration
7. SAP News Center — Autonomous Enterprise: SAP AI Agent Hub inventory and runtime approval for agents/MCP servers
8. SAP Help Portal — Connect to MCP server for SAP BTP administration
9. SAP Community — Principal propagation for MCP servers: SAP Integration Suite to SAP S/4HANA (authorization boundary)
10. GitHub — modelcontextprotocol/typescript-sdk (reference tool/annotation implementation)
11. Model Context Protocol — Tools, specification 2026-07-28 (x-mcp-header constraints, inputSchema)
12. Model Context Protocol — Key changes, specification 2026-07-28 (Mcp-Method/Mcp-Name headers, x-mcp-header, sessions removed)
13. modelcontextprotocol/python-sdk — v2.3.0 release notes, 2 October 2026 (invalid x-mcp-header rejected at registration)
14. modelcontextprotocol/typescript-sdk — v2.3.0 release notes, 2 October 2026 (maxToolInputElements, expectedResource)
15. Model Context Protocol — Security Best Practices (token audience validation, confused-deputy risks)