Tool Design Guide

Ein MCP-Tool ist kein Funktionsaufruf. Es ist ein Vertrag. Es beschreibt, was das System kann, wer es aufrufen darf, was dabei passiert, und was schiefgehen kann. Dieser Vertrag muss maschinenlesbar, typisiert und vollständig sein, bevor ein Agent oder ein Benutzer das Tool überhaupt aufruft.

Der Tool Contract Standard

Jedes MCP-Tool wird nach einem einheitlichen Schema beschrieben. Das Schema umfasst nicht nur Eingabe- und Ausgabetypen, sondern auch Risikostufe, Berechtigungen, Side Effects, Audit Events und mögliche Fehlerfälle. Nur wer alle Felder kennt, kann ein Tool sicher einsetzen, ob durch einen Agenten, eine Webapp oder einen automatisierten Workflow.

Die Felder im Überblick:

• Name, eindeutiger, maschinenlesbarer Bezeichner im Format domain.verb
• Description, natürlichsprachige Beschreibung des Zwecks für Agents und Entwickler
• Category, fachliche Einordnung (z. B. communication, files, billing)
• Risk Level, Klassifizierung nach dem Risikomodell (Low bis Forbidden)
• Autonomous Execution, ob ein Agent das Tool ohne menschliche Freigabe aufrufen darf
• Confirmation, ob eine explizite Nutzerbestätigung erforderlich ist
• Step-up Auth, ob eine zusätzliche Authentifizierung nötig ist und wann
• Input Schema, typisierte Parameter inkl. optionaler Felder
• Output Schema, typisierte Rückgabewerte inkl. Statuscodes
• Permissions, welche Berechtigungen das Tool erfordert
• Side Effects, alle Zustandsänderungen außerhalb des Rückgabewerts
• Audit Event, welches Event ins Audit Log geschrieben wird
• Failure Modes, vollständige Liste aller möglichen Fehlercodes

Das folgende Beispiel zeigt den vollständigen Contract für emails.send_external, ein Tool mit Critical-Risiko, das externe Kommunikation auslöst:

Jedes Feld hat eine Funktion im System: permissions steuert die Policy Engine, sideEffects informiert die Confirmation UI, failureModes werden im Error Handling ausgewertet, auditEvent wird ins Audit Log geschrieben. Der Contract ist damit nicht nur Dokumentation, er ist Teil der Laufzeit.

Das Risikomodell

MCP-first klassifiziert jedes Tool in eine von fünf Risikostufen. Die Stufe bestimmt, ob ein Agent das Tool autonom aufrufen darf, ob eine Bestätigung erforderlich ist und ob Step-up Auth verlangt wird. Die Einstufung ist nicht optional, sie ist Teil des Contracts.

Low

Tools dieser Stufe sind rein lesend oder erzeugen keine dauerhaften Effekte. Sie dürfen von Agents autonom ausgeführt werden, ohne Bestätigung oder Step-up Auth. Typisch sind Listenabfragen, Suchen und Hilfe-Ressourcen.

Medium

Tools dieser Stufe erzeugen Daten oder Zustände, aber in einem eng begrenzten Scope ohne externe Wirkung. Sie dürfen autonom ausgeführt werden, wenn Scope und Kontext eindeutig aus dem Workflow hervorgehen. Bei unklarem Kontext ist Bestätigung ratsam.

High

Tools dieser Stufe ändern relevante Systemzustände oder betreffen andere Nutzer und externe Ressourcen. Sie erfordern in der Regel eine explizite Bestätigung. Ein Agent darf sie nicht stillschweigend ausführen.

Critical

Tools dieser Stufe lösen externe Kommunikation, Zahlungen, Datenlöschungen oder Berechtigungsänderungen aus. Sie erfordern immer eine explizite Bestätigung und häufig Step-up Auth. Autonome Ausführung ist nicht erlaubt.

Forbidden for AI

Tools dieser Stufe dürfen von einem KI-Agenten weder gelesen noch ausgeführt werden. Sie sind aus der Tool Discovery für Agents vollständig ausgeblendet. Die Klassifizierung ist eine harte Grenze, keine Policy-Entscheidung.

Idempotenz

Viele Tools werden in Agenten-Workflows mehrfach aufgerufen, durch Retries, Parallelausführung oder fehlerhafte Planung. MCP-first empfiehlt, Tools wo möglich idempotent zu gestalten: gleicher Input führt bei mehrfachem Aufruf zum selben Ergebnis, ohne unerwünschte Duplikate oder Nebenwirkungen zu erzeugen.

Das Tool create_download_link ist ein gutes Beispiel. Wenn für eine Datei mit demselben fileId und demselben expiresAt bereits ein gültiger Link existiert, gibt das Tool diesen zurück, statt einen zweiten zu erzeugen:

create_download_link(fileId: "f_abc123", expiresAt: "2025-12-31T23:59:00Z")

→ Erster Aufruf: erzeugt neuen Link, gibt linkId + url zurück
→ Zweiter Aufruf (gleiche Parameter, Link noch gültig): gibt denselben Link zurück
→ Dritter Aufruf (Link abgelaufen): erzeugt neuen Link

Idempotenz muss explizit implementiert werden, sie entsteht nicht automatisch. Das Tool Contract Feld sideEffects sollte das Verhalten bei Wiederholung beschreiben, damit Agents und Clients es korrekt einplanen können.

Dry Run

Riskante Tools, insbesondere solche mit Massen-Effekten, sollten einen Dry-Run-Modus anbieten. Der Dry Run führt alle Validierungen und Prüfungen durch, erzeugt aber keine echten Side Effects. Das Ergebnis zeigt, was passieren würde, ohne dass etwas tatsächlich passiert.

emails.bulk_send mit dryRun: true liefert eine vollständige Vorschau:

// Request
{
  "tool": "emails.bulk_send",
  "params": {
    "templateId": "tmpl_newsletter_q3",
    "segmentId": "seg_active_customers",
    "dryRun": true
  }
}

// Response
{
  "dryRun": true,
  "recipientCount": 4821,
  "sampleMessages": [
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Liebe Anna, im dritten Quartal haben wir…"
    },
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Lieber Max, im dritten Quartal haben wir…"
    }
  ],
  "warnings": [
    "43 Empfänger haben keinen Vornamen, Fallback 'Hallo' wird verwendet.",
    "12 E-Mail-Adressen sind als unzustellbar markiert und werden übersprungen."
  ],
  "missingPermissions": [],
  "expectedSideEffects": [
    "4821 externe E-Mails werden versendet.",
    "4821 Audit-Events vom Typ email.external.sent werden erzeugt.",
    "Kampagnen-Status wird auf 'sent' gesetzt."
  ],
  "estimatedDurationMs": 18400
}

Erst nach Prüfung des Dry-Run-Ergebnisses und expliziter Bestätigung durch den Nutzer erfolgt der echte Aufruf ohne dryRun. Der Agent darf den Dry Run nicht überspringen, wenn das Tool ihn als erforderlich deklariert.