Contrôler les appels avec tool_choice

Objectifs

À l’issue de cette leçon, vous serez capable de :

• Utiliser les quatre valeurs de tool_choice
• Savoir quels modèles acceptent l’appel forcé, et quoi faire sur les autres
• Obtenir un appel d’outil fiable sur les modèles récents

Le paramètre tool_choice

Par défaut, Claude arbitre seul : il examine la demande, la confronte aux outils déclarés et décide s’il en appelle un. Cette autonomie convient à la majorité des applications conversationnelles. Le paramètre tool_choice permet de modifier cet arbitrage. Il accepte quatre valeurs :

L’appel forcé n’est plus accepté partout

any et tool forcent un appel. Ils ne fonctionnent pas sur tous les modèles ni avec tous les réglages :

Deux effets de bord, là où l’appel forcé est accepté. L’API pré-remplit le message de l’assistant pour imposer l’outil : Claude n’écrit aucun texte avant le bloc tool_use, même si vous le lui demandez. Et l’appel forcé saute la réflexion : la réponse commence directement par l’appel d’outil, sans bloc thinking.

Obtenir un appel sur les modèles récents

Sur Claude Sonnet 5.5 et les autres modèles qui refusent l’appel forcé, trois gestes remplacent tool_choice :

1. Demander l’outil explicitement dans le message de l’utilisateur, avec tool_choice laissé sur auto.
2. Activer strict tool use ("strict": true dans la définition de l’outil, leçon 8) pour que l’entrée respecte toujours le schéma.
3. Vérifier qu’un appel a bien eu lieu, et relancer sinon.

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,   # la réflexion compte dans ce plafond
    tools=tools,  # tool_choice reste sur "auto", la valeur par défaut
    messages=[{
        "role": "user",
        "content": "Combien font 245 * 873 ? Utilise l'outil calculator dans ta réponse."
    }]
)

appels = [b for b in response.content if b.type == "tool_use"]
if not appels:
    # Aucun appel : relancer avec une consigne plus explicite, ou signaler l'anomalie
    ...

Avec auto, Claude peut aussi réfléchir et expliquer sa démarche avant d’appeler l’outil, ce que l’appel forcé empêche. Et si l’appel forcé ne servait qu’à obtenir du JSON, les sorties structurées font mieux : c’est l’objet de la leçon suivante.

none : garder les outils, interdire l’appel

{"type": "none"} empêche tout appel d’outil, sur tous les modèles, sans retirer les outils de la requête. Il sert par exemple pour un dernier tour où vous voulez une réponse en texte seul, comme une synthèse. Attention avec la mise en cache des prompts (leçon 14) : changer tool_choice invalide le cache des messages ; les définitions d’outils et le prompt système restent en cache.

Sur les modèles qui l’acceptent : tool et any

Vous rencontrerez l’appel forcé dans du code existant. Nommer un outil ne laisse à Claude que le choix des paramètres :

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1000,
    tools=tools,
    tool_choice={"type": "tool", "name": "calculator"},
    messages=[{"role": "user", "content": "Combien font 245 * 873 ?"}]
)
# Claude DOIT utiliser la calculatrice

{"type": "any"} rend l’appel obligatoire mais laisse Claude choisir l’outil : on l’emploie dans un routeur qui doit toujours orienter la demande vers l’un de ses services. Sur ces modèles, la documentation recommande de l’associer à strict: true : un outil est appelé, avec une entrée conforme au schéma.

Plusieurs appels dans une même réponse

Une seule réponse peut contenir plusieurs blocs tool_use, chacun avec son identifiant : la météo et les actualités du jour, par exemple. Renvoyez un tool_result pour chaque tool_use, tous dans le message utilisateur suivant, appariés par tool_use_id, et placés avant tout texte. La leçon 9 montre comment exécuter ces appels en parallèle, et comment les limiter avec disable_parallel_tool_use.

Bien décrire plutôt que forcer

Quand Claude choisit mal, la première chose à retravailler est la définition de l’outil, pas tool_choice : une description précise, qui dit ce que fait l’outil et dans quelles circonstances l’utiliser, vaut mieux que dix lignes de prompt système. Les noms suivent la même logique : search_customer_orders renseigne le modèle, tool3 ne lui apprend rien. La leçon 7 détaille la méthode.

Un cas limite : any sans outil pertinent

Sur un modèle qui accepte l’appel forcé, que se passe-t-il si vous fixez tool_choice à {"type": "any"} alors qu’aucun outil disponible ne correspond à la question posée ?

Voir la réponse

Claude est forcé d’utiliser un outil, même si aucun n’est pertinent. Il choisit l’outil le plus « proche » de la question et l’appelle avec des paramètres qui peuvent ne pas avoir de sens. C’est pourquoi any doit être utilisé avec précaution.

À vous de jouer

Forcer, ou demander. Définissez deux outils, une calculatrice et une météo simulée. Avec Claude Sonnet 5.5, envoyez tool_choice={"type": "any"} et lisez l’erreur 400. Laissez ensuite auto, demandez l’outil dans le message, et vérifiez sur cinq questions qu’un appel a bien lieu. Refaites enfin l’appel forcé sur Claude Haiku 5.5, qui l’accepte : la réponse commence-t-elle bien par le bloc tool_use, sans réflexion ?

Sources officielles : Define tools — Forcing tool use (documentation Claude : valeurs de tool_choice, modèles qui refusent l’appel forcé) · Parallel tool use · Structured outputs · Prompt caching (documentation Claude : ce qui invalide le cache)

Points clés à retenir

• Quatre valeurs : auto (défaut avec outils), any, tool, none
• any et tool renvoient une erreur 400 sur Claude Opus 5.5, Sonnet 5.5, Fable 5.1 et Mythos 5.1, et avec la réflexion manuelle
• Sur ces modèles : auto, une consigne explicite, strict: true, et une vérification qu’un appel a eu lieu
• none interdit l’appel sans retirer les outils
• Un tool_result pour chaque tool_use, tous dans le message suivant

Crédits et licence — Leçon réécrite par Corsen à partir du notebook « 05_tool_choice » du tutoriel Tool use d’Anthropic (dépôt GitHub anthropics/courses, publié sous licence CC BY-NC 4.0), et mise à jour d’après la documentation officielle citée ci-dessus.