Définir des outils



Prérequis

• Une familiarité avec la vue d'ensemble de l'utilisation d'outils
• Une clé API Claude et une configuration SDK ou cURL fonctionnelle



Choisir un modèle

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

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



Spécifier des outils clients

Les outils clients (à 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 optionnelles 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 d'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 pour que l'outil fonctionne correctement :

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 directives :

• 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, meilleur il sera pour décider quand et comment les utiliser. Visez au moins 3 à 4 phrases pour chaque description d'outil, davantage si l'outil est complexe.
• Priorisez les descriptions, mais envisagez d'utiliser input_examples pour les outils complexes. Des descriptions claires sont le plus important, 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. Consultez 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 et plus performants réduisent l'ambiguïté de sélection et rendent votre surface d'outils plus facile à parcourir pour Claude.
• Utilisez un espace de noms 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 non ambiguë à 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 des 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. Ceci est particulièrement utile pour les outils complexes avec des objets imbriqués, des paramètres optionnels ou des entrées sensibles au format.



Utilisation de base

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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 optionnels, quels formats utiliser et comment structurer des entrées complexes.



Exigences et limitations

• Validation de 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 clients définis par l'utilisateur et ceux avec schéma Anthropic, mais pas sur les outils serveur tels que la recherche web ou l'exécution de code
• Coût en tokens - Les exemples s'ajoutent aux tokens du prompt : ~20 à 50 tokens pour les exemples simples, ~100 à 200 tokens pour les 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 en surbrillance sont la seule différence par rapport à une requête d'utilisation d'outils standard :

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-5",
    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, il existe quatre options possibles :

• auto permet à Claude de décider d'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 avez tool_choice défini 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 on le leur demande explicitement.

Les tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez que le modèle fournisse un 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'appeler 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 avec :

{
  "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 guider 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.



Prochaines étapes