Fehlerbehebung bei der Tool-Nutzung
Behebe die häufigsten Fehler bei der Tool-Nutzung mit Diagnosetabellen vom Symptom zur Lösung.
Finde das Symptom oder den Fehler, den du siehst, und wende dann die dafür aufgeführte Lösung an.
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 | Kollision von Tool-Namen oder zu generisches Schema | Prüfe deine Tool-Liste auf doppelte Namen. Füge input_examples hinzu, um die beabsichtigte Verwendung zu konkretisieren. |
| Claude ruft mit falschen Parametertypen auf | Mehrdeutiges 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 | Setze es in der Anfrage, 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 Nachdenken und Prompt-Caching. |
| Das Hinzufügen eines Tools mitten in der Konversation bricht den Cache | Tool wurde dem Tools-Array vorangestellt | Deklariere das Tool ab der ersten Anfrage mit defer_loading: true und lass die Tool-Suche es inline laden, anstatt es später dem Array hinzuzufügen. |
Fehler zum Zeitpunkt der Anfrage
Die Spalte „Fehler“ zeigt einen Teil jeder Meldung, und ... steht für Text, der variiert.
| 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 Inhaltsblock in der Benutzernachricht | Gib für jeden tool_use-Block in der Assistentenantwort 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 ... block | Die Folgeanfrage verhindert, dass ein wartendes Server-Tool ausgeführt wird | Siehe Ein Server-Tool-Aufruf hat keinen Ergebnisblock. |
Unsupported regex feature in pattern field: ... | Ein pattern eines Strict-Tools verwendet ein Regex-Feature, das der Strict-Modus nicht kompilieren kann, etwa eine Rückwärtsreferenz, eine Wortgrenze oder einen großen {n,m}-Bereich | Vereinfache das Muster. Siehe Einschränkungen von JSON Schema. |
Invalid regex in pattern field: ... | Ein pattern eines Strict-Tools enthält ein Lookahead, ein Lookbehind oder einen Syntaxfehler | Entferne jedes Lookahead oder Lookbehind und behebe alle Syntaxfehler. Siehe Einschränkungen von JSON Schema. |
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. |
Ein Server-Tool-Aufruf hat keinen Ergebnisblock
Ein Server-Tool wartet noch auf seine Ausführung, wenn sein server_tool_use- oder mcp_tool_use-Block keinen Ergebnisblock hat. Der Fehler was found without a corresponding ... block bedeutet, dass die Folgeanfrage die Ausführung des wartenden Tools verhindert. Die Fehlermeldung und der vorherige stop_reason zeigen, warum. Verwende den ersten Fall, der zutrifft:
- Die Meldung endet mit
but no `<name>` tool was providedoderis not available after the last message: Hier ist<name>der Name des Tools, etwaweb_search. Die Anfrage definiert das Tool nicht mehr. Sende dasselbetools-Array wie zuvor und bei einem MCP-Tool dieselbenmcp_servers. - Der vorherige
stop_reasonwartool_use: Deine Benutzernachricht enthielt Inhalt nach dentool_result-Blöcken. Sende nur dietool_result-Blöcke, einen für jeden Client-tool_use-Block. - Der vorherige
stop_reasonwarpause_turn: Du hast eine Benutzernachricht hinzugefügt. Entferne sie, damit die Anfrage mit der pausierten Antwort alsassistant-Nachricht endet.
Die vollständigen Schritte findest du unter Wenn ein Server-Tool noch wartet und beim Stop-Grund pause_turn.
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 zwischen Modellversionen
| 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.
War diese Seite hilfreich?