Tool-Beschreibungen steuern die Auswahl

Wenn Claude entscheidet, welches Tool aufgerufen werden soll, wählt es nicht anhand des Tool-Namens. Es liest die Beschreibung jedes Tools und überlegt, welches für die Aufgabe geeignet ist.

Das ist der wichtigste Grundsatz beim Tool-Design: Die Beschreibung ist der wichtigste Auswahlmechanismus. Ein Tool namens process_refund mit einer vagen Beschreibung ist schwerer korrekt auszuwählen als ein klar beschriebenes Tool mit einem unhandlichen Namen.

Wenn Sie zuverlässiges Verhalten erreichen möchten, sollten Sie Ihre Mühe in gute Beschreibungen investieren — nicht in ausgefallene Namen.

Namen sind kurz und mehrdeutig. Betrachten Sie zwei Tools: search_orders und lookup_order. Welches findet anhand einer ID eine Bestellung? Welches filtert eine Liste nach Datum? Anhand der Namen allein können Sie das nicht erkennen — und das Modell ebenfalls nicht.

Die Beschreibung vermittelt die eigentliche Bedeutung:

• Wofür das Tool gedacht ist (Zweck).
• Was es zurückgibt.
• Welche Eingaben es mit Beispielen erwartet.
• Seine Grenzfälle und Grenzen der Anwendbarkeit.

Benennen Sie das Tool sinnvoll, verlassen Sie sich aber niemals auf den Namen, um sein Verhalten eindeutig zu bestimmen.

Eine gute Tool-Beschreibung beantwortet alles, was das Modell benötigt, um das Tool korrekt auszuwählen und aufzurufen. Sie sollte Folgendes enthalten:

• Zweck — die eine Aufgabe, die dieses Tool erledigt.
• Rückgabewerte — was zurückkommt und in welcher Form.
• Eingabeformate mit Beispielen — konkrete Beispielargumente.
• Grenzfälle — leere Ergebnisse, nicht gefundene Einträge, Mehrdeutigkeiten.
• Grenzen der Anwendbarkeit — wann das Tool NICHT verwendet werden darf.

Die Klausel zu den Grenzen verhindert, dass zwischen ähnlichen Tools falsch geroutet wird.

Der häufigste Fehler ist eine minimale oder mehrdeutige Beschreibung. Das ist ein typisches Anti-Muster in Prüfungen und meist die falsche Antwort, wenn gefragt wird, warum ein Tool falsch ausgewählt wurde.

Beachten Sie, was bei knappen Beschreibungen geschieht:

• get_data: „Ruft Daten ab.“
• fetch_info: „Ruft Informationen ab.“

Bei der Aufgabe „Finden Sie die letzte Bestellung des Kunden“ kann das Modell diese beiden Tools nicht unterscheiden. Es ruft möglicherweise das falsche auf oder wechselt zwischen ihnen. Überlappende oder mehrdeutige Beschreibungen führen zu Fehlrouting — die Lösung sind präzisere, nicht überlappende Formulierungen, nicht ein umbenanntes Tool.

Wenn zwei Tools plausibel infrage kommen, muss jede Beschreibung ausdrücklich vom jeweils anderen Tool abgrenzen. Dadurch wird die Überschneidung beseitigt, die die Auswahl erschwert.

Beachten Sie, wie jede Beschreibung das jeweils andere Tool nennt und angibt, wann an dieses verwiesen werden soll. Diese gegenseitige Abgrenzung sorgt dafür, dass das Modell das richtige Tool verwendet.

Grenzfälle gehören in die Beschreibung, weil sie die nachfolgenden Überlegungen des Modells beeinflussen, nicht nur den Aufruf selbst.

Zwei Unterscheidungen sind besonders wichtig:

• Ein Zugriffsfehler (das System war nicht erreichbar — ein erneuter Versuch ist möglicherweise sinnvoll) gegenüber einem gültigen leeren Ergebnis (keine Treffer — nicht erneut versuchen, sondern einfach melden).
• Was bei einer mehrdeutigen Eingabe geschieht — etwa bei mehreren passenden Kunden.

Wenn die Beschreibung sagt „gibt bei keiner passenden Bestellung ein leeres Ergebnis zurück“, behandelt das Modell „keine Ergebnisse“ nicht als Fehler, bei dem es einen neuen Versuch starten muss. Wenn dort steht „gibt mehrere Treffer zurück, wenn der Name nicht eindeutig ist“, weiß das Modell, dass es nach weiteren Identifikatoren fragen muss, statt zu raten.

Selbst perfekte Beschreibungen verlieren an Wirkung, wenn es zu viele davon gibt. Die Auswahl ist eine Denksaufgabe, und mehr Optionen verwässern sie.

• 4–5 Tools pro Agent ist der optimale Bereich für eine zuverlässige Auswahl.
• Ab 18 oder mehr Tools nimmt die Zuverlässigkeit der Auswahl merklich ab.

Gute Beschreibungen und ein kleines Toolset ergänzen sich daher: Beschränken Sie die Tools jedes Agents auf seine Rolle und beschreiben Sie diese wenigen Tools anschließend präzise. Ein überladenes Toolset lässt sich nicht allein durch Formulierungen retten.

Die Qualität der Beschreibung und das Prinzip der geringsten Berechtigung weisen in dieselbe Richtung. Ein Research-Subagent sollte kein Refund-Tool mitführen; ein schreibgeschützter Reviewer sollte weder Write noch Bash mitführen.

Die Beschränkung nach Rolle bewirkt zweierlei:

• Sie entfernt überlappende Kandidaten, sodass die verbleibenden Beschreibungen leichter voneinander zu unterscheiden sind.
• Sie hält jeden Agent nahe am optimalen Bereich von 4–5 Tools.

Weniger, für die Rolle relevante Tools bedeuten präzisere, nicht überlappende Beschreibungen — und genau das sorgt für eine korrekte Auswahl.

Beschreibungen entscheiden, welches Tool geeignet ist. Der Parameter tool_choice ist ein davon unabhängiger Hebel, der einschränkt, ob und wie ein Tool aufgerufen wird:

• "auto" — das Modell wählt Text oder ein Tool (die Auswahl wird weiterhin durch die Beschreibungen gesteuert).
• "any" — das Modell muss EIN Tool aufrufen; nützlich, um eine strukturierte Ausgabe zu garantieren.
• {"type":"tool","name":"X"} — erzwingt ein bestimmtes Tool.

Das Erzwingen eines Tools behebt keine schlechte Beschreibung — es entfernt lediglich die Auswahlmöglichkeit. Bei "auto" oder "any" liest das Modell weiterhin die Beschreibungen, um unter den Kandidaten auszuwählen; daher müssen die Formulierungen weiterhin klar sein.

In MCP sollte nicht alles ein Tool sein. Der Server stellt drei Primitive bereit, und die Wahl des richtigen Primitives sorgt dafür, dass Ihre Tool-Beschreibungen fokussiert bleiben:

• Tools — Aktionen, die etwas TUN (eine Rückerstattung veranlassen, eine Abfrage ausführen).
• Resources — schreibgeschützte Daten und Kontext, etwa Schemata oder Kataloge.
• Prompts — wiederverwendbare Vorlagen.

Wenn Sie ein schreibgeschütztes Schema oder einen Katalog als Resource statt als Tool modellieren, wird es vollständig aus dem Pool für die Aktionsauswahl entfernt. Dadurch gibt es einen mehrdeutigen Kandidaten weniger, der mit den anderen Einträgen in Ihren Beschreibungen konkurriert — das verbessert die Tool-Auswahl unmittelbar.

Die Auswahl endet nicht nach dem ersten Aufruf — das Modell muss als Nächstes oft ein Recovery-Tool auswählen. Diese Wahl hängt von dem Fehler ab, den es zurückerhält.

Ein generischer Fehler wie "Operation failed" liefert dem Modell keine Grundlage für die Weiterleitung. Ein strukturierter MCP-Fehler schon:

• isError: true und errorCategory (transient / validation / business / permission).
• isRetryable, eine message, die attempted_query und alle partial_results.

Damit kann das Modell intelligent entscheiden: einen vorübergehenden Fehler erneut versuchen, ein Validierungsproblem beheben oder einen geschäftlichen bzw. Berechtigungsfehler eskalieren — statt stecken zu bleiben.

Die wichtigsten Erkenntnisse zur Tool-Auswahl:

• Claude wählt Tools anhand ihrer Beschreibungen aus, nicht anhand ihrer Namen.
• Eine gute Beschreibung nennt Zweck, Rückgabewerte, Eingabeformate mit Beispielen, Sonderfälle und Grenzen der Anwendbarkeit.
• Überlappende oder mehrdeutige Beschreibungen führen zu Fehlleitungen; ziehen Sie klare Grenzen, die jedes Tool von seinen ähnlichen Tools abgrenzen.
• Dokumentieren Sie Sonderfälle in der Beschreibung — insbesondere leere Ergebnisse gegenüber Zugriffsfehlern und mehrdeutige Treffer.
• Beschränken Sie jeden Agenten auf 4–5 Tools; ab 18 oder mehr nimmt die Auswahlqualität ab. Richten Sie den Umfang der Tools an der Rolle aus.
• tool_choice (auto / any / forced) schränkt das Aufrufen ein, ersetzt aber keine klare Beschreibung.
• Modellieren Sie schreibgeschützte Daten als MCP-Resources und geben Sie strukturierte Fehler zurück, damit das Modell die Fehlerbehebung gezielt weiterleiten kann.