Définir des outils



Choisir un modèle

Utilisez le dernier modèle Claude Opus (4.8) pour les outils complexes et les requêtes ambiguës ; il gère mieux plusieurs outils et demande des clarifications lorsque nécessaire.

Utilisez les modèles Claude Haiku pour les outils simples, mais notez qu'ils peuvent inférer les paramètres manquants.



Spécifier des outils client

Les outils client (à la fois ceux avec schéma Anthropic et ceux définis par l'utilisateur) sont spécifiés dans le paramètre de premier niveau tools de la requête API. Chaque définition d'outil comprend :

Pour l'ensemble complet des propriétés facultatives disponibles sur toute définition d'outil, y compris cache_control, strict, defer_loading et allowed_callers, consultez la Référence des outils.



Invite système pour l'utilisation d'outils

Lorsque vous appelez l'API Claude avec le paramètre tools, l'API construit une invite système spéciale à partir des définitions d'outils, de la configuration des outils et de toute invite système spécifiée par l'utilisateur. L'invite construite est conçue pour indiquer au modèle d'utiliser le ou les outils spécifiés et fournir le contexte nécessaire au bon fonctionnement de l'outil :

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}



Bonnes pratiques pour les définitions d'outils

Pour obtenir les meilleures performances de Claude lors de l'utilisation d'outils, suivez ces recommandations :

• Fournissez des descriptions extrêmement détaillées. C'est de loin le facteur le plus important pour la performance des outils. Vos descriptions doivent expliquer chaque détail de l'outil, notamment :
  • Ce que fait l'outil
  • Quand il doit être utilisé (et quand il ne doit pas l'être)
  • Ce que signifie chaque paramètre et comment il affecte le comportement de l'outil
  • Toute mise en garde ou limitation importante, comme les informations que l'outil ne renvoie pas si le nom de l'outil n'est pas clair. Plus vous donnez de contexte à Claude sur vos outils, mieux il saura décider quand et comment les utiliser. Visez au moins 3 à 4 phrases par description d'outil, davantage si l'outil est complexe.
• Privilégiez les descriptions, mais envisagez d'utiliser input_examples pour les outils complexes. Des descriptions claires sont primordiales, mais pour les outils avec des entrées complexes, des objets imbriqués ou des paramètres sensibles au format, vous pouvez utiliser le champ input_examples pour fournir des exemples validés par le schéma. Voir Fournir des exemples d'utilisation d'outils pour plus de détails.
• Consolidez les opérations connexes en moins d'outils. Plutôt que de créer un outil distinct pour chaque action (create_pr, review_pr, merge_pr), regroupez-les en un seul outil avec un paramètre action. Des outils moins nombreux mais plus polyvalents réduisent l'ambiguïté de sélection et rendent votre surface d'outils plus facile à parcourir pour Claude.
• Utilisez un espace de nommage significatif dans les noms d'outils. Lorsque vos outils couvrent plusieurs services ou ressources, préfixez les noms avec le service (par exemple, github_list_prs, slack_send_message). Cela rend la sélection d'outils sans ambiguïté à mesure que votre bibliothèque s'agrandit, et c'est particulièrement important lors de l'utilisation de la recherche d'outils.
• Concevez les réponses d'outils pour ne renvoyer que des informations à forte valeur. Renvoyez des identifiants sémantiques et stables (par exemple, des slugs ou des UUID) plutôt que des références internes opaques, et n'incluez que les champs dont Claude a besoin pour raisonner sur sa prochaine étape. Des réponses surchargées gaspillent du contexte et rendent plus difficile pour Claude d'extraire ce qui compte.

La bonne description explique clairement ce que fait l'outil, quand l'utiliser, quelles données il renvoie et ce que signifie le paramètre ticker. La mauvaise description est trop brève et laisse Claude avec de nombreuses questions ouvertes sur le comportement et l'utilisation de l'outil.



Fournir des exemples d'utilisation d'outils

Vous pouvez fournir des exemples concrets d'entrées d'outils valides pour aider Claude à comprendre comment utiliser vos outils plus efficacement. Cela est particulièrement utile pour les outils complexes avec des objets imbriqués, des paramètres facultatifs ou des entrées sensibles au format.



Utilisation de base

Ajoutez un champ facultatif input_examples à votre définition d'outil avec un tableau d'objets d'entrée exemples. Chaque exemple doit être valide selon le input_schema de l'outil :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Les exemples sont inclus dans le prompt aux côtés de votre schéma d'outil, montrant à Claude des modèles concrets d'appels d'outils bien formés. Cela aide Claude à comprendre quand inclure des paramètres facultatifs, quels formats utiliser et comment structurer des entrées complexes.



Exigences et limitations

• Validation du schéma - Chaque exemple doit être valide selon le input_schema de l'outil. Les exemples invalides renvoient une erreur 400.
• Non pris en charge pour les outils côté serveur - Les exemples d'entrée fonctionnent sur les outils client définis par l'utilisateur et ceux avec schéma Anthropic, mais pas sur les outils serveur comme la recherche web ou l'exécution de code.
• Coût en tokens - Les exemples s'ajoutent aux tokens du prompt : environ 20 à 50 tokens pour des exemples simples, environ 100 à 200 tokens pour des objets imbriqués complexes.



Contrôler la sortie de Claude



Forcer l'utilisation d'outils

Dans certains cas, vous pouvez vouloir que Claude utilise un outil spécifique pour répondre à la question de l'utilisateur, même si Claude répondrait autrement directement sans appeler d'outil. Vous pouvez le faire en spécifiant l'outil dans le champ tool_choice de la requête. Les lignes surlignées constituent la seule différence par rapport à une requête d'utilisation d'outils standard :

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Lorsque vous travaillez avec le paramètre tool_choice, quatre options sont possibles :

• auto permet à Claude de décider s'il doit appeler ou non l'un des outils fournis. C'est la valeur par défaut lorsque des tools sont fournis.
• any indique à Claude qu'il doit utiliser l'un des outils fournis, mais ne force pas un outil particulier.
• tool force Claude à toujours utiliser un outil particulier.
• none empêche Claude d'utiliser des outils. C'est la valeur par défaut lorsqu'aucun tools n'est fourni.

Ce diagramme illustre le fonctionnement de chaque option :

Notez que lorsque vous définissez tool_choice sur any ou tool, l'API préremplit le message de l'assistant pour forcer l'utilisation d'un outil. Cela signifie que les modèles n'émettront pas de réponse ou d'explication en langage naturel avant les blocs de contenu tool_use, même si cela leur est explicitement demandé.

Les tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez que le modèle fournisse du contexte ou des explications en langage naturel tout en demandant au modèle d'utiliser un outil spécifique, vous pouvez utiliser {"type": "auto"} pour tool_choice (la valeur par défaut) et ajouter des instructions explicites dans un message user. Par exemple : What's the weather like in London? Use the get_weather tool in your response.



Réponses du modèle avec des outils

Lors de l'utilisation d'outils, Claude commente souvent ce qu'il fait ou répond naturellement à l'utilisateur avant d'invoquer des outils.

Par exemple, avec le prompt « What's the weather like in San Francisco right now, and what time is it there? », Claude pourrait répondre par :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Ce style de réponse naturel aide les utilisateurs à comprendre ce que fait Claude et crée une interaction plus conversationnelle. Vous pouvez orienter le style et le contenu de ces réponses via vos invites système et en fournissant des <examples> dans vos prompts.

Il est important de noter que Claude peut utiliser diverses formulations et approches pour expliquer ses actions. Votre code doit traiter ces réponses comme tout autre texte généré par l'assistant et ne pas s'appuyer sur des conventions de formatage spécifiques.



Étapes suivantes