Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Tools definieren

Leite aus den Anwendungsfällen deines Plugins gezielt die passenden MCP-Tools ab.

Über Tools stellt der MCP-Server eines Plugins ChatGPT und Codex Aktionen und Daten zur Verfügung. Definiere die Tools, nachdem du Ideen für Anwendungsfälle gesammelt hast und bevor du den Server implementierst.

Jedes Tool sollte dabei helfen, ein konkretes Ziel zu erreichen. Bevor du eine interne API nachbildest, überlege, wie Menschen nach der jeweiligen Funktion fragen und wie sie sie nutzen werden.

Anwendungsfällen Tools zuordnen

Gehe für jeden unterstützten Anwendungsfall so vor:

  1. Halte fest, welches Ergebnis die Person erwartet, die die Anfrage stellt.
  2. Liste die Informationen auf, die für dieses Ergebnis nötig sind.
  3. Ermittle, welche Lese- und Schreibvorgänge oder externen Aktionen der Server ausführen muss.
  4. Fasse Vorgänge zusammen, die gemeinsam eine in sich geschlossene Aktion bilden.
  5. Trenne Vorgänge, wenn sie unterschiedliche Berechtigungen erfordern, unterschiedliche Sicherheitsrisiken bergen oder unterschiedliche Anforderungen an die Bestätigung stellen.

Ein Plugin zur Projektverwaltung könnte beispielsweise diese Tools bereitstellen:

  • list_projects, um Projekte zu finden.
  • get_project, um die Details eines einzelnen Projekts abzurufen.
  • create_project, um ein Projekt zu erstellen.
  • update_project, um Projektdetails zu ändern.
  • archive_project, um eine Zustandsänderung mit weitreichenden Folgen vorzunehmen.

Trenne Lese- und Schreibvorgänge, damit sowohl das Modell als auch die Menschen, die das Tool nutzen, erkennen können, ob eine Aktion Informationen abruft oder den Zustand verändert.

Schnittstelle für jedes Tool festlegen

Halte für jedes geplante Tool Folgendes fest:

Feld Was du festlegen solltest
Name Eine stabile Kennung, aus der die Aktion hervorgeht.
Titel Eine kurze, verständliche Bezeichnung für die Aktion.
Beschreibung Das Ziel der anfragenden Person und die Bedingungen, unter denen das Modell das Tool aufrufen sollte.
Eingabeschema Erforderliche und optionale Parameter, ihre Typen, zulässigen Werte und Grenzwerte.
Ausgabeschema Strukturierte Felder, die das Modell auswerten und wiederverwenden kann.
Autorisierung Welches Konto, welche Rolle oder welche Zugriffsrechte für eine Ressource der Server überprüfen muss.
Nebenwirkungen Welche Daten oder welchen externen Zustand das Tool verändern kann.
Verhalten bei Fehlern Welche Fehler das Modell erklären kann oder nach welchen Fehlern es den Vorgang fortsetzen kann.

Gib die erforderlichen Eingaben ausdrücklich vor. Das Modell sollte weder Kennungen noch den Geltungsbereich eines Kontos oder andere für die korrekte Ausführung erforderliche Werte erraten müssen.

Gib stabile Kennungen und genügend strukturierte Informationen für nachfolgende Aufrufe zurück. Die Ergebnisse dürfen keine Geheimnisse, Zugriffstoken, internen Diagnosedaten oder unnötigen personenbezogenen Daten enthalten.

Beschreibungen für die Tool-Auswahl formulieren

Anhand der Beschreibung entscheidet das Modell, ob ein Tool zu einer Anfrage passt. Beschreibe, was die anfragende Person erreichen möchte. Lass Details zur Implementierung weg.

Eine gute Beschreibung erfüllt folgende Aufgaben:

  • Sie benennt, was das Tool tut.
  • Sie erklärt, wann es eingesetzt werden sollte.
  • Sie macht deutlich, wie es sich von ähnlichen Tools unterscheidet.
  • Sie weist auf wichtige Einschränkungen oder Voraussetzungen hin.

Vermeide Beschreibungen, die lediglich den Namen des Tools wiederholen oder interne Begriffe aus einem Dienst verwenden, die Außenstehende nicht kennen.

Sicherheitsannotationen planen

Wähle die Annotationen nach dem tatsächlichen Verhalten des Tools. Die maßgeblichen Definitionen, die Standardwerte und das Zusammenspiel dieser Hinweise sind im MCP-Schema ToolAnnotations beschrieben:

  • readOnlyHint hat nur dann den Wert true, wenn das Tool keinen Zustand verändern kann.
  • destructiveHint hat den Wert true, wenn das Tool Änderungen bewirken kann, die sich nicht oder nur schwer rückgängig machen lassen.
  • openWorldHint hat den Wert true, wenn das Tool auf das öffentliche Internet oder auf externe Ressourcen zugreift, deren Kreis nicht von vornherein begrenzt ist. Das gilt auch für Aktionen ohne Schreibzugriff wie die Websuche. Ein privates Konto oder ein privater Workspace mit klar begrenztem Umfang gilt nicht allein deshalb als offene Umgebung, weil das Hosting extern erfolgt.

Annotationen ersetzen weder die serverseitige Autorisierung noch die Prüfung der Eingaben oder die Bestätigung von Aktionen mit weitreichenden Folgen.

Abdeckung und Grenzen prüfen

Gleiche die geplanten Tools mit der vollständigen Liste der Anwendungsfälle ab:

  1. Stelle sicher, dass sich für jeden unterstützten Anwendungsfall ein nützliches Ergebnis erzielen lässt.
  2. Ermittle, welche Tools keinem dokumentierten Anwendungsfall dienen.
  3. Prüfe, ob Lesevorgänge fehlen, die vor einem Schreibvorgang nötig sind, um die erforderlichen Informationen abzurufen.
  4. Vergewissere dich, dass bei nicht unterstützten Anfragen die Einschränkung verständlich erklärt wird, statt die Anfrage auf unsichere Weise näherungsweise zu erfüllen.
  5. Teste, ob sich die Beschreibungen zweier ähnlicher Tools so überschneiden, dass das Modell sie bei der Auswahl verwechseln könnte.

Nutze den fertigen Tool-Plan als Checkliste für die Implementierung und Evaluierung. Implementiere anschließend den MCP-Server und teste jede Tool-Schnittstelle mit repräsentativen Eingaben, mit ungültigen Eingaben und mit Eingaben, für die die nötige Berechtigung fehlt.