Warum AI-Agent Tool Calling JSON Schema braucht: Parameterfehler, Typfehler und Validierung

Frühere Beiträge dieser Reihe bereiten den Weg: Die Entwicklung von „JSON Schema“, „Function Calling“ und „MCP“ erklärt, warum es sie gibt; Der JSON-Datenfluss von Tool Calling zu MCP verfolgt, wohin sich Bytes bewegen; ob das JSON-Schema zum Standard-Agent-Vertrag wird, der die Ökosystemkonvergenz abdeckt. Dieser Artikel konzentriert sich auf eine praktische Frage: Warum „Tool Calling“ fast zwangsläufig vom „JSON-Schema“ abhängt und wie Parameter- und Typfehler klassifiziert und validiert werden.

Wenn ein Modell ein Werkzeug auswählt und Parameter ausfüllt, kann der Host nicht „auf Glück vertrauen“ – er muss vor der Ausführung „schnell ausfallen“ anhand desselben Schemas. Ein halluziniertes Argument kann Daten löschen, die falsche E-Mail senden oder die nächste Runde vergiften. Fazit: JSON Schema ist der einzige Parametervertrag, der von Modell-APIs, MCP und Host-Laufzeiten gleichermaßen verstanden wird; Validieren Sie nach dem Parsen und vor der Ausführung und geben Sie strukturierte Fehler zur Wiederholung zurück.

Warum Tool-Aufruf vom JSON-Schema abhängt

Tool Calling (gleicher Datenfluss wie Function Calling) bedeutet: Das Modell wählt ein Tool und gibt JSON-Argumente aus, die einem Vertrag entsprechen. Drei Parteien müssen sich einigen:

• 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.
• Host-Programme: benötigen maschinenlesbare, versionierbare, CI-überprüfbare Verträge – ajv, Python jsonschema usw. schlagen das „JSON-Format in der Eingabeaufforderung“ um Größenordnungen.

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

Schema befindet sich an drei Stellen in der Anrufkette

Vs. Strukturierte Ausgabe: 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.

Parameterfehler: fehlende, zusätzliche, falsche Namen, falsche Syntax

Parameterfehler bedeuten, dass JSON möglicherweise analysiert (oder vor der Analyse fehlschlägt), aber gegen Schemaschlüssel und erforderliche Regeln verstößt:

// 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" }

Typfehler: Nichtübereinstimmungen, enum, Verschachtelung, Zwang

Typfehler: Felder sind vorhanden, aber der JSON-Typ oder das JSON-Format der Werte verstößt gegen das Schema:

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

Validierung: Syntax, Argumente, strenger Modus

1. Validieren Sie das Schema selbst

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. Validieren Sie „Argumente“ anhand des Schemas

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 Einzelquelle

3. Hersteller strenger Modus

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 Vertragsartikel.

4. Stichprobengesteuertes CI

Pro Tool: gültige Argumentbeispiele + absichtliche Fehler in CI. Schemaänderungen machen API-Änderungen kaputt – versionieren Sie sie.

End-to-End-Pipeline und Fehler-Feedback

Minimale Pipeline (erweitert den Artikel zum Datenfluss):

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.

Die Ausführung erfordert weiterhin Authentifizierung und Idempotenz – das Schema garantiert die Form, nicht „diese Ticket-ID gehört dem Benutzer“.

Praktische Empfehlungen

• Einzelne Schemaquelle: Pydantic / Zod → MCP inputSchema + OpenAI Tools.
• Beschreibungen sind Eingabeaufforderungen: Sie steuern enum und die erforderliche Konformität – überprüfen Sie Schemas wie API-Code.
• Einfaches Schema, strikte Validierung: oneOf/$ref-Tiefe auf Ziel-API-Teilmenge zuschneiden; scheitern schnell, keine stillen Korrekturen.
• Zwei obligatorische Prüfpunkte: nach tool_calls vor der Ausführung; nach MCP Rückkehr vor dem Kontext (wenn Ergebnisse das Modell füttern).
• Zuerst lokal validieren: Fügen Sie Schema + Beispielargumente vor der Produktion in die JSON Toolbox ein.
• Von „Strukturierter Ausgabe“ trennen: Benutzerantwortschema vs. Tools-Schema – nicht zusammenführen.

FAQ

Zusammenfassung und nächste Schritte

Tool Calling hängt vom JSON Schema ab, da es sich um den gemeinsamen, überprüfbaren Parametervertrag für Modelle, MCP und Hosts handelt. Parameterfehler (fehlend, überzählig, falscher Name, Syntax) und Typfehler (Typen, enum, Verschachtelung) klassifizieren; Vor der Ausführung abfangen und strukturierte Fehler zur Selbstkorrektur einspeisen.

Als nächstes: Wählen Sie ein echtes Tool (z. B. Ticketerstellung), schreiben Sie Schema + gültige/ungültige Beispiele, validieren Sie lokal in der JSON Toolbox und verbinden Sie dann den Agent. Reihenreihenfolge: Evolution → Datenfluss → Vertrag → dieser Artikel (Validierung).