Tool-Use: Vertrag, Auswahl, Rückgabe

Ein Werkzeug ist ein Vertrag, kein Funktionsaufruf

Ein Werkzeug sieht im Code aus wie eine Funktion, verhält sich aber nicht wie eine. Eine Funktion wird von Code aufgerufen, der ihre Signatur kennt. Ein Werkzeug wird von einem Modell ausgewählt, das nur Text über die Funktion gelesen hat.

Werkzeugdefinition — Drei Felder: ein name, eine description in natürlicher Sprache und ein input_schema, das die erlaubten Argumente beschreibt. Aus diesen drei Feldern — und nur aus ihnen — entscheidet das Modell, ob und wie es das Werkzeug aufruft.

Damit ist die Werkzeugdefinition eine Benutzeroberfläche, deren einziger Nutzer ein Sprachmodell ist. Alles, was in einer normalen API die Dokumentation, der Typ und der Kontext des Aufrufers leisten, muss hier in diesen drei Feldern stehen. Was nicht dort steht, existiert für das Modell nicht.

Wo der Code läuft, entscheidet über die Verantwortung

Client-Werkzeuge

Laufen in deiner Anwendung. Das Modell antwortet mit stop_reason: tool_use, dein Code führt aus und schickt ein tool_result zurück. Autorisierung, Zugangsdaten und Prüfung liegen vollständig bei dir.

Server-Werkzeuge

Laufen bei der Modellinfrastruktur — etwa Websuche oder Codeausführung. Du bekommst das Ergebnis, ohne die Ausführung zu behandeln, und hast entsprechend weniger Kontrolle über den Vorgang.

Die Unterscheidung wirkt technisch und ist eine Sicherheitsaussage. Bei Client-Werkzeugen gibt es genau eine Stelle, an der geprüft wird — deine Ausführungsschicht — und sie liegt vollständig in deiner Hand. Bei Server-Werkzeugen ist die Ausführung Teil des Dienstes, und deine Kontrolle beschränkt sich darauf, ob du das Werkzeug anbietest.

Praktisch heißt das: Jede Regel, die für dich verbindlich ist, gehört an ein Client-Werkzeug oder davor. Ein Server-Werkzeug kann man anbieten oder weglassen — feiner steuern kann man es nicht.

Neben dem Ort gibt es einen zweiten Regler, der oft unbenutzt bleibt: wann überhaupt gewählt werden darf. In der Voreinstellung entscheidet das Modell je Runde selbst, ob es ein Werkzeug aufruft oder direkt antwortet. Man kann einen Aufruf stattdessen erzwingen, ein bestimmtes Werkzeug vorschreiben oder Werkzeuge ganz abschalten — und man kann die gleichzeitige Wahl mehrerer Werkzeuge unterbinden.

Der letzte Punkt verdient Aufmerksamkeit, weil parallele Aufrufe bequem und manchmal falsch sind. Zwei lesende Abfragen gleichzeitig sind ein Gewinn. Zwei schreibende Aufrufe gleichzeitig sind eine Wettlaufsituation, die dein Code auflösen muss — und drei parallele Aufrufe gegen ein System mit einem Verbindungslimit sind ein Ausfall. Wo Schreiboperationen im Spiel sind, ist ein Aufruf pro Runde die sicherere Voreinstellung.

Die Beschreibung ist die Schnittstelle

Weil die Auswahl aus Text erfolgt, ist die description das wichtigste Feld der Definition — wichtiger als der Name und oft wichtiger als das Schema. Sie muss vier Dinge beantworten, und zwar ohne Kenntnis des restlichen Systems.

• Wofür — welche Aufgabe erledigt dieses Werkzeug, in den Worten der Aufgabe, nicht des Systems.
• Wofür nicht — die Abgrenzung gegen das nächstähnliche Werkzeug. Genau hier entstehen Fehlgriffe.
• Was es voraussetzt — welche Argumente woher kommen und welche Form sie haben, inklusive Beispiel.
• Was es bewirkt — insbesondere, ob es etwas verändert. Ein lesendes und ein schreibendes Werkzeug dürfen nicht gleich klingen.

Die Empfehlung aus der Praxis ist knapp und lässt wenig Spielraum: Werkzeuge sollen in sich abgeschlossen, fehlerrobust und in ihrer beabsichtigten Verwendung äußerst klar sein. „Äußerst klar“ heißt hier nicht kurz. Eine Beschreibung, die drei Sätze länger ist und dafür einen Fehlgriff pro hundert Läufe verhindert, hat sich bezahlt gemacht.

Überlappung ist der häufigste Entwurfsfehler

Der am häufigsten beobachtete Fehler bei Werkzeugmengen ist benannt: aufgeblähte Werkzeugmengen, die zu viel Funktionalität abdecken oder zu mehrdeutigen Entscheidungspunkten darüber führen, welches Werkzeug zu verwenden ist.

Werkzeugdefinitionen kosten in jeder Runde

Werkzeuge sind nicht kostenlos vorhanden. Die tools-Liste — Namen, Beschreibungen und Schemata — zählt als Eingabe in jeder Anfrage, zusammen mit einem automatisch ergänzten Systemprompt für die Werkzeugnutzung. Bei einer Schleife über zwölf Runden wird eine Werkzeugliste also zwölfmal bezahlt.

Werkzeugsuche

Statt fünfzig Schemata vorab wird ein Suchwerkzeug mitgegeben, über das das Modell die restlichen bei Bedarf lädt. Lohnt sich etwa ab zwanzig Werkzeugen.

Programmatische Aufrufe

Eine Kette kleiner Aufrufe wird zu einem Skript zusammengefasst, das in einer Sandbox läuft. Die Zwischenergebnisse landen nie im Verlauf.

Caching der Definitionen

Senkt nicht die Tokenzahl, aber den Preis dafür. Der richtige Weg bei einer großen, aber stabilen Werkzeugmenge.

Kontextverdrängung

Entfernt alte Werkzeugergebnisse aus dem Verlauf, nicht die Definitionen. Wirkt auf die Ergebnisse, nicht auf die Liste.

Die empfohlene Reihenfolge ist billig und langweilig, was für sie spricht: Caching der Werkzeugdefinitionen vom ersten Tag an — der Aufschlag auf den Cache-Schreibvorgang liegt bei einem Viertel des Eingabepreises und rechnet sich bereits beim zweiten Treffer. Werkzeugsuche erst, wenn die Liste die Zwanzig überschreitet. Kontextverdrängung erst, wenn einzelne Läufe lang genug werden, dass frühe Ergebnisse belanglos sind. Programmatische Aufrufe erst, wenn sich wiederkehrende Ketten kleiner Aufrufe zeigen.

Damit das Caching greift, muss die Werkzeugliste stabil sein — in Reihenfolge und Inhalt. Eine Liste, die je Nutzer anders sortiert ist oder deren Beschreibungen einen Zeitstempel tragen, erzeugt bei jeder Anfrage einen neuen Präfix. Das ist der häufigste Grund dafür, dass ein aktiviertes Caching in der Rechnung nicht auftaucht.

Das Modell rät fehlende Argumente

Der Befund, der die meisten Validierungsentwürfe umwirft, steht offen in der Dokumentation: Enthält die Anfrage nicht genug Information für alle Pflichtparameter, kann das Modell einen plausiblen Wert erfinden, statt nachzufragen. Ob es nachfragt, hängt vom Modell und von der Eindeutigkeit der Anfrage ab — zugesichert ist es nicht.

Das ist keine Randnotiz. Es heißt, dass ein required-Feld im Schema die Existenz eines Wertes erzwingt, nicht seine Richtigkeit. Ein Werkzeug delete_records mit einem Pflichtfeld filter bekommt immer einen Filter — auch dann, wenn niemand einen genannt hat.

Drei Schichten der Prüfung am Werkzeugrand

Aus dem vorigen Abschnitt folgt eine Aufteilung, die sich im Code sauber trennen lässt. Jede Schicht prüft etwas anderes, und keine ersetzt eine andere.

Die hervorgehobene Schicht ist die, die am häufigsten fehlt, weil die erste sie zu erledigen scheint. Sie tut es nicht: Ein Schema beschreibt, wie ein Aufruf aussieht, nicht wer ihn stellen darf. Und sie darf ihre Eingaben nicht aus dem Modellkontext beziehen — Mandant, Nutzer und Rolle kommen aus der authentifizierten Sitzung.

Die Fehlermeldung ist Teil der Schnittstelle

Was ein Werkzeug im Fehlerfall zurückgibt, liest das Modell und richtet seinen nächsten Schritt danach. Damit ist der Fehlertext kein Protokolleintrag, sondern ein Teil des Vertrags — geschrieben für einen Leser, der nur diesen Text hat.

Unbrauchbar

Ein Stacktrace, eine Datenbankfehlernummer, ein leeres Objekt. Das Modell kann daraus keinen nächsten Schritt ableiten und erfindet einen.

Brauchbar

Eine Klasse (vorübergehend, dauerhaft, unberechtigt, nicht gefunden), ein Satz zur Ursache und, wenn es einen gibt, der mögliche nächste Schritt.

Gefährlich

Ein Fehler, der wie ein Erfolg aussieht: ein leeres Ergebnis ohne Hinweis darauf, dass die Abfrage scheiterte.

Zur Kennzeichnung gibt es einen eigenen Kanal: Das Ergebnis wird als Fehler markiert und trägt die Meldung im Inhalt. Diese Markierung zu setzen kostet nichts und ist der Unterschied zwischen einem Agenten, der wiederholt, und einem, der Nichtvorhandenes berichtet.

Was zurückkommt, ist fremde Eingabe — und kostet Kontext

Werkzeugrückgaben haben zwei Eigenschaften, die getrennt behandelt werden müssen und häufig zusammen übersehen werden. Sie sind groß und sie sind fremd.

Groß: Eine Abfrage, die 4.000 Zeilen liefert, legt diese 4.000 Zeilen in den Kontext — und in jede folgende Runde erneut. Die Gegenmittel sind bekannt und gehören ins Werkzeug, nicht in die Schleife: eine Obergrenze je Rückgabe, Blätterung mit einem Fortsetzungsschlüssel, und eine Zusammenfassung statt Rohdaten, wo der Agent ohnehin nur eine Aussage braucht.

Fremd: Der Inhalt einer Rückgabe stammt aus einer Datenbank, einer Webseite, einem Ticket — also aus einer Quelle, die jemand anderes befüllt. Er darf deshalb nie die Rolle einer Anweisung bekommen. Ein Ticket-Text, der „ignoriere alle vorherigen Vorgaben“ enthält, ist ein Datensatz und keine Vorgabe, und die Kennzeichnung dafür setzt das Werkzeug beim Zurückgeben, nicht das Modell beim Lesen.

Beim Begrenzen der Größe entscheidet die Art des Abschneidens. Eine harte Kürzung nach n Zeichen erzeugt den schlechtesten Fall: Der Agent sieht ein unvollständiges Ergebnis, das nicht als unvollständig erkennbar ist, und zieht Schlüsse aus einem Ausschnitt. Brauchbar sind zwei Formen — eine Blätterung mit Gesamtzahl und Fortsetzungsschlüssel, oder eine ausdrückliche Meldung, dass die Treffermenge zu groß ist und die Anfrage verengt werden muss.

Irreversibles braucht einen zweistufigen Vertrag

Für Aktionen, die sich nicht zurücknehmen lassen, reicht kein besseres Prompting und keine strengere Beschreibung. Der Schutz gehört in die Form des Vertrags selbst.

Werkzeug oder Code

Nicht jeder Schritt, den ein Agent braucht, gehört als Werkzeug angeboten. Die Grenze verläuft an der Frage, ob an dieser Stelle eine Entscheidung fällt.

Als Werkzeug anbieten

Wenn das Modell entscheiden soll, ob und womit der Schritt ausgeführt wird — und diese Entscheidung von Zwischenergebnissen abhängt.

Im Code erledigen

Wenn der Schritt immer folgt, wenn seine Argumente aus dem vorherigen Ergebnis eindeutig hervorgehen, oder wenn seine Reihenfolge feststeht.

Ein häufiges Beispiel: Nach jedem Schreibvorgang soll ein Protokolleintrag entstehen. Als Werkzeug angeboten, wird er manchmal vergessen — und niemand merkt es, weil das Vergessene genau die Spur ist, an der man es merken würde. Im Code an den Schreibvorgang gebunden, kann er nicht ausfallen. Das Modell hatte an dieser Stelle ohnehin nichts zu entscheiden.

Die Regel wirkt auch in die andere Richtung, und dort wird sie öfter verletzt. Ein Team, das Unzuverlässigkeit erlebt, neigt dazu, Werkzeuge zu Abläufen zusammenzufassen: ein Werkzeug onboard_employee, das intern fünf Schritte erledigt. Das behebt die Reihenfolge und verliert die Zwischenstände — scheitert Schritt drei, ist von außen nur ein Fehlschlag sichtbar, nicht wiederholbar und nicht lokalisierbar.

Was der Check prüft

• Die Bestandteile eines Werkzeugvertrags ihren Zuständigkeiten zuordnen.
• Eine überlappende Werkzeugmenge zusammenlegen, statt sie um ein weiteres Werkzeug zu ergänzen.
• Eine Werkzeugdefinition lesen und das Feld finden, das den Fehlgriff verursacht.
• Bei wachsender Werkzeugliste den Hebel wählen, der an der richtigen Kostenquelle ansetzt.
• Argumente so gestalten, dass sicherheitsrelevante Werte gar nicht erst erratbar sind.
• Werkzeugfehler als lesbaren Vertragsbestandteil gestalten, ohne Interna preiszugeben.
• Große Rückgaben begrenzen, ohne die Aussage zu verlieren.
• Für eine irreversible Aktion einen Vertrag entwerfen, in dem der gefährliche Aufruf nicht formulierbar ist.

Alle acht Punkte haben denselben Kern: Das Werkzeug ist die Stelle, an der ein probabilistisches System auf deterministische Systeme trifft. Was hier nicht erzwungen wird, wird nirgends erzwungen.