Tool-Design

Tool-Design für Agenten

Entwerfen Sie jedes Tool als Vertrag zwischen einem deterministischen System und einem nicht-deterministischen Agenten. Anders als bei menschlichen APIs müssen Agenten-Tools den Vertrag allein durch die Beschreibung eindeutig machen: Agenten leiten die Absicht aus Beschreibungen ab und generieren Aufrufe, die den erwarteten Formaten entsprechen müssen. Jede Mehrdeutigkeit wird zu einem potenziellen Fehlermodus, den kein Prompt-Engineering beheben kann.

Die Arbeitseinheit dieser Fähigkeit ist ein einzelnes Tool oder ein Tool-Katalog. Entscheidungen über Projektform, Pipeline-Architektur, Aufgabenmodell-Passung und Kosten auf Projektebene gehören zu project-development. Entscheidungen über die Einführung von Sub-Agents gehören zu multi-agent-patterns. Diese Fähigkeit besitzt die Schnittstellenschicht, die deterministischen Code mit dem Agenten verbindet.

Wann zu aktivieren

Aktivieren Sie diese Fähigkeit, wenn die Arbeitseinheit ein Tool ist:

• Schreiben einer neuen Tool-Beschreibung, eines neuen Schemas oder Antwortformats.
• Debuggen von Fällen, in denen der Agent das falsche Tool ausgewählt oder fehlerhafte Aufrufe generiert hat.
• Konsolidieren eines überlappenden Tool-Katalogs (der klassische Fall „Wir haben 17 Tools, der Agent wählt in der Hälfte der Fälle das falsche aus“).
• Entwerfen umsetzbarer Fehlermeldungen, damit der Agent sich selbst korrigieren kann.
• Konsistente Benennung von Tools und Parametern in einem Katalog (MCP-Namensräume, Verb-Nomen-Benennung).
• Evaluieren eines Drittanbieter-Tools anhand des Konsolidierungsprinzips, bevor es hinzugefügt wird.

Aktivieren Sie diese Fähigkeit nicht für angrenzende Arbeiten, die von anderen Fähigkeiten bearbeitet werden:

• Entscheidung, ob das Projekt überhaupt LLMs verwenden soll oder wie die Phasen der Pipeline aussehen sollen: project-development.
• Entscheidung, ob die Arbeit auf Sub-Agents aufgeteilt oder ein einzelner Agent mit mehr Tools betrieben werden soll: multi-agent-patterns.
• Reduzierung des Token-Gewichts von Tool-Ausgaben auf Trajektorienebene (Beobachtungsmaskierung, Formatwahl im großen Maßstab): context-optimization.

Kernkonzepte

Entwerfen Sie Tools nach dem Konsolidierungsprinzip: Wenn ein menschlicher Ingenieur nicht definitiv sagen kann, welches Tool in einer bestimmten Situation verwendet werden sollte, kann von einem Agenten nicht erwartet werden, dass er besser abschneidet. Reduzieren Sie die Tool-Menge, bis jedes Tool einen eindeutigen Zweck hat, denn Agenten wählen Tools durch Vergleich von Beschreibungen aus, und jede Überlappung führt zu Auswahlfehlern.

Behandeln Sie jede Tool-Beschreibung als Prompt-Engineering, das das Agentenverhalten prägt. Die Beschreibung ist keine Dokumentation für Menschen – sie wird in den Kontext des Agenten injiziert und steuert direkt das Denken. Schreiben Sie Beschreibungen, die beantworten, was das Tool tut, wann es verwendet wird und was es zurückgibt, denn diese drei Fragen sind genau das, was Agenten bei der Tool-Auswahl evaluieren.

Detaillierte Themen

Die Tool-Agenten-Schnittstelle

Tools als Verträge Entwerfen Sie jedes Tool als eigenständigen Vertrag. Wenn Menschen APIs aufrufen, lesen sie Dokumentation, verstehen Konventionen und stellen angemessene Anfragen. Agenten müssen den gesamten Vertrag aus einem einzigen Beschreibungsblock ableiten. Machen Sie den Vertrag eindeutig, indem Sie Formatbeispiele, erwartete Muster und explizite Einschränkungen aufnehmen. Lassen Sie nichts aus, was ein Aufrufer wissen muss, denn Agenten können vor einem Aufruf keine klärenden Fragen stellen.

Tool-Beschreibung als Prompt Schreiben Sie Tool-Beschreibungen in dem Wissen, dass sie direkt in den Agentenkontext geladen werden und gemeinsam das Verhalten steuern. Eine vage Beschreibung wie „Datenbank durchsuchen“ mit kryptischen Parameternamen zwingt den Agenten zum Raten – und Raten führt zu falschen Aufrufen. Fügen Sie stattdessen Nutzungskontext, Parameterformatbeispiele und sinnvolle Standardwerte hinzu. Jedes Wort in der Beschreibung hilft oder schadet der Genauigkeit der Tool-Auswahl.

Namensräume und Organisation Verwenden Sie Namensräume für Tools unter gemeinsamen Präfixen, wenn die Sammlung wächst, denn Agenten profitieren von hierarchischer Gruppierung. Wenn ein Agent Datenbankoperationen benötigt, navigiert er zum Namespace db_*; wenn er Webinteraktionen benötigt, zu web_*. Ohne Namensräume müssen Agenten jedes Tool in einer flachen Liste bewerten, was die Auswahlgenauigkeit mit zunehmender Anzahl verschlechtert.

Das Konsolidierungsprinzip

Einzelne umfassende Tools Erstellen Sie einzelne umfassende Tools anstelle mehrerer enger, sich überschneidender Tools. Implementieren Sie anstelle von list_users, list_events und create_event separat ein Tool schedule_event, das Verfügbarkeit findet und in einem Aufruf plant. Das umfassende Tool erledigt den gesamten Workflow intern und entlastet den Agenten von der Verkettung von Aufrufen in der richtigen Reihenfolge.

Warum Konsolidierung funktioniert Wenden Sie Konsolidierung an, weil Agenten begrenzten Kontext und Aufmerksamkeit haben. Jedes Tool in der Sammlung konkurriert um Aufmerksamkeit während der Tool-Auswahl, jede Beschreibung verbraucht Kontextbudget-Token, und überlappende Funktionalität schafft Mehrdeutigkeit. Konsolidierung beseitigt redundante Beschreibungen, entfernt Auswahlmehrdeutigkeit und verkleinert die effektive Tool-Menge. Die Vercel d0-Fallstudie ist ein konkretes Beispiel für die Reduzierung spezialisierter Tools auf eine kleinere Menge primitiver Tools mit besseren gemessenen Ergebnissen.

Wann nicht zu konsolidieren Halten Sie Tools getrennt, wenn sie grundlegend unterschiedliche Verhaltensweisen haben, in unterschiedlichen Kontexten verwendet werden oder unabhängig voneinander aufrufbar sein müssen. Überkonsolidierung schafft ein anderes Problem: Ein einzelnes Tool mit zu vielen Parametern und Modi wird für Agenten schwer korrekt zu parametrisieren.

Architektonische Reduktion

Treiben Sie das Konsolidierungsprinzip auf die logische Spitze, indem Sie die meisten spezialisierten Tools zugunsten primitiver, universell einsetzbarer Fähigkeiten entfernen. Produktionsbelege zeigen, dass dieser Ansatz anspruchsvolle Multi-Tool-Architekturen übertreffen kann.

Das Dateisystem-Agenten-Muster Ermöglichen Sie direkten Dateisystemzugriff durch ein einziges Befehlsausführungstool, anstatt benutzerdefinierte Tools für Datenexploration, Schemaabfrage und Abfragevalidierung zu bauen. Der Agent verwendet Standard-Unix-Dienstprogramme (grep, cat, find, ls), um das System zu erkunden und zu bedienen. Dies funktioniert, weil Dateisysteme eine bewährte Abstraktion sind, die Modelle tief verstehen, Standardtools vorhersehbares Verhalten haben, Agenten Primitive flexibel verketten können, anstatt auf vordefinierte Workflows beschränkt zu sein, und gute Dokumentation in Dateien Zusammenfassungstools ersetzt.

Wann Reduktion Komplexität übertrifft Wählen Sie Reduktion, wenn die Datenebene gut dokumentiert und konsistent strukturiert ist, das Modell über ausreichende Argumentationsfähigkeit verfügt, spezialisierte Tools das Modell eher eingeschränkt als befähigt haben oder mehr Zeit mit der Wartung des Gerüsts als mit der Verbesserung der Ergebnisse verbracht wird. Vermeiden Sie Reduktion, wenn die zugrundeliegenden Daten chaotisch oder schlecht dokumentiert sind, die Domäne spezialisiertes Wissen erfordert, das dem Modell fehlt, Sicherheitsauflagen die Agentenaktionen einschränken müssen oder Operationen tatsächlich von strukturierten Workflows profitieren.

Bauen für zukünftige Modelle Entwerfen Sie minimale Architekturen, die von Modellverbesserungen profitieren, anstelle ausgefeilter Architekturen, die aktuelle Einschränkungen festschreiben. Fragen Sie, ob jedes Tool neue Fähigkeiten ermöglicht oder das Denken einschränkt, das das Modell selbst bewältigen könnte – Tools, die als „Schutzmaßnahmen“ gebaut wurden, werden oft zu Verbindlichkeiten, wenn Modelle besser werden.

Siehe Fallstudie zur architektonischen Reduktion für Produktionsbelege.

Tool-Beschreibungs-Engineering

Struktur der Beschreibung Strukturieren Sie jede Tool-Beschreibung, um vier Fragen zu beantworten:

1. Was macht das Tool? Geben Sie genau an, was das Tool erreicht – vermeiden Sie vage Formulierungen wie „hilft bei“ oder „kann verwendet werden für“.
2. Wann sollte es verwendet werden? Geben Sie direkte Auslöser („Benutzer fragt nach Preisen“) und indirekte Signale („Aktuelle Marktpreise erforderlich“) an.
3. Welche Eingaben akzeptiert es? Beschreiben Sie jeden Parameter mit Typ, Einschränkungen, Standardwerten und Formatbeispielen.
4. Was gibt es zurück? Dokumentieren Sie das Ausgabeformat, die Struktur, erfolgreiche Antwortbeispiele und Fehlerbedingungen.

Auswahl von Standardparametern Setzen Sie Standardwerte so, dass sie häufige Anwendungsfälle widerspiegeln. Standardwerte verringern die Belastung des Agenten, indem sie die Angabe unnötiger Parameter eliminieren, und verhindern Fehler durch weggelassene Parameter. Wählen Sie Standardwerte, die nützliche Ergebnisse liefern, ohne dass der Agent jede Option verstehen muss.

Optimierung des Antwortformats

Bieten Sie Optionen für das Antwortformat (prägnant vs. detailliert) an, da die Größe der Tool-Antwort erheblichen Einfluss auf die Kontextnutzung hat. Das prägnante Format gibt nur wesentliche Felder zurück und eignet sich für Bestätigungen. Das detaillierte Format gibt vollständige Objekte zurück und eignet sich, wenn der vollständige Kontext Entscheidungen antreibt. Dokumentieren Sie in der Tool-Beschreibung, wann welches Format verwendet werden soll, damit Agenten lernen, angemessen auszuwählen.

Fehlermeldungsdesign

Entwerfen Sie Fehlermeldungen für zwei Zielgruppen: Entwickler, die Probleme beheben, und Agenten, die sich von Fehlern erholen. Für Agenten muss jede Fehlermeldung umsetzbar sein – sie muss angeben, was schiefgelaufen ist und wie es korrigiert werden kann. Fügen Sie Wiederholungshinweise für wiederholbare Fehler, korrigierte Formatbeispiele für Eingabefehler und spezifische fehlende Felder für unvollständige Anfragen hinzu. Eine Fehlermeldung, die nur „fehlgeschlagen“ besagt, liefert kein Wiederherstellungssignal.

Tool-Definitionsschema

Etablieren Sie ein einheitliches Schema für alle Tools. Verwenden Sie das Verb-Nomen-Muster für Toolnamen (get_customer, create_order), konsistente Parameternamen über Tools hinweg (immer customer_id, nie manchmal id und manchmal identifier) und konsistente Rückgabefeldnamen. Konsistenz reduziert die kognitive Belastung für Agenten und verbessert die Generalisierung über Tools hinweg.

Tool-Sammlungsdesign

Beschränken Sie Tool-Sammlungen auf die kleinste Menge mit sich nicht überschneidenden Zwecken, denn Beschreibungsüberlappung verursacht Verwirrung beim Modell und mehr Tools führen nicht immer zu besseren Ergebnissen. Wenn tatsächlich mehr Tools benötigt werden, verwenden Sie Namensräume, um logische Gruppierungen zu erstellen. Implementieren Sie Auswahlmechanismen: Tool-Gruppierung nach Domäne, beispielbasierte Auswahlhinweise und Dach-Tools, die an spezialisierte Unter-Tools weiterleiten.

MCP-Tool-Benennungsanforderungen

Verwenden Sie immer vollqualifizierte Toolnamen mit MCP (Model Context Protocol), um „Tool nicht gefunden“-Fehler zu vermeiden.

Format: ServerName:tool_name

# Korrekt: Vollqualifizierte Namen
"Verwenden Sie das BigQuery:bigquery_schema-Tool, um Tabellenschemata abzurufen."
"Verwenden Sie das GitHub:create_issue-Tool, um Issues zu erstellen."

# Falsch: Nicht qualifizierte Namen
"Verwenden Sie das bigquery_schema-Tool..."  # Kann bei mehreren Servern fehlschlagen

Ohne das Server-Präfix können Agenten Tools möglicherweise nicht finden, wenn mehrere MCP-Server verfügbar sind. Etablieren Sie Namenskonventionen, die den Serverkontext in allen Tool-Referenzen enthalten.

Agenten zur Optimierung von Tools einsetzen

Führen Sie beobachtete Tool-Fehler an einen Agenten zurück, um Probleme zu diagnostizieren und Beschreibungen zu verbessern. Behandeln Sie gemeldete Effizienzsteigerungen als workload-spezifisch, bis sie im Ziel-Tool-Katalog reproduziert wurden.

Das Tool-Test-Agenten-Muster:

def optimize_tool_description(tool_spec, failure_examples):
    """
    Verwenden Sie einen Agenten, um Tool-Fehler zu analysieren und Beschreibungen zu verbessern.

    Ablauf:
    1. Agent versucht, das Tool für verschiedene Aufgaben zu verwenden
    2. Sammeln von Fehlermodi und Reibungspunkten
    3. Agent analysiert Fehler und schlägt Verbesserungen vor
    4. Testen der verbesserten Beschreibungen mit denselben Aufgaben
    """
    prompt = f"""
    Analysieren Sie diese Tool-Spezifikation und die beobachteten Fehler.

    Tool: {tool_spec}

    Beobachtete Fehler:
    {failure_examples}

    Identifizieren Sie:
    1. Warum Agenten mit diesem Tool scheitern
    2. Welche Informationen in der Beschreibung fehlen
    3. Welche Mehrdeutigkeiten zu falscher Nutzung führen

    Schlagen Sie eine verbesserte Tool-Beschreibung vor, die diese Probleme adressiert.
    """

    return get_agent_response(prompt)

Dies erzeugt eine Rückkopplungsschleife: Agenten, die Tools verwenden, generieren Fehlerdaten, die Agenten dann zur Verbesserung der Tool-Beschreibungen nutzen, was zukünftige Fehler reduziert.

Tool-Design testen

Bewerten Sie Tool-Designs anhand von fünf Kriterien: Eindeutigkeit, Vollständigkeit, Wiederherstellbarkeit, Effizienz und Konsistenz. Testen Sie, indem Sie repräsentative Agentenanfragen präsentieren und die resultierenden Tool-Aufrufe mit dem erwarteten Verhalten vergleichen.

Praktische Anleitung

Tool-Auswahl-Framework

Beim Entwerfen von Tool-Sammlungen:

1. Identifizieren Sie unterschiedliche Workflows, die Agenten ausführen müssen
2. Gruppieren Sie verwandte Aktionen in umfassenden Tools
3. Stellen Sie sicher, dass jedes Tool einen klaren, eindeutigen Zweck hat
4. Dokumentieren Sie Fehlerfälle und Wiederherstellungspfade
5. Testen Sie mit tatsächlichen Agenteninteraktionen

Tool-Prüfliste

Verwenden Sie diese Checkliste für jedes Tool, bevor Sie es zu einem Agenten hinzufügen:

1. Name: Verb-Nomen, in Namensräumen, wenn der Katalog mehrere Domänen hat.
2. Beschreibung: Gibt an, was das Tool tut, wann es verwendet wird und was es zurückgibt.
3. Schema: Jeder Parameter hat Typ, Einschränkungen, Standardwerte und Beispielwerte.
4. Rückgabeform: Erfolgs- und Fehler-Payloads sind dokumentiert und maschinenlesbar.
5. Wiederherstellung: Jeder Fehler teilt dem Agenten mit, was vor einem erneuten Versuch geändert werden muss.
6. Überlappung: Kein anderes Tool hat dasselbe Aktivierungsszenario.
7. Konsolidierungsentscheidung: Angrenzende enge Tools werden zusammengeführt, es sei denn, unabhängige Aufrufe sind erforderlich.
8. Token-Auswirkung: Große Antworten unterstützen ein prägnantes Modus- oder Dateireferenz-Modus.

Beispiele

Beispiel 1: Gut entworfenes Tool

def get_customer(customer_id: str, format: str = "concise"):
    """
    Kundeninformationen anhand der ID abrufen.

    Verwenden, wenn:
    - Benutzer nach spezifischen Kundendetails fragt
    - Kundenkontext für Entscheidungsfindung benötigt wird
    - Kundenidentität überprüft wird

    Args:
        customer_id: Format "CUST-######" (z.B. "CUST-000001")
        format: "concise" für Schlüsselfelder, "detailed" für vollständigen Datensatz

    Returns:
        Kundenobjekt mit den angeforderten Feldern

    Fehler:
        NOT_FOUND: Kunden-ID nicht gefunden
        INVALID_FORMAT: ID muss dem Muster CUST-###### entsprechen
    """

Beispiel 2: Schlechtes Tool-Design

Dieses Beispiel zeigt mehrere Anti-Patterns des Tool-Designs:

def search(query):
    """Datenbank durchsuchen."""

Probleme mit diesem Design:

1. Vager Name: „search“ ist mehrdeutig – wonach suchen, zu welchem Zweck?
2. Fehlende Parameter: Welche Datenbank? Welches Format soll die Abfrage haben?
3. Keine Rückgabebeschreibung: Was gibt diese Funktion zurück?

---

Hinweis: Dieses Dokument wurde mit Unterstützung von KI aus dem Englischen übersetzt und fachlich geprüft.