MessagesTools
Fehlerbehebung bei der Tool-Nutzung
Behebe die häufigsten Fehler bei der Tool-Nutzung mit Diagnosetabellen vom Symptom zur Lösung.
Tabellen vom Symptom zur Lösung für die häufigsten Fehler bei der „tool use“ (Tool-Nutzung). Jede Lösung verweist auf die Seite, die für das jeweilige Feature zuständig ist.
Claude ruft das falsche Tool auf
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Claude ruft Tool A auf, obwohl du Tool B wolltest | Mehrdeutige Beschreibung | Schärfe die Beschreibungen. Unterscheide Tools danach, WANN sie verwendet werden sollen, nicht nur danach, WAS sie tun. Siehe Tools definieren. |
| Claude ruft dein Tool nie auf | Namenskollision bei Tools oder zu generisches Schema | Prüfe deine Tool-Liste auf doppelte Namen. Füge input_examples hinzu, um die beabsichtigte Verwendung konkret zu machen. |
| Claude ruft mit falschen Parametertypen auf | Das Modell rät bei einem mehrdeutigen Schema | Füge strict: true hinzu (wenn dein Schema in der unterstützten Teilmenge liegt) oder füge input_examples hinzu. |
Claude erfindet Tool-Parameter
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Parameter, der in deinem Schema nicht existiert | Übergenerierung des Modells ohne Strict-Modus | Füge strict: true hinzu, wenn dein Schema in der unterstützten Teilmenge liegt. |
| Parameterwerte außerhalb deines Enums | Fehlender Strict-Modus oder zu großes Enum | Verkleinere das Enum oder füge input_examples hinzu, die gültige Auswahlmöglichkeiten zeigen. |
Parallele Tool-Aufrufe funktionieren nicht
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Claude ruft Tools nacheinander auf, obwohl parallel besser wäre | Formatierung des Nachrichtenverlaufs | Sende mehrere tool_result-Blöcke in EINER User-Nachricht, nicht einen pro Turn. Siehe Parallele Tool-Nutzung. |
disable_parallel_tool_use scheint ignoriert zu werden | Zu spät in der Konversation gesetzt | Muss in der Anfrage gesetzt werden, die tool_use zurückgibt. Das Setzen in einer späteren Anfrage hat keine Auswirkung auf frühere Tool-Aufrufe. |
Cache wird ständig invalidiert
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Jede Anfrage ist ein Cache-Miss | tool_choice, die Thinking-Konfiguration oder output_config.effort variieren zwischen Anfragen | Halte tool_choice stabil oder platziere den cache_control-Breakpoint vor dem Variationspunkt; halte die Thinking-Konfiguration und die Effort-Stufe über die gesamte Lebensdauer einer gecachten Konversation konstant. Siehe Tool-Nutzung mit Prompt-Caching und Thinking und Prompt-Caching. |
| Das Hinzufügen eines Tools mitten in der Konversation bricht den Cache | Tool wurde dem Tools-Array vorangestellt | Verwende defer_loading: true mit der Tool-Suche, um das Tool inline anzuhängen, anstatt den Anfang des Arrays zu verändern. |
Fehler zum Zeitpunkt der Anfrage
| Fehler | Ursache | Lösung |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | Fehlendes tool_result für einige tool_use-IDs, oder tool_result ist nicht der erste Content-Block in der User-Nachricht | Gib für jeden tool_use-Block in der Assistant-Antwort ein tool_result zurück. Platziere tool_result-Blöcke vor jeglichem Text. Siehe Tool-Aufrufe verarbeiten und Parallele Tool-Nutzung. |
was found without a corresponding <name>_tool_result block | Der vorherige Assistant-Turn enthält einen server_tool_use-Block ohne Ergebnisblock (meistens hat Claude ihn zusammen mit einem Client-Tool aufgerufen), und entweder hat deine nächste User-Nachricht diesen Turn beendet (zum Beispiel mit Text nach den tool_result-Blöcken) oder die Fortsetzungsanfrage definiert dieses Server-Tool nicht mehr (die Meldung endet dann mit but no <name> tool was provided) | Sende eine User-Nachricht, die nur die tool_result-Blöcke für die Client-tool_use-IDs enthält, und behalte dasselbe tools-Array bei. Siehe Stop-Reasons und Fallback. |
Unsupported regex feature in pattern field: ... | Ein pattern im input_schema eines Strict-Tools verwendet ein Regex-Feature, das der Strict-Modus nicht kompilieren kann, etwa eine Rückwärtsreferenz, ein Lookaround, eine Wortgrenze oder einen großen {n,m}-Bereich | Vereinfache das Pattern. Verankerte Patterns mit einfachen Quantifizierern, Zeichenklassen und Gruppen werden unterstützt; siehe JSON-Schema-Einschränkungen. |
All tools have defer_loading: true | Keine Tools für das Modell sichtbar | Mindestens ein Tool muss sofort geladen werden. Das Tool-Suche-Tool selbst darf niemals defer_loading: true haben. |
Fehler: Thinking-Blöcke können nicht verändert werden
Wenn eine Anfrage beim Fortsetzen einer Konversation nach einem Tool-Aufruf mit einem 400 invalid_request_error fehlschlägt, dessen Meldung `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified enthält, verändert deine Anwendung die Thinking-Blöcke des Assistants, bevor sie sie zurücksendet. Sende die gesamte Assistant-Nachricht unverändert zurück und hänge dann dein tool_result an.
Siehe Thinking-Blöcke können nicht verändert werden für den vollständigen Fehler und die Schritte zur Behebung.
Claude markiert Tool-Ergebnisse als Prompt-Injection
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Claude weigert sich, auf ein Tool-Ergebnis hin zu handeln, oder bittet den Nutzer, Anweisungen zu bestätigen, die daraus stammen | Deine eigenen Anweisungen werden innerhalb des tool_result-Inhalts übermittelt | Claude ist darauf trainiert, Anweisungen innerhalb von Tool-Ergebnissen als potenziell nicht vertrauenswürdige Inhalte Dritter zu behandeln. Verschiebe deine Anweisungen aus dem Tool-Ergebnis heraus: Sende sie in einem user-Turn nach dem tool_result-Block oder, bei unterstützten Modellen, in einer System-Nachricht mitten in der Konversation. Beschränke das Tool-Ergebnis auf die reinen Daten. Siehe Jailbreaks und Prompt-Injections abschwächen. |
Unterschiede beim JSON-Escaping (Opus 4.6+)
| Symptom | Ursache | Lösung |
|---|---|---|
| String-Vergleich bei Tool-Eingaben schlägt mit neueren Modellen fehl | Das Escaping von Unicode und Schrägstrichen unterscheidet sich zwischen Modellversionen | Parse mit json.loads() oder JSON.parse(). Führe niemals rohe String-Vergleiche auf serialisierten Eingaben durch. |
Nächste Schritte
Schreibe Schemas und Beschreibungen, die Claude zum richtigen Tool lenken.
Führe Tools aus und gib Ergebnisse im erforderlichen Nachrichtenformat zurück.
Vollständiges Verzeichnis der von Anthropic bereitgestellten Tools und ihrer Versions-Strings.
Was this page helpful?