Konzeptkarte

MCP-Tool-Spezifikationsstandard — JSON Schema und Annotationen

Stand 18. Oktober 2026

Redaktion: Cédric Mary, 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?

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.
Der Übergang der MCP-Spezifikation zur Revision vom 28.07.2026 (Elicitation, Extensions-Framework) ließ das Vier-Artefakte-Modell und den Annotationsblock dieser Karte unverändert — Annotationen bleiben genau das Set readOnlyHint/destructiveHint/idempotentHint/openWorldHint vom 18.06.2025.
Bei einem SAP-seitigen Tool — einer Schreibaktion gegen Datasphere oder S/4HANA — ist ein fehlender oder falscher destructiveHint ein Governance-Fehler, keine UX-Nettigkeit: Er entscheidet, ob die MCP-bewusste Agenten-Laufzeitumgebung eines Kunden einem Menschen einen Bestätigungsschritt zeigt, bevor eine irreversible SAP-Transaktion ausgeführt wird.

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.
destructiveHint: Die Annotation, die kennzeichnet, dass ein Tool-Aufruf eine irreversible oder schwer rückgängig zu machende Änderung verursachen kann. Bei SAP-Schreibaktionen ohne triviales Undo — eine gebuchte Journalbuchung, eine freigegebene Bestellung — eher dazu neigen, dies auf true zu setzen, selbst wenn die Beschreibung des Tools routinemäßig klingt.
readOnlyHint: Die Annotation, die ein Tool als sicher aufrufbar ohne Nutzerbestätigung kennzeichnet, weil es nur Daten liest, ohne Nebeneffekt. Der richtige Standard für nachschlagende SAP-Tools wie das Abfragen eines Datasphere-Modells oder das Lesen eines Stammdatensatzes.

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 →

Offene SAP-Projekte

Aktuelle SAP-Analytics-Projekte und Stellen im DACH-Raum: SAP-Analytics-Projekte im DACH-Raum.