---
title: Tool-Search-Tool
url: https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool
description: Skaliere auf Hunderte oder Tausende von Tools, indem du Claude deinen Tool-Katalog durchsuchen und nur die Tools laden lässt, die es benötigt.
---

Das „tool search tool“ (Tool-Search-Tool, also Tool-Suche-Tool) ermöglicht es Claude, mit Hunderten oder Tausenden von Tools zu arbeiten, indem es diese bei Bedarf entdeckt und lädt. Anstatt alle Tool-Definitionen vorab in das „context window“ (Kontextfenster) zu laden, durchsucht Claude deinen Tool-Katalog (einschließlich Tool-Namen, Beschreibungen, Argumentnamen und Argumentbeschreibungen) und lädt nur die Tools, die es benötigt.

Das Vorabladen jeder Tool-Definition verursacht zwei Probleme, wenn eine Tool-Bibliothek wächst:

* **Aufgeblähter Kontext:** Ein typisches Multiserver-Setup (GitHub, Slack, Sentry, Grafana und Splunk) kann \~55k Token an Definitionen verbrauchen, bevor Claude überhaupt etwas tut. Die Tool-Suche reduziert dies typischerweise um über 85 Prozent, indem nur die 3–5 Tools geladen werden, die Claude für eine bestimmte Anfrage benötigt.
* **Genauigkeit der Tool-Auswahl:** Claudes Fähigkeit, das richtige Tool auszuwählen, nimmt ab, sobald du 30–50 verfügbare Tools überschreitest. Da die Tool-Suche bei Bedarf nur eine fokussierte Menge relevanter Tools lädt, bleibt die Auswahlgenauigkeit selbst bei Tausenden von Tools hoch.

Welche Modelle die Tool-Suche unterstützen, findest du unter [Modellkompatibilität](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

<Tip>
  Hintergrundinformationen zu den Skalierungsherausforderungen, die die Tool-Suche löst, findest du unter [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Das bedarfsgesteuerte Laden der Tool-Suche ist außerdem ein Beispiel für das umfassendere Just-in-Time-Retrieval-Prinzip, das in [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) beschrieben wird.
</Tip>

Die Tool-Suche läuft als serverseitiges Tool, aber du kannst auch deine eigene clientseitige Tool-Suche implementieren. Details findest du unter [Benutzerdefinierte Implementierung der Tool-Suche](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation).

<Note>
  Teile Feedback zu diesem Feature über das [Feedback-Formular](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>

<Note>
  Um zu erfahren, wie „zero data retention“ (Null-Datenspeicherung), oder ZDR, auf diese Funktion angewendet wird, siehe [API und Datenspeicherung](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention).
</Note>

<Warning>
  Auf Amazon Bedrock ist die serverseitige Tool-Suche nur über die [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html) verfügbar, nicht über die Converse API.
</Warning>

<Note>
  Auf der [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws) funktioniert die serverseitige Tool-Suche identisch zur Claude API. Claude Platform on AWS verwendet die Anthropic Messages API direkt, daher gibt es keine Unterscheidung zwischen InvokeModel und Converse.
</Note>

## Modellkompatibilität

Beide Varianten der Tool-Suche sind auf den folgenden Modellen verfügbar:

| Modell                                                                                                                              | Tool-Versionen                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 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) ([abgekündigt](https://platform.claude.com/docs/de/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 und frühere Modelle unterstützen das Tool-Search-Tool nicht.

## So funktioniert die Tool-Suche

Es gibt zwei Varianten der Tool-Suche:

* **Regex** (`tool_search_tool_regex_20251119`): Claude erstellt Regex-Muster, um nach Tools zu suchen.
* **BM25** (`tool_search_tool_bm25_20251119`): Claude verwendet Abfragen in natürlicher Sprache, um nach Tools zu suchen.

Wenn du das Tool-Search-Tool aktivierst:

1. Du fügst ein Tool-Search-Tool (zum Beispiel `tool_search_tool_regex_20251119` oder `tool_search_tool_bm25_20251119`) in deine `tools`-Liste ein.
2. Du stellst jede Tool-Definition im `tools`-Array bereit und setzt `defer_loading: true` bei den Tools, die nicht vorab geladen werden sollen. Mindestens ein Tool, normalerweise das Tool-Search-Tool selbst, muss nicht zurückgestellt bleiben.
3. Anfangs enthält Claudes Kontext nur das Tool-Search-Tool und alle nicht zurückgestellten Tools.
4. Wenn Claude zusätzliche Tools benötigt, sucht es mithilfe eines Tool-Search-Tools.
5. Die API führt die Suche aus und gibt die passenden Tools als `tool_reference`-Blöcke zurück (standardmäßig bis zu 5; Claude kann in seiner Sucheingabe ein `limit` setzen).
6. Die API erweitert diese Referenzen automatisch zu vollständigen Tool-Definitionen.
7. Claude wählt aus den entdeckten Tools aus und ruft sie auf.

## Schnellstart

Das folgende Beispiel enthält das Tool-Search-Tool und zwei zurückgestellte Tools:

<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 durchsucht den Katalog, entdeckt `get_weather` und ruft es auf. Die Antwort endet mit `stop_reason: "tool_use"`. Führe das entdeckte Tool aus und gib ein `tool_result` zurück, wie unter [Tool-Aufrufe verarbeiten](https://platform.claude.com/docs/de/agents-and-tools/tool-use/handle-tool-calls) beschrieben. [Antwortformat](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool#response-format) zeigt die Blöcke, die du zurückerhältst, und was du als Nächstes senden musst.

## Tool-Definition

Das Tool-Search-Tool hat zwei Varianten:

```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>
  **Abfrageformat der Regex-Variante: Python-Regex, keine natürliche Sprache**

  Mit `tool_search_tool_regex_20251119` schreibt Claude Python-`re.search()`-Muster, keine Abfragen in natürlicher Sprache. Der Abgleich erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung. Häufige Muster sind unter anderem:

  * `"weather"`: findet Tool-Namen und Beschreibungen, die „weather“ enthalten
  * `"get_.*_data"`: findet Tools wie `get_user_data` und `get_weather_data`
  * `"database.*query|query.*database"`: findet beide Wortreihenfolgen

  Maximale Musterlänge: 200 Zeichen
</Warning>

<Note>
  **Abfrageformat der BM25-Variante: natürliche Sprache**

  Mit `tool_search_tool_bm25_20251119` sucht Claude mit Abfragen in natürlicher Sprache. Maximale Abfragelänge: 500 Zeichen.
</Note>

### Verzögertes Laden von Tools

Markiere Tools für das bedarfsgesteuerte Laden, indem du `defer_loading: true` hinzufügst:

```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` steuert, was in das Kontextfenster gelangt, nicht, was du in der Anfrage sendest:

* Du sendest weiterhin bei jeder Anfrage die vollständige Definition jedes Tools im `tools`-Array, einschließlich der zurückgestellten. Die API benötigt sie serverseitig, um die Suche auszuführen und `tool_reference`-Blöcke zu erweitern.
* Tools ohne `defer_loading` werden sofort in den Kontext geladen.
* Tools mit `defer_loading: true` werden nur geladen, wenn Claude sie über die Suche entdeckt.
* Setze niemals `defer_loading: true` beim Tool-Search-Tool selbst.
* Lass deine 3–5 am häufigsten verwendeten Tools nicht zurückgestellt, damit Claude sie aufrufen kann, ohne zuerst suchen zu müssen.

Die Toolsets für Computer Use und Browser Use (`computer_toolset_20260801` und `browser_toolset_20260801`) nehmen `defer_loading` pro Mitglieds-Tool innerhalb des `configs`-Objekts des Eintrags entgegen, nicht auf dem Eintrag selbst; eine Anfrage, die es auf Eintragsebene setzt, wird abgelehnt. Da ein Toolset als Einheit zurückgestellt und erweitert wird, muss `defer_loading` bei jedem aktivierten Mitglied zum selben Wert aufgelöst werden, und wenn Claude das Toolset über die Suche entdeckt, werden alle aktivierten Mitglieder auf einmal geladen. Das `configs`-Format findest du unter [Client-Toolsets](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference#client-toolsets).

Beide Varianten der Tool-Suche (`regex` und `bm25`) durchsuchen Tool-Namen, Beschreibungen, Argumentnamen und Argumentbeschreibungen.

Intern schließt die API zurückgestellte Tools aus dem System-Prompt-Präfix aus. Wenn Claude ein zurückgestelltes Tool über die Tool-Suche entdeckt, hängt die API einen `tool_reference`-Block inline in die Konversation an und erweitert ihn dann zur vollständigen Tool-Definition, bevor sie ihn an Claude übergibt. Das Präfix bleibt unberührt, sodass das „prompt caching“ (Prompt-Caching) erhalten bleibt. Die Grammatik für den [Strict Mode](https://platform.claude.com/docs/de/agents-and-tools/tool-use/strict-tool-use) (die Regeln, die die Tool-Aufruf-Ausgabe auf deine Schemas beschränken) wird aus dem vollständigen Toolset erstellt, sodass `defer_loading` und Strict Mode ohne Neukompilierung der Grammatik zusammenwirken.

## Antwortformat

Wenn Claude das Tool-Search-Tool verwendet, enthält die Antwort die folgenden Blocktypen:

```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"
}
```

### Die Antwort verstehen

* **`server_tool_use`:** Claudes Aufruf des Tool-Search-Tools. Die Suche läuft auf den Servern von Anthropic. Gib niemals ein `tool_result` für dessen `srvtoolu_...`-ID zurück. Das `input` enthält die Suche (`pattern` für die Regex-Variante, `query` für BM25) und kann ein optionales `limit` enthalten, eine Ganzzahl von 1 bis 10.000, die begrenzt, wie viele passende Tools die Suche zurückgibt (Standard: 5).
* **`tool_search_tool_result`:** die Suchergebnisse in einem verschachtelten `tool_search_tool_search_result`-Objekt. Behalte es unverändert im Nachrichtenverlauf.
* **`tool_references`:** ein Array von `tool_reference`-Objekten, die auf entdeckte Tools verweisen. Die API erweitert diese für Claude. Du erweiterst sie niemals selbst.
* **`tool_use`:** Claudes Aufruf eines entdeckten Tools. Führe es aus und gib ein `tool_result` genau wie bei der standardmäßigen Tool-Nutzung zurück.

Die API erweitert `tool_reference`-Blöcke automatisch zu vollständigen Tool-Definitionen, bevor sie Claude angezeigt werden. Du musst diese Erweiterung nicht selbst übernehmen, solange du alle passenden Tool-Definitionen im `tools`-Parameter bereitstellst.

### Die Konversation fortsetzen

Gib bei der nächsten Anfrage den Inhalt des Assistenten unverändert zurück, einschließlich der `server_tool_use`- und `tool_search_tool_result`-Blöcke. Füge dein `tool_result` für das entdeckte Tool in einer User-Nachricht hinzu und sende dasselbe `tools`-Array: das Such-Tool plus jede zurückgestellte Definition. Gib kein `tool_result` für die `srvtoolu_...`-ID zurück: Die API lehnt die Anfrage ab. Die API erweitert `tool_reference`-Blöcke im gesamten Konversationsverlauf, sodass Claude entdeckte Tools in späteren Zügen wiederverwenden kann, ohne erneut zu suchen. Eine Suche ohne Treffer gibt ein `tool_search_tool_search_result` mit einem leeren `tool_references`-Array zurück, keinen Fehler.

## MCP-Integration

Wenn deine Tools über den [MCP-Connector](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector) von MCP-Servern stammen, setzt du `defer_loading` nicht bei einzelnen Tool-Definitionen. Setze es stattdessen einmal in der `default_config` des `mcp_toolset`-Eintrags für den gesamten Server oder pro Tool in dessen `configs`. Siehe [MCP-Toolset-Konfiguration](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#mcp-toolset-configuration).

## Benutzerdefinierte Implementierung der Tool-Suche

Du kannst deine eigene Tool-Suchlogik implementieren (zum Beispiel mit Embeddings oder semantischer Suche), indem du `tool_reference`-Blöcke aus einem benutzerdefinierten Tool zurückgibst. Wenn Claude dein benutzerdefiniertes Such-Tool aufruft, gib ein standardmäßiges `tool_result` mit `tool_reference`-Blöcken im Content-Array zurück:

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

Jedes referenzierte Tool muss eine entsprechende Tool-Definition im `tools`-Parameter der obersten Ebene haben, normalerweise mit `defer_loading: true`. So kannst du Suchmethoden verwenden, die die integrierten Varianten nicht bieten, etwa Embedding-basiertes Retrieval, und die API erweitert die zurückgegebenen `tool_reference`-Blöcke auf dieselbe Weise.

<Note>
  Das im Abschnitt [Antwortformat](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool#response-format) gezeigte `tool_search_tool_result`-Format ist das serverseitige Format, das intern von Anthropics integrierter Tool-Suche verwendet wird. Verwende für benutzerdefinierte clientseitige Implementierungen immer das standardmäßige `tool_result`-Format mit `tool_reference`-Content-Blöcken, wie im vorangehenden Beispiel gezeigt.
</Note>

Ein vollständiges Beispiel mit Embeddings findest du im Rezept [Tool-Suche mit Embeddings](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings).

## Fehlerbehandlung

<Note>
  [Beispiele zur Tool-Nutzung](https://platform.claude.com/docs/de/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) funktionieren mit der Tool-Suche: Wenn Claude ein zurückgestelltes Tool entdeckt, erweitert die API dessen `input_examples` zusammen mit seiner Definition.
</Note>

### HTTP-Fehler (Status 400)

Diese Fehler verhindern, dass die API die Anfrage verarbeitet:

**Alle Tools zurückgestellt:**

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

**Fehlende Tool-Definition:**

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

### Tool-Result-Fehler (Status 200)

Wenn eine Tool-Suchoperation während der Ausführung fehlschlägt, gibt die API eine 200-Antwort mit dem Fehler im Body zurück:

```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"
  }
}
```

Das Feld `error_code` hat vier mögliche Werte:

* `invalid_tool_input`: Die Sucheingabe war ungültig, zum Beispiel ein fehlerhaftes Regex-Muster oder ein Muster über dem Limit von 200 Zeichen
* `unavailable`: Die Suche konnte nicht ausgeführt werden, zum Beispiel wegen einer Zeitüberschreitung oder weil der Dienst nicht verfügbar war
* `too_many_requests`: Ratenlimit für Tool-Suchoperationen überschritten
* `execution_time_exceeded`: Die Suche hat ihr Ausführungszeitlimit überschritten

### Häufige Fehler

<Accordion title="400-Fehler: Alle Tools sind zurückgestellt">
  **Ursache:** Du hast `defer_loading: true` bei jedem Tool gesetzt, einschließlich des Tool-Search-Tools.

  **Lösung:** Entferne `defer_loading` vom Tool-Search-Tool:

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

<Accordion title="400-Fehler: Fehlende Tool-Definition">
  **Ursache:** Eine `tool_reference` verweist auf ein Tool, das nicht in deinem `tools`-Array enthalten ist.

  **Lösung:** Stelle sicher, dass jedes Tool, das entdeckt werden könnte, eine vollständige Definition hat:

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

<Accordion title="Claude findet erwartete Tools nicht">
  **Ursache:** Das Regex-Muster passt nicht zum Namen, zur Beschreibung, zu den Argumentnamen oder den Argumentbeschreibungen des Tools.

  **Schritte zur Fehlersuche:**

  1. Prüfe Tool-Namen, Beschreibung, Argumentnamen und Argumentbeschreibungen. Claude durchsucht alle diese Felder.
  2. Teste dein Muster: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
  3. Der Abgleich erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung, daher sind Unterschiede in der Schreibweise nicht das Problem.
  4. Claude verwendet breite Muster wie `".*weather.*"`, keine exakten Übereinstimmungen.

  **Tipp:** Füge Tool-Beschreibungen gängige Schlüsselwörter hinzu, um die Auffindbarkeit zu verbessern.
</Accordion>

## Prompt-Caching

Wie `defer_loading` das Prompt-Caching erhält, erfährst du unter [Tool-Nutzung mit Prompt-Caching](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-use-with-prompt-caching).

Ein Tool mit `defer_loading: true` kann nicht zusätzlich `cache_control` tragen: Die API gibt einen 400-Fehler zurück. Setze den Cache-Breakpoint auf ein nicht zurückgestelltes Tool.

## Streaming

Bei aktiviertem Streaming erhältst du Tool-Suchereignisse als Teil des Streams:

```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
```

## Batch-Anfragen

Du kannst das Tool-Search-Tool in der [Messages Batches API](https://platform.claude.com/docs/de/build-with-claude/batch-processing) verwenden.

## Limits und Best Practices

### Limits

* **Maximale Anzahl zurückgestellter Tools:** 10.000 Tools mit `defer_loading: true` pro Anfrage
* **Suchergebnisse:** Jede Suche gibt standardmäßig bis zu 5 passende Tools zurück; Claude kann `limit` in seiner Sucheingabe auf jede Ganzzahl von 1 bis 10.000 setzen
* **Muster- und Abfragelänge:** maximal 200 Zeichen für Regex-Muster und 500 Zeichen für BM25-Abfragen
* **Modellunterstützung:** siehe [Modellkompatibilität](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool#model-compatibility)

### Wann du die Tool-Suche verwenden solltest

Verwende die Tool-Suche, wenn einer der folgenden Punkte zutrifft:

* Du hast 10 oder mehr Tools zur Verfügung.
* Deine Tool-Definitionen verbrauchen mehr als 10k Token.
* Die Genauigkeit der Tool-Auswahl sinkt, wenn dein Toolset wächst.
* Du aggregierst mehrere MCP-Server (200+ Tools).
* Deine Tool-Bibliothek wächst im Laufe der Zeit.

Standardmäßige Tool-Aufrufe ohne Tool-Suche sind besser geeignet, wenn du weniger als 10 Tools hast, jedes Tool in jeder Anfrage verwendet wird oder deine Tool-Definitionen klein sind (insgesamt weniger als 100 Token).

### Optimierungstipps

* Lass deine 3–5 am häufigsten verwendeten Tools nicht zurückgestellt.
* Schreibe klare, aussagekräftige Tool-Namen und Beschreibungen.
* Verwende konsistente Namensräume in Tool-Namen: Stelle ein Präfix nach Dienst oder Ressource voran (zum Beispiel `github_`, `slack_`), damit eine Suche die gesamte Gruppe findet.
* Verwende in Beschreibungen Schlüsselwörter, die dazu passen, wie Nutzer Aufgaben beschreiben.
* Füge einen System-Prompt-Abschnitt hinzu, der die verfügbaren Tool-Kategorien beschreibt: „You can search for tools to interact with Slack, GitHub, and Jira.“
* Beobachte, welche Tools Claude entdeckt, um deine Beschreibungen zu verfeinern.

## Nutzung

Die Tool-Suche wird nicht als separates Server-Tool abgerechnet. Das `usage.server_tool_use`-Objekt der Antwort hat kein Feld für die Tool-Suche, und die Tool-Definitionen, die die Suche in den Kontext lädt, zählen wie jede andere Tool-Definition als Input-Token.

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Memory-Tool" icon="brain" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/memory-tool">
    Lass Claude Informationen über Konversationen hinweg speichern und abrufen, indem du die Dateioperationen des Memory-Tools in deiner Anwendung implementierst.
  </Card>

  <Card title="Tool-Referenz" icon="book" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference">
    Verzeichnis der von Anthropic bereitgestellten Tools und Referenz für optionale Eigenschaften von Tool-Definitionen.
  </Card>

  <Card title="MCP-Connector" icon="link" href="https://platform.claude.com/docs/de/agents-and-tools/mcp-connector">
    Konfiguriere MCP-Toolsets mit verzögertem Laden.
  </Card>

  <Card title="Tool-Nutzung mit Prompt-Caching" icon="bolt" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    Cache Tool-Definitionen über Züge hinweg und verstehe, was deinen Cache ungültig macht.
  </Card>

  <Card title="Tools definieren" icon="hammer" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/define-tools">
    Lege Tool-Schemas fest, schreibe wirksame Beschreibungen und steuere, wann Claude deine Tools aufruft.
  </Card>
</CardGroup>