Eingabeformate und Beispiele

Eine Toolbeschreibung ist der zentrale Mechanismus, anhand dessen Claude entscheidet, wann und wie ein Tool aufgerufen wird. Namen allein liefern nicht genügend Informationen. Eine gute Beschreibung behandelt Zweck, Rückgabewerte, Sonderfälle, Anwendbarkeitsgrenzen und insbesondere die Eingabeformate.

Diese Lektion konzentriert sich auf eine besonders wirkungsvolle Technik: konkrete Eingabebeispiele zu zeigen, damit das Modell nie erraten muss, wie ein Parameter aussehen soll.

Stellen Sie sich ein Tool mit einem Parameter namens date vor. Ist das 2026-06-10? 06/10/2026? June 10? Ein Unix-Zeitstempel? Ohne Beispiel muss Claude das Format ableiten, und genau diese Ableitung bei Mehrdeutigkeit führt zu fehlerhaften Tool-Aufrufen.

Ein mehrdeutiges Schema schlägt nicht offensichtlich fehl. Es schlägt unbemerkt fehl, indem es Eingaben erzeugt, die Ihr Backend ablehnt. Konkrete Beispiele beseitigen diese Mehrdeutigkeit an der Quelle.

Sie können Eingabebeispiele an zwei sich ergänzenden Stellen platzieren:

• Im Text der Toolbeschreibung (allgemeine Verwendungsbeispiele).
• In der description jedes Parameters innerhalb des JSON-Schemas (Format des jeweiligen Feldes).

Beide Stellen speisen dieselbe Engine für Auswahl und Formatierung. Platzieren Sie die Formatvorgaben möglichst nah an dem Feld, für das sie gelten, und ergänzen Sie ein ganzheitliches Beispiel für den vollständigen Aufruf.

Vergleichen Sie diese Beispiele. Die schwache Version zwingt zum Raten; die starke zeigt genau, wie eine gültige Eingabe aussieht.

• Schwach: „Kunden suchen.“
• Stark: Zweck + Eingabeformat + Beispiel + Rückgabewerte + Sonderfälle.

Minimale, mehrdeutige Beschreibungen sind ein klassisches Anti-Pattern, das zu falschem Tool-Routing und fehlerhaften Argumenten führt.

Wenn ein Parameter ein Objekt oder Array ist, ist ein einzelnes Beispiel mehr wert als ein ganzer Absatz Prosa. Zeigen Sie dem Modell die konkrete Struktur, die es ausgeben soll.

Das ist besonders wertvoll für verschachtelte Filter, Listenelemente oder jedes Feld, dessen Struktur allein aus dem Typ nicht ersichtlich ist.

Wenn ein Feld eine bekannte, endliche Menge gültiger Werte hat, kodieren Sie diese als enum, statt sie in Prosa zu beschreiben. Das Schema schränkt das Modell dann direkt ein.

Für Erweiterbarkeit fügen Sie einen "other"-Enum-Wert sowie ein Freitextfeld für Details hinzu, damit neue Fälle das Modell nicht dazu zwingen, einen ungültigen Wert zu erfinden.

Few-shot-Beispiele gehören zu den zuverlässigsten Prompting-Tools. Mit 2–4 gezielten Beispielen pro Mehrdeutigkeit verallgemeinert das Modell das Muster, statt es nur zu wiederholen.

Bei Tool-Eingaben eignen sich Beispiele besonders für Konsistenz, Sonderfälle, Ausgabeformate und die Verringerung von Halluzinationen — genau die Fehlerarten, die zu fehlerhaften Tool-Argumenten führen.

Beispiele zeigen dem Modell, wie eine gültige Eingabe aussieht; das Array required gibt an, was enthalten sein muss. Eine wichtige Regel: Markieren Sie ein Feld nur dann als erforderlich, wenn es immer vorhanden ist.

Wenn Sie ein Feld verlangen, das in der Quelle fehlen kann, wird das Modell einen Wert erfinden, um das Schema zu erfüllen. Optional, aber gut durch Beispiele erklärt, ist besser als erforderlich, aber manchmal nicht vorhanden.

Gute Beschreibungen nennen Anwendbarkeitsgrenzen: was das Tool erledigt und was es NICHT verarbeitet. Verankern Sie diese Grenzen in Ihren Beispielen, damit das Modell erkennt, wann eine Eingabe außerhalb des Zuständigkeitsbereichs liegt.

So verhindern Sie, dass sich überschneidende Tools falsch geroutet werden, denn das Beispiel verdeutlicht, welchem Tool welche Eingabestruktur zugeordnet ist.

Selbst bei hervorragenden Beispielen werden manche Eingaben ungültig sein. Der Fehlervertrag des Tools sollte deshalb ebenso eindeutig sein, damit sich das Modell davon erholen kann.

Geben Sie strukturierte Fehler zurück: ein isError-Flag sowie errorCategory (transient / validation / business / permission), isRetryable, eine Nachricht und die attempted_query. Der generische Fehler „Operation failed“ verhindert die Wiederherstellung; strukturierte Fehler ermöglichen intelligentes Routing und einen korrigierten Wiederholungsversuch.

Wenn eine Tool-Eingabe fehlerhaft zurückkommt, verwenden Sie retry-with-feedback: Senden Sie die ursprüngliche Anfrage, die fehlerhafte Ausgabe und den genauen Validierungsfehler zurück an das Modell. Genau dafür sind Format- und Strukturfehler geeignet.

Beachten Sie die Einschränkung: Eine Wiederholung hilft, wenn die Eingabe falsch formatiert war, nicht wenn die benötigte Information in der Quelle einfach fehlt. Beispiele verhindern die erste Fehlerklasse; fehlende Fakten kann nichts erfinden.

Die wichtigsten Erkenntnisse:

• Tool-Beschreibungen steuern Auswahl und Formatierung. Investieren Sie daher in sie und nicht nur in Namen.
• Zeigen Sie konkrete Eingabebeispiele auf Feldebene sowie ein Beispiel für den vollständigen Aufruf in der Beschreibung.
• Verwenden Sie Enums (mit einem Wert 'other' + Detailfeld) für feste Mengen; zeigen Sie die konkrete Struktur von Objekten und Arrays.
• Markieren Sie ein Feld nur dann als erforderlich, wenn es immer vorhanden ist, andernfalls erfindet das Modell einen Wert.
• Ergänzen Sie Beispiele durch strukturierte Fehler (errorCategory, isRetryable, attempted_query), damit retry-with-feedback Formatfehler korrigieren kann, auch wenn dadurch keine fehlenden Fakten ergänzt werden können.

Konkrete Beispiele sind die kostengünstigste und wirkungsvollste Methode, fehlerhafte Tool-Aufrufe zu verhindern, bevor sie entstehen.