---
title: Outil de recherche d'outils
url: https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool
description: Passez à l'échelle de centaines ou de milliers d'outils en laissant Claude rechercher dans votre catalogue d'outils et charger uniquement les outils dont il a besoin.
---

L'outil de recherche d'outils (« tool search tool ») permet à Claude de travailler avec des centaines ou des milliers d'outils en les découvrant et en les chargeant à la demande. Au lieu de charger toutes les définitions d'outils dans la « context window » (fenêtre de contexte) dès le départ, Claude recherche dans votre catalogue d'outils (y compris les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments) et charge uniquement les outils dont il a besoin.

Charger chaque définition d'outil dès le départ pose deux problèmes à mesure qu'une bibliothèque d'outils grandit :

* **Encombrement du contexte :** une configuration multiserveur typique (GitHub, Slack, Sentry, Grafana et Splunk) peut consommer environ 55 000 tokens en définitions avant que Claude n'effectue le moindre travail. La recherche d'outils réduit généralement ce chiffre de plus de 85 pour cent, en ne chargeant que les 3 à 5 outils dont Claude a besoin pour une requête donnée.
* **Précision de la sélection d'outils :** la capacité de Claude à choisir le bon outil se dégrade dès que vous dépassez 30 à 50 outils disponibles. Comme la recherche d'outils ne charge à la demande qu'un ensemble ciblé d'outils pertinents, la précision de la sélection reste élevée même parmi des milliers d'outils.

Pour connaître les modèles qui prennent en charge la recherche d'outils, consultez [Compatibilité des modèles](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

<Tip>
  Pour en savoir plus sur les défis de mise à l'échelle que résout la recherche d'outils, consultez [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Le chargement à la demande de la recherche d'outils est également une application du principe plus général de récupération juste-à-temps décrit dans [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
</Tip>

La recherche d'outils s'exécute en tant qu'outil côté serveur, mais vous pouvez également implémenter votre propre recherche d'outils côté client. Consultez [Implémentation personnalisée de la recherche d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation) pour plus de détails.

<Note>
  Partagez vos commentaires sur cette fonctionnalité via le [formulaire de commentaires](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>

<Note>
  Pour savoir comment la « zero data retention » (rétention zéro des données), ou ZDR, s'applique à cette fonctionnalité, consultez [API et rétention des données](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention).
</Note>

<Warning>
  Sur Amazon Bedrock, la recherche d'outils côté serveur est disponible uniquement via l'[API InvokeModel](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), et non via l'API Converse.
</Warning>

<Note>
  Sur [Claude Platform on AWS](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws), la recherche d'outils côté serveur fonctionne de manière identique à l'API Claude. Claude Platform on AWS utilise directement l'API Messages d'Anthropic, il n'y a donc pas de distinction entre InvokeModel et Converse.
</Note>

## Compatibilité des modèles

Les deux variantes de recherche d'outils sont disponibles sur les modèles suivants :

| Modèle                                                                                                                           | Versions de l'outil                                                 |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Claude Fable 5.1 (claude-fable-5-1)                                                                                              | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5.1 (claude-mythos-5-1)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Fable 5 (claude-fable-5)                                                                                                  | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5 (claude-mythos-5)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5.5 (claude-opus-5-5)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5 (claude-opus-5)                                                                                                    | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5.5 (claude-sonnet-5-5)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5 (claude-sonnet-5)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 5.5 (claude-haiku-5-5)                                                                                              | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.8 (claude-opus-4-8)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.7 (claude-opus-4-7)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.6 (claude-opus-4-6)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.6 (claude-sonnet-4-6)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.5 (claude-opus-4-5-20251101)                                                                                       | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) ([déprécié](https://platform.claude.com/docs/fr/about-claude/model-deprecations)) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 4.5 (claude-haiku-4-5-20251001)                                                                                     | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |

Claude Opus 4.1 et les modèles antérieurs ne prennent pas en charge l'outil de recherche d'outils.

## Fonctionnement de la recherche d'outils

Il existe deux variantes de recherche d'outils :

* **Regex** (`tool_search_tool_regex_20251119`) : Claude construit des motifs regex pour rechercher des outils.
* **BM25** (`tool_search_tool_bm25_20251119`) : Claude utilise des requêtes en langage naturel pour rechercher des outils.

Lorsque vous activez l'outil de recherche d'outils :

1. Vous incluez un outil de recherche d'outils (par exemple, `tool_search_tool_regex_20251119` ou `tool_search_tool_bm25_20251119`) dans votre liste `tools`.
2. Vous fournissez chaque définition d'outil dans le tableau `tools` et définissez `defer_loading: true` sur les outils qui ne doivent pas être chargés dès le départ. Au moins un outil, normalement l'outil de recherche d'outils lui-même, doit rester non différé.
3. Initialement, le contexte de Claude ne contient que l'outil de recherche d'outils et les éventuels outils non différés.
4. Lorsque Claude a besoin d'outils supplémentaires, il effectue une recherche à l'aide d'un outil de recherche d'outils.
5. L'API exécute la recherche et renvoie les outils correspondants sous forme de blocs `tool_reference` (jusqu'à 5 par défaut ; Claude peut définir une `limit` dans son entrée de recherche).
6. L'API développe automatiquement ces références en définitions d'outils complètes.
7. Claude choisit parmi les outils découverts et les appelle.

## Démarrage rapide

L'exemple suivant inclut l'outil de recherche d'outils et deux outils différés :

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 2048,
          "messages": [
              {
                  "role": "user",
                  "content": "What is the weather in San Francisco?"
              }
          ],
          "tools": [
              {
                  "type": "tool_search_tool_regex_20251119",
                  "name": "tool_search_tool_regex"
              },
              {
                  "name": "get_weather",
                  "description": "Get the weather at a specific location",
                  "input_schema": {
                      "type": "object",
                      "properties": {
                          "location": {"type": "string"},
                          "unit": {
                              "type": "string",
                              "enum": ["celsius", "fahrenheit"]
                          }
                      },
                      "required": ["location"]
                  },
                  "defer_loading": true
              },
              {
                  "name": "search_files",
                  "description": "Search through files in the workspace",
                  "input_schema": {
                      "type": "object",
                      "properties": {
                          "query": {"type": "string"},
                          "file_types": {
                              "type": "array",
                              "items": {"type": "string"}
                          }
                      },
                      "required": ["query"]
                  },
                  "defer_loading": true
              }
          ]
      }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 2048
  messages:
    - role: user
      content: What is the weather in San Francisco?
  tools:
    - type: tool_search_tool_regex_20251119
      name: tool_search_tool_regex
    - name: get_weather
      description: Get the weather at a specific location
      input_schema:
        type: object
        properties:
          location:
            type: string
          unit:
            type: string
            enum: [celsius, fahrenheit]
        required: [location]
      defer_loading: true
    - name: search_files
      description: Search through files in the workspace
      input_schema:
        type: object
        properties:
          query:
            type: string
          file_types:
            type: array
            items:
              type: string
        required: [query]
      defer_loading: true
  YAML
  ```

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

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=2048,
      messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
      tools=[
          {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
          {
              "name": "get_weather",
              "description": "Get the weather at a specific location",
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "location": {"type": "string"},
                      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                  },
                  "required": ["location"],
              },
              "defer_loading": True,
          },
          {
              "name": "search_files",
              "description": "Search through files in the workspace",
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "query": {"type": "string"},
                      "file_types": {"type": "array", "items": {"type": "string"}},
                  },
                  "required": ["query"],
              },
              "defer_loading": True,
          },
      ],
  )

  print(response)
  ```

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

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 2048,
    messages: [
      {
        role: "user",
        content: "What is the weather in San Francisco?"
      }
    ],
    tools: [
      {
        type: "tool_search_tool_regex_20251119",
        name: "tool_search_tool_regex"
      },
      {
        name: "get_weather",
        description: "Get the weather at a specific location",
        input_schema: {
          type: "object" as const,
          properties: {
            location: { type: "string" },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"]
            }
          },
          required: ["location"]
        },
        defer_loading: true
      },
      {
        name: "search_files",
        description: "Search through files in the workspace",
        input_schema: {
          type: "object" as const,
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  });

  console.log(response);
  ```

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

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 2048,
      Messages = [
          new() {
              Role = Role.User,
              Content = "What is the weather in San Francisco?"
          }
      ],
      Tools = [
          new ToolUnion(new ToolSearchToolRegex20251119
          {
              Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119
          }),
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the weather at a specific location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }),
                  },
                  Required = ["location"],
              },
              DeferLoading = true,
          }),
          new ToolUnion(new Tool()
          {
              Name = "search_files",
              Description = "Search through files in the workspace",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["query"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["file_types"] = JsonSerializer.SerializeToElement(new { type = "array", items = new { type = "string" } }),
                  },
                  Required = ["query"],
              },
              DeferLoading = true,
          }),
      ]
  };

  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: 2048,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfToolSearchToolRegex20251119: &anthropic.ToolSearchToolRegex20251119Param{
  			Type: anthropic.ToolSearchToolRegex20251119TypeToolSearchToolRegex20251119,
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the weather at a specific location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{"type": "string"},
  					"unit": map[string]any{
  						"type": "string",
  						"enum": []string{"celsius", "fahrenheit"},
  					},
  				},
  				Required: []string{"location"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "search_files",
  			Description: anthropic.String("Search through files in the workspace"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"query":      map[string]any{"type": "string"},
  					"file_types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
  				},
  				Required: []string{"query"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.ToolSearchToolRegex20251119;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      InputSchema weatherSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "location", Map.of("type", "string"),
              "unit", Map.of(
                  "type", "string",
                  "enum", List.of("celsius", "fahrenheit")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("location")))
          .build();

      InputSchema searchSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "query", Map.of("type", "string"),
              "file_types", Map.of(
                  "type", "array",
                  "items", Map.of("type", "string")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("query")))
          .build();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(2048L)
          .addUserMessage("What is the weather in San Francisco?")
          .addTool(ToolSearchToolRegex20251119.builder()
              .type(ToolSearchToolRegex20251119.Type.TOOL_SEARCH_TOOL_REGEX_20251119)
              .build())
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the weather at a specific location")
              .inputSchema(weatherSchema)
              .deferLoading(true)
              .build())
          .addTool(Tool.builder()
              .name("search_files")
              .description("Search through files in the workspace")
              .inputSchema(searchSchema)
              .deferLoading(true)
              .build())
          .build();

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

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

  $message = $client->messages->create(
      maxTokens: 2048,
      messages: [
          ['role' => 'user', 'content' => 'What is the weather in San Francisco?'],
      ],
      model: 'claude-opus-5-5',
      tools: [
          [
              'type' => 'tool_search_tool_regex_20251119',
              'name' => 'tool_search_tool_regex',
          ],
          [
              'name' => 'get_weather',
              'description' => 'Get the weather at a specific location',
              'input_schema' => [
                  'type' => 'object',
                  'properties' => [
                      'location' => ['type' => 'string'],
                      'unit' => [
                          'type' => 'string',
                          'enum' => ['celsius', 'fahrenheit'],
                      ],
                  ],
                  'required' => ['location'],
              ],
              'defer_loading' => true,
          ],
          [
              'name' => 'search_files',
              'description' => 'Search through files in the workspace',
              'input_schema' => [
                  'type' => 'object',
                  'properties' => [
                      'query' => ['type' => 'string'],
                      'file_types' => [
                          'type' => 'array',
                          'items' => ['type' => 'string'],
                      ],
                  ],
                  'required' => ['query'],
              ],
              'defer_loading' => true,
          ],
      ],
  );

  echo $message;
  ```

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

  message = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 2048,
    messages: [
      { role: "user", content: "What is the weather in San Francisco?" }
    ],
    tools: [
      {
        type: "tool_search_tool_regex_20251119",
        name: "tool_search_tool_regex"
      },
      {
        name: "get_weather",
        description: "Get the weather at a specific location",
        input_schema: {
          type: "object",
          properties: {
            location: { type: "string" },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"]
            }
          },
          required: ["location"]
        },
        defer_loading: true
      },
      {
        name: "search_files",
        description: "Search through files in the workspace",
        input_schema: {
          type: "object",
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  )

  puts message
  ```
</CodeGroup>

Claude recherche dans le catalogue, découvre `get_weather` et l'appelle. La réponse se termine par `stop_reason: "tool_use"`. Exécutez l'outil découvert et renvoyez un `tool_result` comme dans [Gérer les appels d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/handle-tool-calls). La section [Format de réponse](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool#response-format) montre les blocs que vous recevez en retour et ce qu'il faut envoyer ensuite.

## Définition de l'outil

L'outil de recherche d'outils possède deux variantes :

```json JSON
{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}
```

```json JSON
{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}
```

<Warning>
  **Format de requête de la variante regex : regex Python, pas de langage naturel**

  Avec `tool_search_tool_regex_20251119`, Claude écrit des motifs Python `re.search()`, et non des requêtes en langage naturel. La correspondance est insensible à la casse. Les motifs courants incluent les suivants :

  * `"weather"` : correspond aux noms et descriptions d'outils contenant « weather »
  * `"get_.*_data"` : correspond à des outils tels que `get_user_data` et `get_weather_data`
  * `"database.*query|query.*database"` : correspond à l'un ou l'autre ordre des mots

  Longueur maximale du motif : 200 caractères
</Warning>

<Note>
  **Format de requête de la variante BM25 : langage naturel**

  Avec `tool_search_tool_bm25_20251119`, Claude effectue des recherches avec des requêtes en langage naturel. Longueur maximale de la requête : 500 caractères.
</Note>

### Chargement différé des outils

Marquez les outils pour un chargement à la demande en ajoutant `defer_loading: true` :

```json JSON
{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}
```

`defer_loading` contrôle ce qui entre dans la fenêtre de contexte, et non ce que vous envoyez dans la requête :

* Vous envoyez toujours la définition complète de chaque outil dans le tableau `tools` à chaque requête, y compris les outils différés. L'API en a besoin côté serveur pour exécuter la recherche et développer les blocs `tool_reference`.
* Les outils sans `defer_loading` sont chargés immédiatement dans le contexte.
* Les outils avec `defer_loading: true` ne sont chargés que lorsque Claude les découvre via la recherche.
* Ne définissez jamais `defer_loading: true` sur l'outil de recherche d'outils lui-même.
* Gardez vos 3 à 5 outils les plus fréquemment utilisés non différés afin que Claude puisse les appeler sans effectuer de recherche préalable.

Les ensembles d'outils d'utilisation de l'ordinateur et d'utilisation du navigateur (`computer_toolset_20260801` et `browser_toolset_20260801`) acceptent `defer_loading` par outil membre à l'intérieur de l'objet `configs` de l'entrée, et non sur l'entrée elle-même ; une requête qui le définit au niveau de l'entrée est rejetée. Comme un ensemble d'outils est différé et développé en tant qu'unité, `defer_loading` doit se résoudre à la même valeur pour chaque membre activé, et lorsque Claude découvre l'ensemble d'outils via la recherche, tous les membres activés sont chargés en même temps. Consultez [Ensembles d'outils client](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets) pour le format de `configs`.

Les deux variantes de recherche d'outils (`regex` et `bm25`) recherchent dans les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments.

En interne, l'API exclut les outils différés du préfixe de l'invite système. Lorsque Claude découvre un outil différé via la recherche d'outils, l'API ajoute un bloc `tool_reference` en ligne dans la conversation, puis le développe en définition d'outil complète avant de le transmettre à Claude. Le préfixe reste intact, de sorte que la « prompt caching » (mise en cache des prompts) est préservée. La grammaire du [mode strict](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/strict-tool-use) (les règles qui contraignent la sortie des appels d'outils à correspondre à vos schémas) est construite à partir de l'ensemble complet des outils, de sorte que `defer_loading` et le mode strict se combinent sans recompilation de la grammaire.

## Format de réponse

Lorsque Claude utilise l'outil de recherche d'outils, la réponse inclut les types de blocs suivants :

```json JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}
```

### Comprendre la réponse

* **`server_tool_use` :** l'appel de Claude à l'outil de recherche d'outils. La recherche s'exécute sur les serveurs d'Anthropic. Ne renvoyez jamais de `tool_result` pour son ID `srvtoolu_...`. Le champ `input` contient la recherche (`pattern` pour la variante regex, `query` pour BM25) et peut inclure une `limit` facultative, un entier de 1 à 10 000 qui plafonne le nombre d'outils correspondants renvoyés par la recherche (par défaut : 5).
* **`tool_search_tool_result` :** les résultats de la recherche, dans un objet `tool_search_tool_search_result` imbriqué. Conservez-le tel quel dans l'historique des messages.
* **`tool_references` :** un tableau d'objets `tool_reference` pointant vers les outils découverts. L'API les développe pour Claude. Vous ne les développez jamais vous-même.
* **`tool_use` :** l'appel de Claude à un outil découvert. Exécutez-le et renvoyez un `tool_result` exactement comme dans l'utilisation d'outils standard.

L'API développe automatiquement les blocs `tool_reference` en définitions d'outils complètes avant de les montrer à Claude. Vous n'avez pas besoin de gérer ce développement vous-même, tant que vous fournissez toutes les définitions d'outils correspondantes dans le paramètre `tools`.

### Poursuivre la conversation

Lors de la requête suivante, renvoyez le contenu de l'assistant sans modification, y compris les blocs `server_tool_use` et `tool_search_tool_result`. Ajoutez votre `tool_result` pour l'outil découvert dans un message utilisateur, et envoyez le même tableau `tools` : l'outil de recherche plus chaque définition différée. Ne renvoyez pas de `tool_result` pour l'ID `srvtoolu_...` : l'API rejette la requête. L'API développe les blocs `tool_reference` dans tout l'historique de la conversation, de sorte que Claude peut réutiliser les outils découverts lors des tours suivants sans effectuer de nouvelle recherche. Une recherche qui ne trouve aucune correspondance renvoie un `tool_search_tool_search_result` avec un tableau `tool_references` vide, et non une erreur.

## Intégration MCP

Si vos outils proviennent de serveurs MCP via le [connecteur MCP](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector), vous ne définissez pas `defer_loading` sur les définitions d'outils individuelles. Définissez-le plutôt une seule fois dans le `default_config` de l'entrée `mcp_toolset` pour l'ensemble du serveur, ou par outil dans ses `configs`. Consultez [Configuration de l'ensemble d'outils MCP](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#mcp-toolset-configuration).

## Implémentation personnalisée de la recherche d'outils

Vous pouvez implémenter votre propre logique de recherche d'outils (par exemple, à l'aide d'embeddings ou de recherche sémantique) en renvoyant des blocs `tool_reference` depuis un outil personnalisé. Lorsque Claude appelle votre outil de recherche personnalisé, renvoyez un `tool_result` standard avec des blocs `tool_reference` dans le tableau de contenu :

```json JSON
{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
```

Chaque outil référencé doit avoir une définition d'outil correspondante dans le paramètre `tools` de niveau supérieur, normalement avec `defer_loading: true`. Cela vous permet d'utiliser des méthodes de recherche que les variantes intégrées ne fournissent pas, comme la récupération basée sur les embeddings, et l'API développe les blocs `tool_reference` renvoyés de la même manière.

<Note>
  Le format `tool_search_tool_result` présenté dans la section [Format de réponse](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool#response-format) est le format côté serveur utilisé en interne par la recherche d'outils intégrée d'Anthropic. Pour les implémentations personnalisées côté client, utilisez toujours le format `tool_result` standard avec des blocs de contenu `tool_reference`, comme illustré dans l'exemple précédent.
</Note>

Pour un exemple complet utilisant des embeddings, consultez la recette [recherche d'outils avec embeddings](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings).

## Gestion des erreurs

<Note>
  Les [exemples d'utilisation d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) fonctionnent avec la recherche d'outils : lorsque Claude découvre un outil différé, l'API développe ses `input_examples` en même temps que sa définition.
</Note>

### Erreurs HTTP (statut 400)

Ces erreurs empêchent l'API de traiter la requête :

**Tous les outils sont différés :**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}
```

**Définition d'outil manquante :**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}
```

### Erreurs de résultat d'outil (statut 200)

Lorsqu'une opération de recherche d'outils échoue pendant l'exécution, l'API renvoie une réponse 200 avec l'erreur dans le corps :

```json JSON
{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}
```

Le champ `error_code` a quatre valeurs possibles :

* `invalid_tool_input` : l'entrée de recherche était invalide, par exemple un motif regex mal formé ou un motif dépassant la limite de 200 caractères
* `unavailable` : la recherche n'a pas pu s'exécuter, par exemple parce qu'elle a expiré ou que le service était indisponible
* `too_many_requests` : limite de débit dépassée pour les opérations de recherche d'outils
* `execution_time_exceeded` : la recherche a dépassé sa limite de temps d'exécution

### Erreurs courantes

<Accordion title="Erreur 400 : tous les outils sont différés">
  **Cause :** vous avez défini `defer_loading: true` sur chaque outil, y compris l'outil de recherche d'outils.

  **Correction :** supprimez `defer_loading` de l'outil de recherche d'outils :

  ```json
  {
    "type": "tool_search_tool_regex_20251119",
    "name": "tool_search_tool_regex"
  }
  ```
</Accordion>

<Accordion title="Erreur 400 : définition d'outil manquante">
  **Cause :** un `tool_reference` pointe vers un outil absent de votre tableau `tools`.

  **Correction :** assurez-vous que chaque outil susceptible d'être découvert possède une définition complète :

  ```json
  {
    "name": "my_tool",
    "description": "Full description here",
    "input_schema": {
      "type": "object"
    },
    "defer_loading": true
  }
  ```
</Accordion>

<Accordion title="Claude ne trouve pas les outils attendus">
  **Cause :** le motif regex ne correspond pas au nom, à la description, aux noms d'arguments ou aux descriptions d'arguments de l'outil.

  **Étapes de débogage :**

  1. Vérifiez le nom de l'outil, sa description, les noms d'arguments et les descriptions d'arguments. Claude recherche dans tous ces champs.
  2. Testez votre motif : `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
  3. La correspondance est insensible à la casse, donc les différences de casse ne sont pas le problème.
  4. Claude utilise des motifs larges tels que `".*weather.*"`, et non des correspondances exactes.

  **Conseil :** ajoutez des mots-clés courants aux descriptions d'outils pour améliorer leur découvrabilité.
</Accordion>

## Mise en cache des prompts

Pour savoir comment `defer_loading` préserve la mise en cache des prompts, consultez [Utilisation d'outils avec mise en cache des prompts](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-use-with-prompt-caching).

Un outil avec `defer_loading: true` ne peut pas également porter `cache_control` : l'API renvoie une erreur 400. Placez le point de rupture du cache sur un outil non différé.

## Streaming

Avec le streaming activé, vous recevrez les événements de recherche d'outils dans le flux :

```sse
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools
```

## Requêtes par lots

Vous pouvez inclure l'outil de recherche d'outils dans l'[API Messages Batches](https://platform.claude.com/docs/fr/build-with-claude/batch-processing).

## Limites et bonnes pratiques

### Limites

* **Nombre maximal d'outils différés :** 10 000 outils avec `defer_loading: true` par requête
* **Résultats de recherche :** chaque recherche renvoie jusqu'à 5 outils correspondants par défaut ; Claude peut définir `limit` dans son entrée de recherche sur n'importe quel entier de 1 à 10 000
* **Longueur des motifs et des requêtes :** maximum 200 caractères pour les motifs regex et 500 caractères pour les requêtes BM25
* **Prise en charge des modèles :** consultez [Compatibilité des modèles](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool#model-compatibility)

### Quand utiliser la recherche d'outils

Utilisez la recherche d'outils lorsque l'une des conditions suivantes s'applique :

* Vous disposez de 10 outils ou plus.
* Vos définitions d'outils consomment plus de 10 000 tokens.
* La précision de la sélection d'outils diminue à mesure que votre ensemble d'outils grandit.
* Vous agrégez plusieurs serveurs MCP (plus de 200 outils).
* Votre bibliothèque d'outils grandit au fil du temps.

L'appel d'outils standard, sans recherche d'outils, convient mieux lorsque vous avez moins de 10 outils, que chaque outil est utilisé dans chaque requête, ou que vos définitions d'outils sont petites (moins de 100 tokens au total).

### Conseils d'optimisation

* Gardez vos 3 à 5 outils les plus fréquemment utilisés non différés.
* Rédigez des noms et des descriptions d'outils clairs et descriptifs.
* Utilisez un espace de noms cohérent dans les noms d'outils : préfixez par service ou ressource (par exemple, `github_`, `slack_`) afin qu'une seule recherche corresponde à tout le groupe.
* Utilisez dans les descriptions des mots-clés qui correspondent à la façon dont les utilisateurs décrivent les tâches.
* Ajoutez une section d'invite système décrivant les catégories d'outils disponibles : « Vous pouvez rechercher des outils pour interagir avec Slack, GitHub et Jira. »
* Surveillez les outils que Claude découvre afin d'affiner vos descriptions.

## Utilisation

La recherche d'outils n'est pas comptabilisée comme un outil serveur distinct. L'objet `usage.server_tool_use` de la réponse ne comporte aucun champ de recherche d'outils, et les définitions d'outils que la recherche charge dans le contexte comptent comme des tokens d'entrée, comme toute autre définition d'outil.

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Outil de mémoire" icon="brain" href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/memory-tool">
    Permettez à Claude de stocker et de récupérer des informations d'une conversation à l'autre en implémentant les opérations de fichiers de l'outil de mémoire dans votre application.
  </Card>

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

  <Card title="Connecteur MCP" icon="link" href="https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector">
    Configurez des ensembles d'outils MCP avec chargement différé.
  </Card>

  <Card title="Utilisation d'outils avec mise en cache des prompts" icon="bolt" href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    Mettez en cache les définitions d'outils d'un tour à l'autre et comprenez ce qui invalide votre cache.
  </Card>

  <Card title="Définir des outils" icon="hammer" href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/define-tools">
    Spécifiez les schémas d'outils, rédigez des descriptions efficaces et contrôlez quand Claude appelle vos outils.
  </Card>
</CardGroup>