Tool-Granularität bei LLM-Agenten: Was uns 20 Workflow-Konfigurationen gelehrt haben

Die Faustregeln rund um Tools für LLM-Agenten laufen meist auf eine von zwei Parolen hinaus: „Gib dem Modell weniger Tools, damit es nicht durcheinanderkommt“, oder „Mache jede Operation als Tool verfügbar, damit das Modell frei komponieren kann“. Beide liegen auf interessante Weise daneben. Wir haben AgentDoc gebaut – einen MCP-gesteuerten Dokumenten-Editor – unter anderem, um einen glaubwürdigen Prüfstand für diese Frage zu haben, und wir haben 20 Workflow-Konfigurationen (A–T) über 13 Benchmark-Szenarien laufen lassen, um zu sehen, was wirklich etwas bewegt.

Dieser Beitrag fasst zusammen, was wir herausgefunden haben; hier konzentrieren wir uns auf die praktischen Erkenntnisse für alle, die Tools für LLM-Agenten entwerfen – ob für einen MCP-Server, eine Function-Calling-API oder einen eigenen Orchestrator.

Der Aufbau, kurz gefasst

Jede Konfiguration ist eine andere Kombination aus (a) Tool-Oberfläche – atomar vs. zusammengesetzt vs. gemischt; (b) Workflow-Steuerung – reines ReAct-Prompting vs. zustandsbeschränkter ReAct-FSM; und (c) Verifizierungsrichtlinie – optionaler vs. verpflichtender get_document_context-Aufruf nach jeder Mutation. Die Konfigurationen reichen von einer monolithischen Zero-Shot-Baseline (ein riesiges edit_document-Tool, keine FSM) bis hin zu einer streng kontrollierten FSM mit 35 atomaren Primitiven.

Die Bewertung verwendet die Levenshtein-Distanz auf dem finalen Dokument, plus Token-Verbrauch und explizite Halluzinations-Zählungen (Tool-Aufrufe, die auf Indizes verweisen, die nicht existieren).

Erkenntnis 1: „weniger Tools“ gewinnt bei Tokens, verliert bei Genauigkeit

Die monolithische edit_document-Baseline ist bei den Tokens mit Abstand am günstigsten – das Modell gibt einen großen Aufruf aus und wir sind fertig. Aber ihre Levenshtein-Werte sind bei mehrstufigen Aufgaben rund 3× schlechter als die der atomaren Tool-Konfigurationen, weil das Modell die gesamte Mutation in einem einzigen Vorwärtsdurchlauf planen muss, ohne die Möglichkeit, Zwischenzustände zu verifizieren.

Bei langen Dokumenten scheitert dieses Vorgehen völlig: Das Modell gibt eine Bearbeitung aus, die auf eine Überschrift verweist, die am angenommenen Offset nicht mehr existiert (weil frühere hypothetische Bearbeitungen „im selben Plan“ die Indizes verschoben haben), und das Ergebnis ist ein beschädigtes Dokument, das selbst für den nächsten Agenten-Zug schwer nachvollziehbar ist.

Erkenntnis 2: „jede Operation als Tool“ gewinnt bei Genauigkeit, verliert bei Tokens – und an Klippen

Rein atomare Tools (separate find, delete_substring, insert_string usw.) verlagern die Verifizierung in die Reasoning-Schleife des Modells. Bei instruktions-getunten Frontier-Modellen ist die Genauigkeit hoch – aber die Token-Zahlen explodieren, und wir beobachten eine scharfe Klippe bei rund 25 Tools an der Oberfläche: darüber beginnt das Modell, zwischen nahezu synonymen Tools falsch zu wählen (insert_paragraph vs. insert_text vs. append_text), was ein eigener Fehlermodus ist, der in den 8-Tool-Konfigurationen nicht auftritt.

Die Anzahl der Tools interagiert mit der Benennungs-Entropie. Zwanzig Tools, deren Namen sich semantisch ballen (insert_*, append_*, prepend_*), sind für das Modell schwieriger als dreißig Tools, die offensichtlich verschiedene Verben abdecken.

Erkenntnis 3: ein kleiner Satz gut benannter Makros ist der Sweet Spot

Die Konfigurationen, die im gemeinsamen Genauigkeits-/Token-Score am höchsten abschnitten, teilen eine Struktur: atomare Primitive für den Long Tail, plus drei bis fünf gut benannte Makros für die offensichtlichen, häufigen Pfade (replace_all, format_all_matches, convert_paragraph_to_heading). Die Makros eliminieren die häufigsten mehrstufigen Sequenzen – sie kürzen 4 Round-Trips auf 1 – ohne das Modell zu zwingen, sie von Grund auf zusammenzusetzen.

Der Clou ist nicht die Anzahl der Makros; es ist, dass jedes Makro einer natürlichsprachlichen Anfrage entsprechen muss, die Nutzer tatsächlich stellen. Makros, die aus Gründen der Code-Eleganz erfunden wurden („composeFormatBatch“), werden vom Modell zugunsten der atomaren Primitive ignoriert. Makros, die nach häufigen Anfragen benannt sind („ersetze alle X durch Y“), werden sofort und korrekt verwendet.

Erkenntnis 4: strukturelle Verifizierung schlägt geprompte Verifizierung

Dem Modell zu sagen „lies das Dokument vor jeder Mutation erneut“ funktioniert manchmal. Eine zustandsbeschränkte ReAct-FSM, die die Schreib-Tools sperrt, bis ein get_document_context-Aufruf abgeschlossen ist, funktioniert immer. Die FSM-Konfigurationen senkten halluzinierte Index-Fehler von ~14 % in der reinen Prompt-Bedingung auf unter 2 % – und die Kosten sind ein einziger zusätzlicher Round-Trip alle paar Züge, was gegenüber einer beschädigten Bearbeitung billig ist.

Das ist die stärkste praktische Erkenntnis der gesamten Studie: Wenn dein Agent gegen index-sensitiven Zustand arbeitet (ein Dokument, einen Puffer, einen Syntaxbaum), verlasse dich nicht allein auf Prompts. Mache die Verifizierung in der Tool-Oberfläche selbst strukturell unvermeidlich.

Erkenntnis 5: Index-Drift ist ein Tool-Design-Bug, kein Modell-Bug

Wir haben immer wieder gesehen, dass die schlechtesten Konfigurationen nach keiner Fähigkeits-Metrik „schwach“ waren – sie stellten lediglich Tools bereit, deren Verträge es dem Modell erlaubten, lokal zu gelingen und global zu scheitern. Ein Tool, das einen Zeichenindex entgegennimmt und Erfolg zurückmeldet, ohne dem Modell mitzuteilen, dass sich alles nach diesem Index verschoben hat, ist der Bug. Frontier-Modelle lernen mit der Zeit, das auszugleichen. Deine Tool-Oberfläche sollte es nicht von ihnen verlangen.

Konkret: Jedes Mutations-Tool in AgentDoc gibt eine strukturierte Payload zurück, die einen Dirty-Range-Deskriptor enthält ({shifted_after: 412, delta: -23}). Der nächste Tool-Aufruf sieht das, und die FSM erzwingt ein erneutes Einlesen. Halluzinationen sanken dadurch nahezu auf den Boden.

Was das bedeutet, wenn du einen Agenten baust

Drei Faustregeln, die mehr wert sind als jede konkrete Zahl oben:

• Standardmäßig atomare Primitive, ergänzt um Makros für natürlichsprachliche Pfade. Optimiere nicht vorzeitig auf Token-Kosten; sie sind billiger als eine beschädigte Bearbeitung.
• Halte die Tool-Oberfläche unter 25 Tools, oder teile sie in namentlich klar unterscheidbare Familien auf. Cluster-Mehrdeutigkeit ist ein echter Fehlermodus.
• Mache die Verifizierung strukturell. Eine FSM, die Schreib-Tools hinter einem kürzlichen erneuten Einlesen sperrt, kostet fast nichts und eliminiert die gesamte Klasse von Index-Drift-Bugs.

Der nächste Beitrag dieser Reihe behandelt die Voice-First-Architektur – einschließlich der Gründe, warum wir Gemini Live direkt an die MCP-Oberfläche angebunden haben statt über einen Transkriptions-Proxy. Die Entscheidung ergibt sich direkt aus genau den obigen Erkenntnissen.