---
title: Définir des outils
url: https://platform.claude.com/docs/fr/agents-and-tools/tool-use/define-tools
description: Spécifiez les schémas d'outils, rédigez des descriptions efficaces et contrôlez quand Claude appelle vos outils.
---

## Prérequis

* Une familiarité avec la [présentation de l'utilisation d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/overview)
* Une clé API Claude et une configuration SDK ou cURL fonctionnelle

<Tip>
  Si vous utilisez Claude avec l'utilisation d'outils et la réflexion, consultez [Réflexion](https://platform.claude.com/docs/fr/build-with-claude/thinking) pour plus d'informations.
</Tip>

## Spécifier des outils client

Les « client tools » (outils client) sont spécifiés dans le paramètre de premier niveau `tools` de la requête API. Les outils client à schéma Anthropic, tels que les outils bash et éditeur de texte, sont déclarés par un `type` versionné par date ; consultez la page de chaque outil, accessible depuis la [Référence des outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference), pour connaître les champs qu'il accepte. Les outils d'utilisation de l'ordinateur et d'utilisation du navigateur sont des [ensembles d'outils client](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets) : une entrée unique sans `name` qui déclare un ensemble fixe d'outils membres. Une définition d'outil définie par l'utilisateur comprend :

| Paramètre        | Description                                                                                                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | Le nom de l'outil. Doit correspondre à l'expression régulière `^[a-zA-Z0-9_-]{1,128}$`.                                                                                                                                                                                       |
| `description`    | Une description détaillée en texte brut de ce que fait l'outil, du moment où il doit être utilisé et de son comportement.                                                                                                                                                     |
| `input_schema`   | Un objet [JSON Schema](https://json-schema.org/) définissant les paramètres attendus pour l'outil.                                                                                                                                                                            |
| `input_examples` | (Facultatif) Un tableau d'objets d'entrée d'exemple pour aider Claude à comprendre comment utiliser l'outil. Consultez [Fournir des exemples d'utilisation d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/define-tools#providing-tool-use-examples). |

Pour l'ensemble complet des propriétés facultatives disponibles sur toute définition d'outil individuelle, y compris `cache_control`, `strict`, `defer_loading` et `allowed_callers`, consultez la [Référence des outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#tool-definition-properties). Une entrée d'ensemble d'outils client accepte `cache_control` et `allowed_callers` sur l'entrée et définit `defer_loading` par membre ; consultez [Ensembles d'outils client](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets).

<Accordion title="Exemple de définition d'outil simple">
  ```json JSON
  {
    "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, either 'celsius' or 'fahrenheit'"
        }
      },
      "required": ["location"]
    }
  }
  ```

  Cet outil, nommé `get_weather`, attend un objet d'entrée avec une chaîne `location` obligatoire et une chaîne `unit` facultative qui doit être soit "celsius", soit "fahrenheit".
</Accordion>

### Invite système pour l'utilisation d'outils

Lorsque vous appelez l'API Claude avec le paramètre `tools`, l'API construit une « system prompt » (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. Le prompt construit est conçu 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 :

```text wrap
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 les performances 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, par exemple les informations que l'outil ne renvoie pas si le nom de l'outil n'est pas clair. Plus vous pouvez donner de contexte à Claude sur vos outils, mieux il saura déterminer quand et comment les utiliser. Visez au moins 3 à 4 phrases pour chaque 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 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) pour plus de détails.

* **Regroupez 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 des espaces de noms significatifs 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool).

* **Concevez les réponses des outils pour ne renvoyer que des informations à fort signal.** 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.

* **Demandez une explication, pas un raisonnement.** Si un paramètre demande à Claude pourquoi il effectue l'appel, demandez une courte explication ou les éléments justificatifs. Un paramètre qui demande la réflexion du modèle ou un raisonnement étape par étape peut entraîner un refus `reasoning_extraction`. Consultez [Conserver le raisonnement dans les blocs de réflexion](https://platform.claude.com/docs/fr/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).

<AccordionGroup>
  <Accordion title="Exemple d'une bonne description d'outil">
    ```json JSON
    {
      "name": "get_stock_price",
      "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
      "input_schema": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string",
            "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
          }
        },
        "required": ["ticker"]
      }
    }
    ```
  </Accordion>

  <Accordion title="Exemple de mauvaise description d'outil">
    ```json JSON
    {
      "name": "get_stock_price",
      "description": "Gets the stock price for a ticker.",
      "input_schema": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string"
          }
        },
        "required": ["ticker"]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

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.

<Tip>
  Pour des conseils plus approfondis sur la conception d'outils (regroupement, nommage et mise en forme des réponses), consultez [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents).
</Tip>

## 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. C'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 d'exemple. Chaque exemple doit être valide selon le `input_schema` de l'outil :

<CodeGroup>
  ```bash cURL
  curl -sS https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-opus-5-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"}
          ]
        }
      ],
      "messages": [
        {"role": "user", "content": "What is the weather like in San Francisco?"}
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-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?
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-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"
            // Montre que 'unit' est facultatif.
          }
        ]
      }
    ],
    messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools = [
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the current weather in a given location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" }, description = "The unit of temperature" }),
                  },
                  Required = ["location"],
              },
              InputExamples =
              [
                  new Dictionary<string, JsonElement>()
                  {
                      { "location", JsonSerializer.SerializeToElement("San Francisco, CA") },
                      { "unit", JsonSerializer.SerializeToElement("fahrenheit") },
                  },
                  new Dictionary<string, JsonElement>()
                  {
                      { "location", JsonSerializer.SerializeToElement("Tokyo, Japan") },
                      { "unit", JsonSerializer.SerializeToElement("celsius") },
                  },
                  new Dictionary<string, JsonElement>()
                  {
                      { "location", JsonSerializer.SerializeToElement("New York, NY") },
                  },
              ],
          }),
      ],
      Messages = [
          new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the current weather in a given location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{
  						"type":        "string",
  						"description": "The city and state, e.g. San Francisco, CA",
  					},
  					"unit": map[string]any{
  						"type":        "string",
  						"enum":        []string{"celsius", "fahrenheit"},
  						"description": "The unit of temperature",
  					},
  				},
  				Required: []string{"location"},
  			},
  			InputExamples: []map[string]any{
  				{
  					"location": "San Francisco, CA",
  					"unit":     "fahrenheit",
  				},
  				{
  					"location": "Tokyo, Japan",
  					"unit":     "celsius",
  				},
  				{
  					"location": "New York, NY",
  					// Montre que 'unit' est facultatif.
  				},
  			},
  		}},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.Tool;
  import com.anthropic.models.messages.Tool.InputSchema;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the current weather in a given location")
              .inputSchema(InputSchema.builder()
                  .properties(JsonValue.from(Map.of(
                      "location", Map.of(
                          "type", "string",
                          "description", "The city and state, e.g. San Francisco, CA"
                      ),
                      "unit", Map.of(
                          "type", "string",
                          "enum", List.of("celsius", "fahrenheit"),
                          "description", "The unit of temperature"
                      )
                  )))
                  .required(List.of("location"))
                  .build())
              .putAdditionalProperty("input_examples", JsonValue.from(List.of(
                  Map.of(
                      "location", "San Francisco, CA",
                      "unit", "fahrenheit"
                  ),
                  Map.of(
                      "location", "Tokyo, Japan",
                      "unit", "celsius"
                  ),
                  Map.of(
                      "location", "New York, NY"
                  )
              )))
              .build())
          .addUserMessage("What's the weather like in San Francisco?")
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
      ],
      model: 'claude-opus-5-5',
      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'
                  ]
              ]
          ]
      ],
  );
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: "claude-opus-5-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"
          }
        ]
      }
    ],
    messages: [
      { role: "user", content: "What's the weather like in San Francisco?" }
    ]
  )
  puts message
  ```
</CodeGroup>

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 ou les ensembles d'outils client** - Les exemples d'entrée fonctionnent sur les outils client définis par l'utilisateur et à schéma Anthropic autres que les ensembles d'outils d'[utilisation de l'ordinateur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool) et d'[utilisation du navigateur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool), 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 : environ 20 à 50 tokens pour les exemples simples, environ 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 souhaiter 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.

Tous les modèles et paramètres ne prennent pas en charge l'utilisation forcée d'outils. Lorsqu'elle n'est pas prise en charge, `tool_choice: {"type": "any"}` et `tool_choice: {"type": "tool", "name": "..."}` échouent, tandis que `tool_choice: {"type": "auto"}` (la valeur par défaut) et `tool_choice: {"type": "none"}` fonctionnent toujours :

| Modèle ou paramètre                                                                                                                                           | Restriction                                                                                                              | Que utiliser à la place                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [« Extended thinking » (réflexion étendue)](https://platform.claude.com/docs/fr/build-with-claude/extended-thinking) manuelle (`thinking: {type: "enabled"}`) | `any` et `tool` ne sont pas pris en charge et entraînent une erreur                                                      | `auto` ou `none`. La [réflexion adaptative](https://platform.claude.com/docs/fr/build-with-claude/thinking) elle-même ne bloque pas l'utilisation forcée d'outils (les modèles dont la réflexion est activée par défaut, tels que Claude Opus 5 et Claude Haiku 5.5, l'acceptent, mais un appel forcé ignore la réflexion : la réponse commence par l'appel d'outil et ne contient aucun bloc `thinking`) ; les modèles de la ligne suivante rejettent l'utilisation forcée d'outils quels que soient les paramètres de réflexion |
| Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 et [Claude Mythos 5.1](https://platform.claude.com/docs/fr/models/mythos-5-1/overview)                   | `any` et `tool` renvoient une [erreur 400](https://platform.claude.com/docs/fr/api/errors#forced-tool-use-not-supported) | `auto` avec le « [strict tool use](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/strict-tool-use) » (utilisation stricte d'outils) pour garantir des entrées d'outils conformes au schéma, ou les « [structured outputs](https://platform.claude.com/docs/fr/build-with-claude/structured-outputs) » (sorties structurées) lorsque vous avez besoin d'une réponse dans une forme JSON fixe. Le prompt influence toujours l'outil choisi par `auto`. `none` est également pris en charge                           |

Sur les modèles qui la prennent en charge, les lignes mises en évidence sont la seule différence par rapport à une requête d'utilisation d'outils standard :

<CodeGroup>
  ```bash cURL
  curl -sS https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "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"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "tool", "name": "get_weather"},
      "messages": [
        {"role": "user", "content": "What is the weather like in San Francisco?"}
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  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
        required: [location]
  tool_choice:
    type: tool
    name: get_weather
  messages:
    - role: user
      content: What's the weather like in San Francisco?
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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"
            }
          },
          required: ["location"]
        }
      }
    ],
    tool_choice: { type: "tool", name: "get_weather" },
    messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5,
      MaxTokens = 1024,
      Tools = [
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the current weather in a given location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
                  },
                  Required = ["location"],
              },
          }),
      ],
      ToolChoice = new ToolChoiceTool { Name = "get_weather" },
      Messages = [
          new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the current weather in a given location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{
  						"type":        "string",
  						"description": "The city and state, e.g. San Francisco, CA",
  					},
  				},
  				Required: []string{"location"},
  			},
  		}},
  	},
  	ToolChoice: anthropic.ToolChoiceUnionParam{OfTool: &anthropic.ToolChoiceToolParam{Name: "get_weather"}},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.Tool;
  import com.anthropic.models.messages.Tool.InputSchema;
  import com.anthropic.models.messages.ToolChoice;
  import com.anthropic.models.messages.ToolChoiceTool;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5)
          .maxTokens(1024L)
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the current weather in a given location")
              .inputSchema(InputSchema.builder()
                  .properties(JsonValue.from(Map.of(
                      "location", Map.of(
                          "type", "string",
                          "description", "The city and state, e.g. San Francisco, CA"
                      )
                  )))
                  .required(List.of("location"))
                  .build())
              .build())
          .toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder()
              .name("get_weather")
              .build()))
          .addUserMessage("What's the weather like in San Francisco?")
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
      ],
      model: 'claude-opus-5',
      toolChoice: ['type' => 'tool', 'name' => 'get_weather'],
      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']
              ]
          ]
      ],
  );
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = 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"
            }
          },
          required: ["location"]
        }
      }
    ],
    tool_choice: { type: "tool", name: "get_weather" },
    messages: [
      { role: "user", content: "What's the weather like in San Francisco?" }
    ]
  )
  puts message
  ```
</CodeGroup>

Lorsque vous travaillez avec le paramètre `tool_choice`, il existe quatre options possibles :

* `auto` permet à Claude de déterminer 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.

<Note>
  Lors de l'utilisation de la [mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-cache), les modifications du paramètre `tool_choice` invalideront les blocs de messages mis en cache. Les définitions d'outils et les invites système restent en cache, mais le contenu des messages doit être retraité.
</Note>

Ce diagramme illustre le fonctionnement de chaque option :

<Frame>
  ![Diagramme des trois options de tool\_choice : auto (un outil ou une réponse simple), any (l'un des outils) et tool (l'outil nommé)](https://platform.claude.com/docs/fr/images/tool_choice.svg)
</Frame>

Notez que lorsque `tool_choice` est 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 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 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.`

Forcer un outil ignore également la réflexion sur tous les modèles qui acceptent l'utilisation forcée d'outils : la réponse commence par le bloc `tool_use` et ne contient aucun bloc `thinking`. Pour permettre au modèle de réfléchir avant d'appeler l'outil, utilisez `auto` avec une instruction dans le prompt de la même manière.

<Tip>
  **Appels d'outils garantis avec les outils stricts**

  Sur les modèles qui prennent en charge l'utilisation forcée d'outils, combinez `tool_choice: {"type": "any"}` avec l'[utilisation stricte d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/strict-tool-use) pour garantir à la fois que l'un de vos outils est appelé et que les entrées de l'outil respectent strictement votre schéma. Définissez `strict: true` sur vos définitions d'outils pour activer la validation du schéma.
</Tip>

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

```json JSON
{
  "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

<CardGroup>
  <Card href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/handle-tool-calls" title="Gérer les appels d'outils">
    Analysez les blocs tool\_use et formatez les réponses tool\_result.
  </Card>

  <Card href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-runner" title="Tool Runner (SDK)">
    Laissez le SDK gérer automatiquement la boucle agentique.
  </Card>

  <Card href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference" title="Référence des outils">
    Répertoire des outils fournis par Anthropic et des propriétés facultatives.
  </Card>
</CardGroup>