Claude Platform Docs
MessagesTools

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

SymptomWahrscheinliche UrsacheLösung
Claude ruft Tool A auf, obwohl du Tool B wolltestMehrdeutige BeschreibungSchä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 aufKollision von Tool-Namen oder zu generisches SchemaPrüfe deine Tool-Liste auf doppelte Namen. Füge input_examples hinzu, um die beabsichtigte Verwendung zu konkretisieren.
Claude ruft mit falschen Parametertypen aufMehrdeutiges SchemaFüge strict: true hinzu (wenn dein Schema in der unterstützten Teilmenge liegt) oder füge input_examples hinzu.

Claude erfindet Tool-Parameter

SymptomWahrscheinliche UrsacheLösung
Parameter, der in deinem Schema nicht existiertÜbergenerierung des Modells ohne Strict-ModusFüge strict: true hinzu, wenn dein Schema in der unterstützten Teilmenge liegt.
Parameterwerte außerhalb deines EnumsFehlender Strict-Modus oder zu großes EnumVerkleinere das Enum oder füge input_examples hinzu, die gültige Auswahlmöglichkeiten zeigen.

Parallele Tool-Aufrufe funktionieren nicht

SymptomWahrscheinliche UrsacheLösung
Claude ruft Tools nacheinander auf, obwohl parallel besser wäreFormatierung des NachrichtenverlaufsSende mehrere tool_result-Blöcke in EINER User-Nachricht, nicht einen pro Turn. Siehe Parallele Tool-Nutzung.
disable_parallel_tool_use scheint ignoriert zu werdenZu spät in der Konversation gesetztSetze 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

SymptomWahrscheinliche UrsacheLösung
Jede Anfrage ist ein Cache-Misstool_choice, die Thinking-Konfiguration oder output_config.effort variieren zwischen AnfragenHalte 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 CacheTool wurde dem Tools-Array vorangestelltDeklariere 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.

FehlerUrsacheLösung
tool_use ids were found without tool_result blocks immediately afterFehlendes tool_result für einige tool_use-IDs, oder tool_result ist nicht der erste Inhaltsblock in der BenutzernachrichtGib 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 ... blockDie Folgeanfrage verhindert, dass ein wartendes Server-Tool ausgeführt wirdSiehe 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}-BereichVereinfache 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 SyntaxfehlerEntferne jedes Lookahead oder Lookbehind und behebe alle Syntaxfehler. Siehe Einschränkungen von JSON Schema.
All tools have defer_loading: trueKeine Tools für das Modell sichtbarMindestens 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 provided oder is not available after the last message: Hier ist <name> der Name des Tools, etwa web_search. Die Anfrage definiert das Tool nicht mehr. Sende dasselbe tools-Array wie zuvor und bei einem MCP-Tool dieselben mcp_servers.
  • Der vorherige stop_reason war tool_use: Deine Benutzernachricht enthielt Inhalt nach den tool_result-Blöcken. Sende nur die tool_result-Blöcke, einen für jeden Client-tool_use-Block.
  • Der vorherige stop_reason war pause_turn: Du hast eine Benutzernachricht hinzugefügt. Entferne sie, damit die Anfrage mit der pausierten Antwort als assistant-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

SymptomWahrscheinliche UrsacheLösung
Claude weigert sich, auf ein Tool-Ergebnis hin zu handeln, oder bittet den Nutzer, Anweisungen zu bestätigen, die daraus stammenDeine eigenen Anweisungen werden innerhalb des tool_result-Inhalts übermitteltClaude 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

SymptomUrsacheLösung
String-Vergleich bei Tool-Eingaben schlägt mit neueren Modellen fehlDas Escaping von Unicode und Schrägstrichen unterscheidet sich zwischen ModellversionenParse 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?