Wie viele Tools verkraftet ein Agent?

OpenAI rät zu weniger als 20 Funktionen zu Beginn eines Zuges. Anthropic schreibt, dass Claudes Tool-Auswahl ab 30 bis 50 Tools nachlässt, und empfiehlt Tool Search ab 10 Tools oder Definitionen über 10.000 Tokens. Darüber Tools bei Bedarf laden statt alle vorab.

Tool-Fehler als Exception werfen oder ans Modell zurückgeben?

Ausführungsfehler als Tool-Ergebnis zurückgeben, mit is_error true bei der Claude API oder isError true in MCP, damit sich das Modell korrigieren kann. Die MCP-Spezifikation reserviert JSON-RPC-Protokollfehler für unbekannte Tools und fehlerhafte Anfragen, von denen sich Modelle seltener erholen.

Ist ein Tool pro API-Endpunkt besser?

Meist nicht. Anthropic rät davon ab, jeden Endpunkt zu verpacken, und empfiehlt, mehrstufige Arbeit in einem Tool zu bündeln, OpenAI rät, Funktionen zusammenzulegen, die immer nacheinander aufgerufen werden. Weniger, dafür fähigere Tools verringern Auswahlfehler und sparen Kontext.

Tools für KI-Agenten gestalten

Q: Wie lang sollte eine Tool-Beschreibung sein?

Anthropic empfiehlt mindestens drei bis vier Sätze pro Tool, bei komplexen Tools mehr: was das Tool tut, wann man es nutzt und wann nicht, was jeder Parameter bedeutet und welche Grenzen es hat. Eine Einzeilenbeschreibung wie „Holt den Aktienkurs für ein Tickersymbol“ lässt das Modell raten.

Q: Kann ich MCP-Tool-Annotationen wie Read-only-Hinweisen trauen?

Nicht standardmäßig. Die MCP-Spezifikation verlangt, dass Clients Tool-Annotationen als nicht vertrauenswürdig behandeln, sofern sie nicht von vertrauenswürdigen Servern stammen. Sie für Anzeige und als Hinweis nutzen, aber Berechtigungen, Bestätigungen und Rate-Limits im eigenen Code durchsetzen.

Wenn ein Agent sich danebenbenimmt, will man zuerst den System-Prompt umschreiben. Oft liegt das Problem eine Ebene tiefer, in den Tools: ein Name, der zweierlei bedeuten kann, eine Beschreibung, die nie sagt, wann man das Tool nicht nutzen soll, ein Parameter namens user, der alles annimmt, eine Suche, die 40.000 Tokens JSON zurückgibt, oder ein Fehler, der nur „failed“ sagt. Das Modell liest all das in jedem Zug, und es kann nur so gut sein wie das, was es liest.

Dieser Leitfaden sammelt, was Anthropic, OpenAI und die MCP-Spezifikation zum Tool-Design sagen, und macht daraus konkrete Regeln: welche Tools man baut, wie man sie benennt und beschreibt, wie man Schemas so formt, dass Fehler schwer werden, was man zurückgibt, wie man Fehler meldet, damit sich das Modell erholt, und was zu tun ist, wenn die Tool-Liste über ein paar Dutzend wächst. Die Beispiele stammen aus der Art von B2B-Shop- und Backoffice-Agenten, die ich baue.

Tool-Definitionen sind Prompts

Bei der Claude API wird der Parameter tools zu einem System-Prompt: die API baut aus Tool-Definitionen, Tool-Konfiguration und dem eigenen System-Prompt einen speziellen Prompt. Namen, Beschreibungen und Parameterbeschreibungen sind also Anweisungen im wörtlichsten Sinn. Anthropics Dokumentation nennt sehr detaillierte Beschreibungen den „mit Abstand wichtigsten Faktor für die Tool-Leistung“, und der Essay Building effective agents vom Dezember 2024 berichtet, dass das Team für seinen SWE-bench-Agenten mehr Zeit in die Optimierung der Tools gesteckt hat als in den Gesamt-Prompt.

Derselbe Essay benennt die Disziplin: die Agent-Computer-Schnittstelle (ACI) mit derselben Sorgfalt gestalten wie eine Benutzeroberfläche und sich in die Lage des Modells versetzen. OpenAIs Version ist der Praktikantentest: könnte jemand die Funktion korrekt benutzen, wenn er nur sieht, was das Modell sieht? Wenn die Antwort ein Gespräch mit einem selbst erfordert, ist die Definition unvollständig.

Tools um Aufgaben bauen, nicht um Endpunkte

Der häufigste Fehler ist, pro REST-Endpunkt ein Tool zu generieren. Anthropics Artikel zum Tool-Schreiben vom September 2025 sagt unverblümt, dass mehr Tools nicht immer zu besseren Ergebnissen führen, und nennt als Beispiel ein Tool schedule_event, das freie Zeiten findet und den Termin bucht, statt getrennter Tools list_users, list_events und create_event, die der Agent verketten muss. OpenAI macht denselben Punkt von der anderen Seite: Funktionen zusammenlegen, die immer nacheinander aufgerufen werden, und weniger als 20 Funktionen zu Beginn eines Zuges anstreben.

Endpunktorientiert	Aufgabenorientiert	Warum es hilft
`get_customer`, `list_orders`, `get_order_lines`	`get_customer_context(customer_id)`	Ein Aufruf liefert, was ein Agent für eine Support-Frage braucht
`list_products` + client-side filtering	`search_products(query, filters, limit)`	Gefiltert wird im Code, nicht im Kontextfenster
`create_pr`, `review_pr`, `merge_pr`	`pull_request(action, ...)`	Anthropics Vorschlag: verwandte Aktionen hinter einem action-Parameter bündeln
`read_logs` (full dump)	`search_logs(query, since, context_lines)`	Liefert die relevanten Zeilen mit Kontext statt alles

Bündeln hat Grenzen: ein einziges Tool do_anything(json) versteckt jede Entscheidung in einem Argument und macht Berechtigungen unmöglich. Ich trenne entlang der Risiken. Lesezugriffe dürfen breit sein; Schreibzugriffe, Zahlungen und alles Unumkehrbare bekommen ein eigenes Tool mit engem Schema, damit ein Freigabeschritt wie in Human in the Loop für KI-Agenten sie gezielt treffen kann.

Namen und Namensräume

Sobald ein Agent Tools aus mehreren Diensten sieht, kollidieren Namen: search aus dem CRM, search aus dem Wiki, search aus dem Shop. Beide Anthropic-Quellen empfehlen ein Präfix nach Dienst und Ressource, etwa github_list_prs oder slack_send_message, und der Artikel zum Tool-Schreiben ergänzt, dass Präfix- gegenüber Suffix-Schemata die Ergebnisse messbar verändern, also testen. Die technischen Grenzen sind großzügig: die Claude API akzeptiert Namen nach ^[a-zA-Z0-9_-]{1,128}$, und die MCP-Spezifikation sagt, Namen sollen 1 bis 128 Zeichen lang, case-sensitiv und pro Server eindeutig sein und aus Buchstaben, Ziffern, Unterstrich, Bindestrich und Punkt bestehen.

Parameternamen verdienen dieselbe Sorgfalt. Anthropics Beispiel ist klein und überall kopierenswert: statt eines Parameters namens user lieber user_id. Im Shop-Kontext wird daraus sku gegen article_number gegen product_id; den Begriff wählen, den die Nutzer sagen, und das Format in der Parameterbeschreibung erklären.

Beschreibungen, mit denen das Modell arbeiten kann

Anthropics Checkliste für eine Beschreibung lautet: was das Tool tut, wann man es nutzen soll und wann nicht, was jeder Parameter bedeutet und wie er das Verhalten ändert, und wichtige Einschränkungen, etwa was das Tool nicht liefert. Verlangt werden mindestens drei bis vier Sätze pro Tool. Der Artikel zum Tool-Schreiben beschreibt es als Einarbeitung eines neuen Kollegen: implizites Wissen explizit machen, auch Abfrageformate, Fachbegriffe und Beziehungen zwischen Ressourcen.

{
  "name": "shop_search_products",
  "description": "Searches the B2B catalogue by keyword, part number or attribute and returns up to `limit` matching products with name, SKU, price for the current customer and stock status. Use it when the user asks about products, availability or alternatives. Do not use it for order history (use shop_get_orders) or for prices of other customers. Exact part numbers such as 'ART-10001' match only when passed in `sku`, not in `query`. Results are sorted by relevance; if there are more, the response contains `next_cursor`.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Free-text search in German or English, e.g. 'Edelstahl Schraube M8'" },
      "sku": { "type": "string", "description": "Exact SKU, e.g. 'ART-10001'. Overrides query." },
      "in_stock_only": { "type": "boolean", "description": "Only return products available now. Default false." },
      "limit": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Default 10." },
      "response_format": { "type": "string", "enum": ["concise", "detailed"], "description": "concise: name, SKU, price, stock. detailed: adds attributes and documents." }
    },
    "additionalProperties": false
  },
  "input_examples": [ { "query": "Edelstahl Schraube M8", "in_stock_only": true }, { "sku": "ART-10001" } ]
}

Für komplexe Eingaben akzeptiert die Claude API input_examples: ein Array von Beispieleingaben, die gegen das Schema validieren müssen, sonst scheitert die Anfrage mit 400. Sie kosten etwa 20 bis 50 Tokens pro einfachem Beispiel und 100 bis 200 bei verschachtelten Objekten. OpenAI ergänzt eine beachtenswerte Warnung: Beispiele helfen normalen Modellen, können bei Reasoning-Modellen aber die Leistung verschlechtern, also messen, bevor man sie behält.

Schemas, die Fehler schwer machen

Building effective agents leiht sich einen Begriff aus der Fertigung: Poka-Yoke für Tools, also Argumente so ändern, dass Fehler schwerer werden. Das Beispiel ist konkret. Der SWE-bench-Agent lag nach einem Verzeichniswechsel bei relativen Dateipfaden immer wieder falsch, also änderte das Team das Tool so, dass es absolute Pfade verlangt, und das Modell nutzte sie danach fehlerfrei. Dieselbe Idee in anderen Formen:

Enums statt Freitext. OpenAIs Gegenbeispiel ist toggle_light(on: bool, off: bool), das ungültige Zustände zulässt; ein einzelnes Enum state nicht.
Nicht nach dem fragen, was der Code weiß. Kennt die Sitzung Kunde und Bestellung schon, im Code einsetzen. OpenAI: das Modell keine Argumente füllen lassen, die man schon kennt.
Strict Mode einschalten. OpenAI empfiehlt, ihn immer zu aktivieren; er verlangt additionalProperties: false und jede Property in required, optionale Felder als nullable. Bei der Claude API garantiert strict: true, dass Eingaben dem Schema entsprechen.
Nach einer Begründung fragen, nicht nach Reasoning. Anthropic warnt, dass ein Parameter, der das schrittweise Denken des Modells verlangt, eine Ablehnung auslösen kann; stattdessen nach kurzer Erklärung oder Belegen fragen.

Strikte Schemas garantieren die Form, nicht die Wahrheit. Ein gültiges SKU-Format kann trotzdem ein Produkt bezeichnen, das es nicht gibt, deshalb muss der Server validieren und einen nützlichen Fehler liefern. Garantien und Lücken der Schema-Durchsetzung beschreibt strukturierte Ausgaben mit JSON Schema.

Antworten: viel Signal, wenige Tokens

Was ein Tool zurückgibt, landet im Kontextfenster und bleibt dort für den Rest des Laufs. Anthropic rät, nur Informationen mit hohem Signalgehalt zurückzugeben, und stellte fest, dass das Auflösen beliebiger alphanumerischer UUIDs in sprechende Namen die Präzision bei Retrieval-Aufgaben verbesserte. Außerdem wird ein Enum response_format vorgeschlagen, damit der Agent wählen kann: im Slack-Beispiel brauchte die ausführliche Antwort 206 Tokens, die knappe 72, etwa ein Drittel. Für alles, was groß werden kann, Paginierung, Bereichsauswahl, Filter oder Kürzung mit vernünftigen Standardwerten einbauen; Claude Code begrenzt Tool-Antworten zum Vergleich standardmäßig auf 25.000 Tokens.

Jedes Feld ist eine Stelle, an der der Tool-Designer, nicht das Modell, entscheidet, wie wahrscheinlich der nächste Schritt gelingt.

Große Ergebnisse sind auch der Haupttreiber von Context Rot bei lang laufenden Agenten. Ein Tool, das einen Cursor und die ersten zehn Treffer liefert, ist jetzt billiger und hält den Agenten fünfzig Züge später schärfer.

Fehlermeldungen sind Anweisungen

Ein Tool-Fehler ist der nächste Prompt, den das Modell liest, also so schreiben. Die Claude API transportiert Ausführungsfehler als normales tool_result mit is_error: true, und Anthropics Tipp ist konkret: statt eines generischen „failed“ sagen, was schiefging und was als Nächstes zu versuchen ist, zum Beispiel „Rate limit exceeded. Retry after 60 seconds.“ Bei ungültigen Aufrufen wie einem fehlenden Parameter versucht Claude es zwei- bis dreimal mit Korrekturen, bevor es sich beim Nutzer entschuldigt, eine präzise Meldung rettet also meist den Lauf.

// Bad: the model learns nothing
{ "type": "tool_result", "tool_use_id": "toolu_01", "is_error": true, "content": "Error 422" }

// Good: what failed, why, and the next valid move
{ "type": "tool_result", "tool_use_id": "toolu_01", "is_error": true,
  "content": "No product with sku 'ART-1001'. SKUs have 5 digits after 'ART-'. Closest matches: ART-10010 (Edelstahl Schraube M8), ART-10011 (M10). Call shop_search_products with sku set to one of these, or with query if the user gave a description." }

MCP zieht dieselbe Linie formal. Die Spezifikation trennt Protokollfehler, also normale JSON-RPC-Fehler für unbekannte Tools, fehlerhafte Anfragen und Serverausfälle, von Tool-Ausführungsfehlern, die im Ergebnis mit isError: true gemeldet werden: API-Ausfälle, Validierungsfehler wie ein Datum im falschen Format und Fehler der Geschäftslogik. Clients sollen Ausführungsfehler ans Modell weitergeben, damit es sich selbst korrigieren kann; Protokollfehler führen seltener zur Erholung.

Wenn die Tool-Liste wächst

Wer ein paar MCP-Server anbindet, hat schnell hundert Tools. Anthropic beziffert die Kosten: ein typisches Setup mit GitHub, Slack, Sentry, Grafana und Splunk kann vor jeder Arbeit etwa 55.000 Tokens an Definitionen verbrauchen, und Claudes Fähigkeit, das richtige Tool zu wählen, lässt ab 30 bis 50 verfügbaren Tools nach. Das Tool-Search-Tool adressiert beides. Man schickt alle Definitionen, markiert die meisten mit defer_loading: true, und Claude durchsucht Namen, Beschreibungen und Argumentnamen per Regex oder BM25 und lädt nur die Treffer, meist drei bis fünf, was laut Anthropic die Definitions-Tokens um über 85 Prozent senkt.

Wann umsteigen: Anthropic empfiehlt Tool Search ab 10 Tools, Definitionen über 10.000 Tokens oder mehreren MCP-Servern; unter 10 Tools, die alle immer genutzt werden, normal laden.
Häufige geladen lassen: die drei bis fünf meistgenutzten Tools nicht zurückstellen.
Für die Suche schreiben: einheitliche Präfixe lassen eine Abfrage einen ganzen Dienst treffen; in Beschreibungen die Wörter der Nutzer verwenden.
Cache bleibt intakt: zurückgestellte Tools sind nicht im Prompt-Präfix, das Entdecken eines Tools invalidiert den Prompt-Cache also nicht.

Die grundsätzliche Wahl zwischen MCP-Servern, CLIs und Skills für Coding-Agenten behandelt AGENTS.md, Skills, MCP oder CLI.

Tools sind eine Angriffsfläche

Tool-Ergebnisse enthalten oft Inhalte, die man nicht kontrolliert: Webseiten, eingehende E-Mails, Uploads, Drittanbieter-APIs. Anthropics Dokumentation verlangt, diese Inhalte als nicht vertrauenswürdig zu behandeln, weil sie an das Modell gerichtete Anweisungen enthalten können, und sie in tool_result-Blöcken zu halten statt im System-Prompt oder in normalem Nutzertext. Die MCP-Spezifikation ergänzt, dass Clients Tool-Annotationen als nicht vertrauenswürdig behandeln müssen, sofern sie nicht von vertrauenswürdigen Servern stammen, dass Server alle Eingaben validieren, Zugriffe kontrollieren, Aufrufe begrenzen und Ausgaben bereinigen müssen und dass ein Mensch Tool-Aufrufe ablehnen können soll.

Praktisch heißt das: Berechtigungen in die Tool-Implementierung, nicht in die Beschreibung; Bestätigung für Schreibzugriffe verlangen; und nie private Daten, nicht vertrauenswürdige Inhalte und einen ausgehenden Kanal ohne Plan in einem Agenten kombinieren. Die Muster stehen in die tödliche Dreifaltigkeit und sechs Entwurfsmuster, die serverseitigen Prüfungen in der MCP-Sicherheits-Checkliste.

Tools evaluieren, dann iterieren

Anthropics Vorgehen ist der nützlichste Teil des Artikels zum Tool-Schreiben: einen schnellen Prototyp bauen, realistische Evaluationsaufgaben schreiben, die viele Tool-Aufrufe brauchen können, sie laufen lassen und die Transkripte lesen. Neben dem Aufgabenerfolg die Gesamtzahl der Tool-Aufrufe, Tokens, Laufzeit und Tool-Fehler verfolgen und einen zurückgehaltenen Testsatz behalten, damit man Beschreibungen nicht an die eigenen Tests überanpasst. Redundante Aufrufe deuten auf fehlende Paginierung oder Filter; wiederholt ungültige Argumente auf eine unklare Beschreibung oder ein Schema, das den Fehler zulässt.

Wie man die Läufe selbst bewertet, Trajektorien wie Ergebnisse, behandelt KI-Agenten evaluieren. Wie die Schleife um diese Tools funktioniert, erklärt die Agentenschleife, erklärt.

Tools für KI-Agenten gestalten: Namen, Beschreibungen, Schemas und Fehlermeldungen

Das Wichtigste in Kürze