Claude Platform Docs
MessagesOutils

Dépannage de l’utilisation d’outils

Corrigez les erreurs d’utilisation d’outils les plus courantes grâce à des tableaux de diagnostic symptôme-correctif.

Trouvez le symptôme ou l’erreur que vous constatez, puis appliquez le correctif indiqué.

Claude appelle le mauvais outil

SymptômeCause probableCorrectif
Claude appelle l’outil A alors que vous vouliez l’outil BAmbiguïté de la descriptionAffinez les descriptions. Différenciez les outils selon QUAND les utiliser, et pas seulement selon CE qu’ils font. Consultez Définir des outils.
Claude n’appelle jamais votre outilCollision de noms d’outils ou schéma trop génériqueVérifiez l’absence de noms en double dans votre liste d’outils. Ajoutez input_examples pour rendre l’usage prévu concret.
Claude effectue des appels avec des types de paramètres incorrectsSchéma ambiguAjoutez strict: true (si votre schéma fait partie du sous-ensemble pris en charge) ou ajoutez input_examples.

Claude invente des paramètres d’outil

SymptômeCause probableCorrectif
Paramètre qui n’existe pas dans votre schémaSurgénération du modèle sans mode strictAjoutez strict: true si votre schéma fait partie du sous-ensemble pris en charge.
Valeurs de paramètres en dehors de votre enumMode strict absent ou enum trop grandRéduisez l’enum ou ajoutez input_examples montrant les choix valides.

Les appels d’outils parallèles ne fonctionnent pas

SymptômeCause probableCorrectif
Claude appelle les outils séquentiellement alors que le parallélisme serait préférableFormatage de l’historique des messagesEnvoyez plusieurs blocs tool_result dans UN SEUL message utilisateur, et non un par tour. Consultez Utilisation d’outils en parallèle.
disable_parallel_tool_use semble ignoréDéfini trop tard dans la conversationDéfinissez-le sur la requête qui renvoie tool_use. Le définir sur une requête ultérieure n’a aucun effet sur les appels d’outils précédents.

Le cache ne cesse de s’invalider

SymptômeCause probableCorrectif
Chaque requête est un échec de cachetool_choice, la configuration de réflexion ou output_config.effort varient d’une requête à l’autreGardez tool_choice stable ou placez le point d’arrêt cache_control avant le point de variation ; maintenez la configuration de réflexion et le niveau d’effort constants pendant toute la durée d’une conversation mise en cache. Consultez Utilisation d’outils avec la mise en cache des prompts et Réflexion et mise en cache des prompts.
L’ajout d’un outil en cours de conversation casse le cacheOutil ajouté en tête du tableau des outilsDéclarez l’outil avec defer_loading: true dès la première requête et laissez la recherche d’outils le charger en ligne, au lieu de l’ajouter au tableau plus tard.

Erreurs au moment de la requête

La colonne Erreur affiche une partie de chaque message, et ... représente un texte qui varie.

ErreurCauseCorrectif
tool_use ids were found without tool_result blocks immediately aftertool_result manquant pour certains identifiants tool_use, ou tool_result n’est pas le premier bloc de contenu du message utilisateurRenvoyez un tool_result pour chaque bloc tool_use de la réponse de l’assistant. Placez les blocs tool_result avant tout texte. Consultez Gérer les appels d’outils et Utilisation d’outils en parallèle.
was found without a corresponding ... blockLa requête de suivi empêche un outil serveur en attente de s’exécuterConsultez Un appel d’outil serveur n’a pas de bloc de résultat.
Unsupported regex feature in pattern field: ...Le pattern d’un outil strict utilise une fonctionnalité d’expression régulière que le mode strict ne peut pas compiler, comme une référence arrière, une limite de mot ou une grande plage {n,m}Simplifiez le motif. Consultez Limitations de JSON Schema.
Invalid regex in pattern field: ...Le pattern d’un outil strict contient une assertion avant (lookahead), une assertion arrière (lookbehind) ou une erreur de syntaxeSupprimez toute assertion avant ou arrière et corrigez les éventuelles erreurs de syntaxe. Consultez Limitations de JSON Schema.
All tools have defer_loading: trueAucun outil visible pour le modèleAu moins un outil doit être chargé immédiatement. L’outil de recherche d’outils lui-même ne doit jamais avoir defer_loading: true.

Un appel d’outil serveur n’a pas de bloc de résultat

Un outil serveur attend toujours de s’exécuter lorsque son bloc server_tool_use ou mcp_tool_use n’a pas de bloc de résultat. L’erreur was found without a corresponding ... block signifie que la requête de suivi empêche l’outil en attente de s’exécuter. Le message d’erreur et le stop_reason précédent en indiquent la raison. Appliquez le premier cas correspondant :

  • Le message se termine par but no `<name>` tool was provided ou is not available after the last message : Ici, <name> est le nom de l’outil, par exemple web_search. La requête ne définit plus l’outil. Envoyez le même tableau tools qu’auparavant, ainsi que les mêmes mcp_servers pour un outil MCP.
  • Le stop_reason précédent était tool_use : Votre message utilisateur contenait du contenu après les blocs tool_result. Envoyez uniquement les blocs tool_result, un pour chaque bloc tool_use client.
  • Le stop_reason précédent était pause_turn : Vous avez ajouté un message utilisateur. Supprimez-le afin que la requête se termine par la réponse mise en pause sous forme de message assistant.

Pour les étapes complètes, consultez Lorsqu’un outil serveur est encore en attente et la raison d’arrêt pause_turn.

Erreur : les blocs de réflexion ne peuvent pas être modifiés

Si une requête échoue avec une erreur 400 invalid_request_error dont le message contient `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified lors de la poursuite d’une conversation après un appel d’outil, votre application modifie les blocs de réflexion de l’assistant avant de les renvoyer. Renvoyez l’intégralité du message de l’assistant sans modification, puis ajoutez votre tool_result.

Consultez Les blocs de réflexion ne peuvent pas être modifiés pour l’erreur complète et les étapes de correction.

Claude signale les résultats d’outils comme une injection de prompt

SymptômeCause probableCorrectif
Claude refuse d’agir sur un résultat d’outil, ou demande à l’utilisateur de confirmer des instructions qui en proviennentVos propres instructions sont transmises à l’intérieur du contenu tool_resultClaude est entraîné à traiter les instructions contenues dans les résultats d’outils comme du contenu tiers potentiellement non fiable. Sortez vos instructions du résultat d’outil : envoyez-les dans un tour user après le bloc tool_result, ou, sur les modèles pris en charge, dans un message système en cours de conversation. Limitez le résultat d’outil aux seules données. Consultez Atténuer les jailbreaks et les injections de prompt.

Différences d’échappement JSON entre les versions de modèles

SymptômeCauseCorrectif
La comparaison de chaînes sur les entrées d’outils échoue avec les modèles plus récentsL’échappement Unicode et des barres obliques diffère selon les versions de modèleAnalysez avec json.loads() ou JSON.parse(). N’effectuez jamais de correspondance de chaînes brutes sur une entrée sérialisée.

Étapes suivantes

Rédigez des schémas et des descriptions qui orientent Claude vers le bon outil.

Exécutez des outils et renvoyez les résultats dans le format de message requis.

Répertoire complet des outils fournis par Anthropic et de leurs chaînes de version.

Cette page vous a-t-elle été utile ?