Vom API-Endpunkt zur Nutzerabsicht

Tools sollten fachliche Intentionen abbilden, nicht mechanisch Endpunkte spiegeln. Ein Tool pro CRUD-Operation zwingt das Modell, interne Zustandslogik zu rekonstruieren. Eine kuratierte Capability bündelt nur Schritte, die transaktional und sicherheitlich zusammengehören.

Read- und Write-Fähigkeiten werden getrennt. Auch Vorbereitung und verbindliche Ausführung gehören häufig in zwei Tools, damit der Client vor der Nebenwirkung eine überprüfbare Vorschau zeigen kann.

InputSchema

JSON Schema beschreibt Typen, Pflichtfelder, Enums, Formate, Längen, Zahlenbereiche und zusätzliche Eigenschaften. additionalProperties:false reduziert überraschende Eingaben. Beschreibungen erklären fachliche Bedeutung und Einheit.

Schemaerfolg ist nur Stufe eins. Danach folgen Normalisierung, objektbezogene Autorisierung und fachliche Konsistenz gegen den aktuellen Backendzustand. IDs aus dem Client dürfen nicht als Zugriffsrecht interpretiert werden.

OutputSchema und strukturierte Resultate

Ein outputSchema macht Resultate validierbar und ermöglicht stabilere Weiterverarbeitung. StructuredContent sollte dem Schema entsprechen; für Kompatibilität kann dieselbe Information zusätzlich als TextContent serialisiert werden.

Ergebnisse werden auf den Zweck minimiert. Interne Debugfelder, vollständige Kundenobjekte oder Downstreamtokens sind keine hilfreiche Transparenz, sondern Datenabfluss.

Fehler und Wiederholbarkeit

Fachfehler sollten dem Modell eine sichere Korrektur ermöglichen, ohne Interna zu verraten. Autorisierungsfehler werden nicht durch alternative Parameter umgehbar. Temporäre Fehler enthalten keine pauschale Retry-Empfehlung, wenn die Operation möglicherweise ausgeführt wurde.

Schreibende Tools verwenden Idempotenzschlüssel oder fachliche Eindeutigkeitsbedingungen. Parallelaufrufe werden gegen Race Conditions getestet.

Toolbeschreibung als Auswahloberfläche

Titel und Beschreibung beeinflussen, wann ein Modell das Tool auswählt. Sie nennen positiven Zweck, Ausschlüsse und Konsequenzen. Beispiele helfen, dürfen aber keine versteckte Policy ersetzen.

Evaluationen messen Auswahlpräzision mit realistischen und adversarialen Nutzeranfragen. Ein technisch korrektes Tool ist unbrauchbar, wenn Modelle es regelmäßig mit einem Nachbartool verwechseln.

FAQ zu MCP-Tool-Design und JSON Schema

Soll jedes API-Feld im Tool erscheinen?

Nein. Nur Felder, die für die Nutzerabsicht erforderlich, verständlich und zulässig sind.

Sind Tool-Annotationen vertrauenswürdig?

Clients müssen Annotationen eines nicht vertrauenswürdigen Servers als untrusted behandeln. Serverseitig ersetzen sie niemals Autorisierung.

Primärquellen und wissenschaftliche Einordnung

Die Darstellung folgt der versionierten MCP-Spezifikation. Normative Anforderungen werden von Architektur- und Betriebsempfehlungen getrennt; experimentelle Funktionen sind entsprechend gekennzeichnet.