MCP-Tool-Annotationen: readOnlyHint und destructiveHint erklärt

MCP-Tool-Annotationen sind ein kleiner Metadatenblock (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), den ein Server an jedes Tool hängt, das er bereitstellt. So kann der Host am anderen Ende (Claude Desktop, Cursor, ein eigener MCP-Client) eine harmlose Abfrage von einer Änderung an deinen Daten unterscheiden, noch bevor er das Tool aufruft. Done setzt sie für alle seine 84 Tools und leitet sie direkt aus derselben Liste ab, die schon die Nur-Lese-Beschränkung von Tokens durchsetzt. Was über die Sicherheit angekündigt wird und was tatsächlich durchgesetzt wird, kann also nicht auseinanderlaufen.

Was bedeuten readOnlyHint, destructiveHint, idempotentHint und openWorldHint eigentlich?

• readOnlyHint: true, wenn der Aufruf nichts ändern kann. Die 34 Lese-Tools von Done (list_my_tasks, get_task, get_digest, fleet_status und die übrigen) tragen diesen Hinweis. Die anderen 50, die etwas anlegen, ändern oder löschen, tragen ihn nicht.
• destructiveHint: true, wenn der Aufruf etwas bereits Vorhandenes entfernt oder überschreibt, statt nur etwas hinzuzufügen. delete_task und delete_project sind die offensichtlichen Fälle. Auch update_task zählt dazu, denn ein Feld zu überschreiben zerstört, was vorher darin stand, auch wenn Löschungen in Done umkehrbar sind und sich aus dem Papierkorb wiederherstellen lassen.
• idempotentHint: true, wenn derselbe Schreibvorgang mit denselben Argumenten bei zweimaligem Aufruf denselben Zustand hinterlässt wie bei einmaligem. block_task oder set_step_status lassen sich gefahrlos wiederholen. Alles, was einen neuen Eintrag anhängt (comment_on_task, start_run, decompose_task), lässt sich nicht gefahrlos wiederholen und bekommt den Hinweis deshalb nicht.
• openWorldHint: ob das Tool über eine geschlossene, bekannte Menge von Ressourcen hinausgreift. Fast jedes Done-Tool berührt nur die Einträge deines eigenen Kontos, Kalenderverknüpfungen eingeschlossen. Dort steht der Hinweis also auf false. Die Ausnahmen sind die Konnektor-Tools (search_context, read_context, save_context), die in die Apps hineingreifen, die du verbunden hast, etwa Drive, Slack oder Notion, und das mit true anzeigen.

Warum braucht ein Host das, statt einfach das Modell zu fragen?

Weil nicht das Modell entscheidet, ob du gefragt wirst, sondern der Host, und er muss das entscheiden, bevor der Aufruf läuft, nicht danach. Ein Host, der Nur-Lese-Aufrufe durchlassen will, ohne dich zu unterbrechen, aber bei allem anhalten möchte, was Daten löscht oder überschreibt, braucht eine Stelle, an der er diesen Unterschied ablesen kann. Und diese Stelle darf nicht davon abhängen, dass das Modell bei jedem einzelnen Aufruf aus dem Namen oder der Beschreibung eines Tools die Absicht richtig errät.

Was passiert, wenn ein Server gar keine Annotationen angibt?

Das liest sich nicht als „wird schon passen“. Ein Host, der ein Tool nicht einordnen kann, muss vom Schlimmsten ausgehen: Ein Aufruf ohne Annotationen wird genauso behandelt wie ein ungeprüfter, destruktiver Schreibvorgang auf eine offene Welt, und das gilt auch für Lesezugriffe. Diese Lücke hat Done geschlossen. Eine Zeit lang wurden alle 84 Tools ohne Annotationsblock ausgeliefert. Ein Host, der bei allem nachfragt, was „nicht ausdrücklich nur lesend“ ist, musste deshalb bei allen 84 nachfragen, bei get_digest und list_my_tasks ebenso wie bei delete_task, weil ihm in der Übertragung nichts etwas anderes sagte.

Wie hält Done die Annotationen ehrlich?

Indem es sie aus derselben maßgeblichen Quelle ableitet, die die Bereichsprüfung ohnehin schon nutzt, statt von Hand eine zweite Kopie zu schreiben, die abweichen könnte. WRITE_TOOLS ist die Menge, die entscheidet, ob ein nur lesendes Token etwas überhaupt aufrufen darf. annotationsFor() liest dieselbe Menge, um readOnlyHint festzulegen. Ein destruktiver oder idempotenter Schreibvorgang wird gegen zwei weitere Mengen geprüft, DESTRUCTIVE_TOOLS und CONVERGENT_TOOLS, die nach derselben Logik aufgebaut sind (überschreibt oder entfernt es etwas, läuft es bei Wiederholung auf denselben Zustand hinaus). Es gibt also genau eine Stelle, die sagt, was ein Tool tut, und nicht einen Durchsetzungspfad und eine angekündigte Beschreibung, die sich stillschweigend widersprechen.

Ersetzen Annotationen die Freigabe oder die Beschränkung von Tokens?

Nein. Sie sind eine andere Ebene, die vor beiden liegt. Die Beschränkung des Tokens regelt, was ein Agent mit seinen Zugangsdaten überhaupt aufrufen darf. Die Freigabe in Done regelt, ob eine Aufgabe ohne Auto-OK abgeschlossen werden kann, ohne dass ein Mensch zustimmt. MCP-Annotationen sind das, worauf die Oberfläche des Hosts selbst reagieren kann, noch bevor eines von beiden erreicht ist, zum Beispiel indem sie dich einen destruktiven Aufruf an Ort und Stelle bestätigen lässt, statt dass du erst hinterher davon erfährst. Keines der drei ersetzt die anderen. Annotationen sind Hinweise für das Urteil des Hosts und keine Sicherheitsgrenze, auf die sich Done allein verlässt: Die Bereichsprüfung und die Freigabe setzen die tatsächlichen Grenzen weiterhin auf dem Server durch, egal was ein Host mit den Metadaten anfängt.