Pourquoi le Tool Calling des agents IA dépend de JSON Schema : erreurs de paramètres, de types et validation

Les articles précédents de cette série ont préparé le terrain : l'évolution de JSON Schema, Function Calling et MCP explique pourquoi ils existent ; Les données JSON circulent de Tool Calling vers les traces MCP où les octets se déplacent ; si JSON Schema devient le contrat Agent standard couvrant la convergence de l'écosystème. Cet article se concentre sur une question pratique : pourquoi Tool Calling dépend presque inévitablement du JSON Schema, et comment classer et valider les erreurs de paramètre par rapport aux erreurs de type.

Lorsqu'un modèle choisit un outil et remplit les paramètres, l'hôte ne peut pas « faire confiance à la chance » : il doit « échouer rapidement » par rapport au même schéma avant l'exécution. Un argument halluciné peut supprimer des données, envoyer le mauvais e-mail ou empoisonner le tour suivant. En fin de compte : JSON Schema est le seul contrat de paramètres compris par les API de modèle, MCP et les environnements d'exécution hôtes ; validez après l'analyse et avant l'exécution, et renvoyez les erreurs structurées pour une nouvelle tentative.

Pourquoi Tool Calling dépend du JSON Schema

Tool Calling (même flux de données que Function Calling) signifie : le modèle choisit un outil et génère des arguments JSON qui correspondent à un contrat. Trois parties doivent s'entendre :

• Model APIs: OpenAI, Gemini, and Anthropic Tools APIs describe parameters with JSON Schema; some vendors also constrain decoding with Schema.
• MCP: each Tool’s inputSchema is JSON Schema; Hosts often pass it through or trim to a subset when mapping to model APIs.
• Programmes Host : nécessitent des contrats lisibles par machine, versionnables et vérifiables par CI : ajv, Python jsonschema, etc. battent le « format JSON dans l'invite » par des ordres de grandeur.

Without Schema, hosts regex-parse or prompt-parse arguments—that breaks at Agent scale. Schema gives shape (which fields), types, and constraints (enum, minimum, pattern)—everything you need syntactically before calling HTTP/DB/MCP. Business rules (“does priority=high violate SLA?”) still need code; Schema blocks most hallucinations at the syntax layer.

User intent → model reads JSON Schema in tools[]
           → outputs tool_calls[].function.arguments (JSON string)
           → host JSON.parse + Schema validate
           → only then call MCP / HTTP / DB

Trois endroits où Schema se trouve sur la chaîne d'appels

Vs. Sortie structurée: Structured Output constrains the final user-facing JSON reply; Tool Calling Schema constrains execution parameters. You can share one Schema source (Pydantic / Zod), but validate Tool arguments on every tool_calls before execute.

Erreurs de paramètres : manquants, supplémentaires, noms erronés, syntaxe

Les erreurs de paramètres signifient que JSON peut analyser (ou échouer avant l'analyse) mais viole les clés de schéma et les règles requises :

// Schema fragment
{
  "type": "object",
  "properties": {
    "ticket_id": { "type": "string", "description": "Ticket ID" },
    "note": { "type": "string" }
  },
  "required": ["ticket_id"],
  "additionalProperties": false
}

// Model output (missing ticket_id) → validation fails
{ "note": "Please handle ASAP" }

Erreurs de type : incompatibilités, enum, imbrication, coercition

Erreurs de type : des champs existent mais le type ou le format JSON des valeurs viole le schéma :

Coercion: some validators coerce "10" to 10. In production Agents, prefer coercion off—silent fixes hide systematic drift. If you must coerce, document it and lock behavior in CI samples.

// Type error example
Schema: { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }
Model:  { "limit": " fifty " }  // string, not numeric → fail

Validation : syntaxe, arguments, mode strict

1. Validez le schéma lui-même

Before registering tools, meta-validate parameters / inputSchema (draft 2020-12, etc.). JSON Toolbox in the browser works locally—don’t ship invalid Schema to model APIs.

2. Validez les arguments par rapport au schéma

After JSON.parse(arguments), validate with the same Schema used at registration:

• JavaScript / TypeScript: ajv (mind draft and strict options)
• Python: jsonschema, Pydantic (model_validate after JSON parse)
• Codegen : Zod / Pydantic → JSON Schema source unique

3. Fournisseur mode strict

OpenAI strict: true requires a stricter subset (e.g. all objects with additionalProperties: false). That reduces model-side errors but does not replace host validation—dialects differ by vendor; see the Article du contrat.

4. CI basé sur des échantillons

Par outil : échantillons d'arguments valides + échecs intentionnels dans CI. Les modifications de schéma interrompent les modifications de l'API : versionnez-les.

Pipeline de bout en bout et retour d’erreurs

Pipeline minimal (étend l'article sur le flux de données) :

1. tools/list or static register → validate each inputSchema syntax
2. On tool_calls → JSON.parse(arguments)
   ├─ parse fail → tool message "JSON syntax error: …" → model retry
   └─ parse ok → ajv/jsonschema validate
        ├─ fail → structured errors (missing, type, enum) → feed back
        └─ ok → execute + optional business rules
3. Tool result → optional result Schema before append to messages
4. Log: schema version, raw arguments, error codes (no secrets)

Error feedback must be machine-readable: “ticket_id is required” beats “bad params, retry”. Many frameworks format validation errors as JSON in the tool role for self-correction.

L'exécution a toujours besoin d'authentification et d'idempotence : le schéma garantit la forme, et non « ce ticket_id appartient à l'utilisateur ».

Recommandations pratiques

• Source de schéma unique : outils Pydantic / Zod → MCP inputSchema + OpenAI.
• Les descriptions sont des invites : elles déterminent l'énum et la conformité requise : examinez le schéma comme le code de l'API.
• Schéma simple, validation stricte : coupez la profondeur oneOf/$ref pour cibler le sous-ensemble de l'API ; échouer rapidement, pas de correctifs silencieux.
• Deux points de contrôle obligatoires : après tool_calls avant l'exécution ; après MCP retour avant le contexte (si les résultats alimentent le modèle).
• Validez d'abord localement : collez le schéma + l'échantillon arguments dans la JSON Toolbox avant la production.
• Séparé de la « Sortie structurée » : réponse de l'utilisateur Schéma par rapport aux outils Schéma : ne pas fusionner.

FAQ

Résumé et prochaines étapes

Tool Calling dépend du JSON Schema car il s'agit du contrat de paramètres partagé et vérifiable pour les modèles, MCP et les hôtes. Classer les erreurs de paramètres (manquants, supplémentaires, mauvais nom, syntaxe) et les erreurs de type (types, enum, imbrication) ; intercepter avant d’exécuter et alimenter les erreurs structurées pour l’auto-correction.

Ensuite : choisissez un outil réel (par exemple, création de ticket), écrivez un schéma + des échantillons valides/invalides, validez localement dans la JSON Toolbox, puis câblez l'Agent. Ordre des séries : évolution → flux de données → contrat → cet article (validation).