Konzeptkarte

MCP-Tool-Spezifikationsstandard — JSON Schema und Annotationen

Stand 2026-07-24T14:00:00Z

Redaktion: Cédric-Olivier Mâry, alleiniger Redakteur und verantwortlich für die Veröffentlichung — 27 Jahre im SAP-Ökosystem. Wie diese Seiten entstehen und wo Automatisierung eingesetzt wird.

Was ist MCP-Tool-Spezifikationsstandard — JSON Schema und Annotationen?

Die meisten Ausfälle von MCP-Tools im Produktivbetrieb sind keine Handler-Fehler — es sind unzureichend spezifizierte Beschreibungen und zu lose Eingabeschemata, die das Modell zu falscher Tool-Auswahl oder ungültigen Argumenten verleiten.

Ein MCP-Tool wird vollständig durch vier Artefakte beschrieben: einen Namen, eine Beschreibung, eine JSON-Schema-Eingabespezifikation und einen optionalen Annotationsblock. Die Qualität dieser vier Artefakte entscheidet, ob ein LLM-Client das richtige Tool wählt, es mit gültigen Argumenten aufruft und das Ergebnis korrekt interpretiert. Die meisten Produktionsfehler in MCP-Servern sind keine Handler-Bugs; es sind unzureichend spezifizierte Beschreibungen und zu lose Eingabeschemata, die das Modell zu falscher Tool-Auswahl oder ungültiger Argumenterzeugung verleiten.

Was jedes Artefakt trägt

Der Name ist ein stabiler Identifikator, üblicherweise als kurze, aneinandergereihte Kleinbuchstaben-Wörter geschrieben, die eine Aktion und ein Substantiv beschreiben, etwa ein Tool, das ein Firmenverzeichnis durchsucht, oder eines, das das vollständige Profil einer einzelnen Firma abruft. Stabilität zählt hier mehr als Eleganz: Ein Tool zwischen Serverversionen umzubenennen bricht still jeden Agenten-Prompt, jeden gecachten Plan oder jedes feinabgestimmte Routing-Verhalten, das sich auf den alten Namen bezog. Die Beschreibung ist das Artefakt, das das Modell tatsächlich liest, um zu entscheiden, ob ein Tool zur Absicht des Nutzers passt, und sie ist das mit dem größten Hebel im gesamten Server. Ein nacktes „Search firms" wird in dem Moment falsch ausgewählt, in dem ein zweites suchförmiges Tool im selben Kontext existiert, während eine vollständigere Beschreibung, die nennt, welches Verzeichnis durchsucht wird, wie viele Ergebnisse zurückkommen, nach welchen Feldern der Aufrufer filtern kann und welches begleitende Tool als Nächstes für einen vollständigen Datensatz aufzurufen ist, dem Modell genug gibt, um korrekt zu routen und den nächsten Schritt zu planen.

Warum es zählt

Eine vage Beschreibung wie „Search firms" wird in einem Multi-Tool-Kontext falsch ausgewählt; die Aktion, Eingaben, Ausgabeform und das Folge-Tool zu nennen, löst die Mehrdeutigkeit auf.
Eine locker typisierte Eigenschaft wie {type: string, description: country} erzeugt je nach Modell zufällige ISO-Codes oder vollständige Ländernamen; sie mit einem expliziten enum zu beschränken, behebt die Mehrdeutigkeit auf Schema-Ebene.
Das Zod-first-Muster (eine Schema-Definition, die sowohl den Laufzeit-Validator als auch das JSON Schema erzeugt) beseitigt Schema-Drift zwischen dem, was der Handler durchsetzt, und dem, was das LLM sieht.

Kernpunkte

Vier Artefakte pro Tool — Name (snake_case, stabile ID), Beschreibung (Aktion+Substantiv voran), Eingabespezifikation (JSON Schema 2020-12), Annotationen (Planungshinweise).
Beschreibungsqualität treibt die Tool-Auswahl — mit der Aktion beginnen, Eingaben und Ausgabeform auflisten, Einschränkungen nennen; vage Beschreibungen leiten das LLM in die Irre.
Eingabespezifikation — JSON Schema 2020-12 mit required, properties (type+description+enum/pattern), additionalProperties:false, um Tippfehler abzulehnen.
Zod-first-Muster — Schema einmal in TypeScript definieren, sowohl Laufzeit-Validator als auch JSON Schema für das LLM erzeugen.
Annotationen (Spezifikationsrevision 2025-06-18) — title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint; Planungshinweise, keine Laufzeitdurchsetzung.
„MCP-Tool-Spezifikationsstandard — JSON Schema und Annotationen" ist erst dann beherrscht, wenn es eine benannte Kaufentscheidung verändert.
Beginnen Sie mit dem semantischen Vertrag und dem Steuerungsmodell, bevor Sie das Tool demonstrieren.
Nutzen Sie aktuelle SAP-, Analysten-, Studien-, KG- und News-Signale als Beleg, nicht als Dekoration.
Trennen Sie verifizierte Fakten von richtungsweisenden Trends und modellierten Annahmen.
Definieren Sie Verantwortlichen, Kennzahl, Schwellenwert, Support-Pfad und Rollback, bevor Sie skalieren.

Begriffe auf dieser Seite

JSON Schema 2020-12: Der IETF-Draft-Schema-Dialekt, den MCP-Tool-Eingabespezifikationen verwenden; types, required, properties, enum, pattern, additionalProperties — das LLM liest es, um zu wissen, wie ein gültiger Aufruf zu konstruieren ist.
Tool-Annotationen: Optionale Hinweise, die seit der Spezifikationsrevision 2025-06-18 neben name/description/inputSchema mitgeführt werden: title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint — das Modell nutzt sie zur Planung, der Server setzt sie nicht zur Laufzeit durch.
Zod-first-Schema-Muster: Ein Eingabeschema einmal in TypeScript mit Zod definieren, dann sowohl den Laufzeit-Validator als auch den JSON-Schema-String erzeugen, den das LLM sieht — eine einzige Quelle der Wahrheit, kein Drift zwischen dem, was die Spezifikation ausweist, und dem, was der Handler akzeptiert.
Tool-Fehlrouting: Der Fehlermodus, bei dem das LLM für eine Nutzerabsicht das falsche Tool wählt, weil sich die Beschreibungen zweier Tools überschneiden oder zu vage sind; die Produktionsbug-Klasse Nr. 1 in MCP-Servern, behoben durch chirurgisch präzise Beschreibungen und klare Annotationen.
Entscheidungsverantwortlicher: Die verantwortliche Person, die den Kompromiss akzeptiert und die nächste Maßnahme finanziert.
Semantischer Vertrag: Die gemeinsame Definition von Geschäftsbegriffen, Kennzahlen, Entitäten und Zugriffsregeln, die von Tools und Teams verwendet wird.
Control Plane: Die Schicht, die Policy, Zugriff, Lineage, Monitoring und Eskalation über das Betriebsmodell hinweg durchsetzt.
Evidenzgrad: Eine Kennzeichnung, die verifizierte Fakten, Richtungssignale, modellierte Annahmen und Feldbeobachtungen unterscheidet.

Quellen

Vollständige Karte für Mitglieder. Was die vollständige Karte ergänzt: den vollständigen Entscheidungsrahmen · den Vergleich SAP · Snowflake · Databricks · Fabric · die häufigen Fallstricke und ihre Behebung · die Kurzreferenz · die Architekturschemata · die Codeblöcke · die zitierfähigen Kennzahlen.

In der App öffnen →