Tools

Tool-Suchwerkzeug

Ermöglichen Sie Claude, mit Hunderten oder Tausenden von Werkzeugen zu arbeiten, indem Sie diese dynamisch entdecken und bei Bedarf laden.

Das Tool-Suchwerkzeug ermöglicht Claude, mit Hunderten oder Tausenden von Werkzeugen zu arbeiten, indem diese dynamisch entdeckt und bei Bedarf geladen werden. Anstatt alle Werkzeugdefinitionen vorab in das Kontextfenster zu laden, durchsucht Claude Ihren Werkzeugkatalog – einschließlich Werkzeugnamen, Beschreibungen, Argumentnamen und Argumentbeschreibungen – und lädt nur die Werkzeuge, die er benötigt.

Dieser Ansatz löst zwei kritische Herausforderungen, wenn Werkzeugbibliotheken skaliert werden:

Kontexteffizienz: Werkzeugdefinitionen können massive Teile Ihres Kontextfensters verbrauchen (50 Werkzeuge ≈ 10-20K Token), was weniger Platz für tatsächliche Arbeit lässt
Genauigkeit der Werkzeugauswahl: Claudes Fähigkeit, Werkzeuge korrekt auszuwählen, verschlechtert sich erheblich bei mehr als 30-50 konventionell verfügbaren Werkzeugen

Obwohl dies als serverseitiges Werkzeug bereitgestellt wird, können Sie auch Ihre eigene clientseitige Tool-Suchfunktionalität implementieren. Siehe Benutzerdefinierte Tool-Suchimplementierung für Details.

Das Tool-Suchwerkzeug befindet sich derzeit in der öffentlichen Beta.

Um diese Funktion zu nutzen, fügen Sie den "advanced-tool-use-2025-11-20" Beta-Header zu Ihren API-Anfragen hinzu.

Bitte teilen Sie Ihre Erfahrungen mit dem Tool-Suchwerkzeug über unser Feedback-Formular mit.

Plattform- und Modellunterstützung

Plattform	Unterstützte Modelle
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Bei Amazon Bedrock ist die serverseitige Tool-Suche nur über die invoke API verfügbar, nicht über die converse API.

Sie können auch clientseitige Tool-Suche implementieren, indem Sie tool_reference-Blöcke aus Ihrer eigenen Suchimplementierung zurückgeben.

Wie die Tool-Suche funktioniert

Es gibt zwei Tool-Suchvarianten:

Regex (tool_search_tool_regex_20251119): Claude konstruiert Regex-Muster zur Suche nach Werkzeugen
BM25 (tool_search_tool_bm25_20251119): Claude verwendet natürlichsprachliche Abfragen zur Suche nach Werkzeugen

Wenn Sie das Tool-Suchwerkzeug aktivieren:

Sie fügen ein Tool-Suchwerkzeug (z. B. tool_search_tool_regex_20251119 oder tool_search_tool_bm25_20251119) in Ihre Werkzeugliste ein
Sie stellen alle Werkzeugdefinitionen mit defer_loading: true für Werkzeuge bereit, die nicht sofort geladen werden sollten
Claude sieht zunächst nur das Tool-Suchwerkzeug und alle nicht aufgeschobenen Werkzeuge
Wenn Claude zusätzliche Werkzeuge benötigt, sucht er mit einem Tool-Suchwerkzeug
Die API gibt 3-5 der relevantesten tool_reference-Blöcke zurück
Diese Referenzen werden automatisch in vollständige Werkzeugdefinitionen erweitert
Claude wählt aus den entdeckten Werkzeugen aus und ruft sie auf

Dies hält Ihr Kontextfenster effizient, während die hohe Genauigkeit der Werkzeugauswahl erhalten bleibt.

Schnellstart

Hier ist ein einfaches Beispiel mit aufgeschobenen Werkzeugen:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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
            }
        ]
    }'

Werkzeugdefinition

Das Tool-Suchwerkzeug hat zwei Varianten:

JSON

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

JSON

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

Regex-Varianten-Abfrageformat: Python-Regex, NICHT natürliche Sprache

Bei Verwendung von tool_search_tool_regex_20251119 konstruiert Claude Regex-Muster mit der Syntax von Pythons re.search(), nicht natürlichsprachliche Abfragen. Häufige Muster:

"weather" - passt Werkzeugnamen/Beschreibungen, die "weather" enthalten
"get_.*_data" - passt Werkzeuge wie get_user_data, get_weather_data
"database.*query|query.*database" - ODER-Muster für Flexibilität
"(?i)slack" - Suche ohne Berücksichtigung der Groß-/Kleinschreibung

Maximale Abfragelänge: 200 Zeichen

BM25-Varianten-Abfrageformat: Natürliche Sprache

Bei Verwendung von tool_search_tool_bm25_20251119 verwendet Claude natürlichsprachliche Abfragen zur Suche nach Werkzeugen.

Aufgeschobenes Werkzeugladen

Markieren Sie Werkzeuge für bedarfsgerechtes Laden, indem Sie defer_loading: true hinzufügen:

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
}

Wichtige Punkte:

Werkzeuge ohne defer_loading werden sofort in den Kontext geladen
Werkzeuge mit defer_loading: true werden nur geladen, wenn Claude sie durch Suche entdeckt
Das Tool-Suchwerkzeug selbst sollte niemals defer_loading: true haben
Behalten Sie Ihre 3-5 am häufigsten verwendeten Werkzeuge als nicht aufgeschoben für optimale Leistung

Beide Tool-Suchvarianten (regex und bm25) durchsuchen Werkzeugnamen, Beschreibungen, Argumentnamen und Argumentbeschreibungen.

Antwortformat

Wenn Claude das Tool-Suchwerkzeug verwendet, enthält die Antwort neue Blocktypen:

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": {
        "query": "weather"
      }
    },
    {
      "type": "tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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: Zeigt an, dass Claude das Tool-Suchwerkzeug aufruft
tool_result mit tool_reference: Die Suchergebnisse mit Referenzen zu entdeckten Werkzeugen
tool_use: Claude ruft das entdeckte Werkzeug auf

Die tool_reference-Blöcke werden automatisch in vollständige Werkzeugdefinitionen erweitert, bevor sie Claude angezeigt werden. Sie müssen diese Erweiterung nicht selbst durchführen. Dies geschieht automatisch in der API, solange Sie alle übereinstimmenden Werkzeugdefinitionen im tools-Parameter bereitstellen.

MCP-Integration

Das Tool-Suchwerkzeug funktioniert mit MCP-Servern. Fügen Sie den "mcp-client-2025-11-20" Beta-Header zu Ihrer API-Anfrage hinzu, und verwenden Sie dann mcp_tool_set mit default_configs, um MCP-Werkzeuge aufzuschieben:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP-Konfigurationsoptionen:

default_configs.defer_loading: Standard für alle Werkzeuge vom MCP-Server festlegen
configs: Standards für bestimmte Werkzeuge nach Name überschreiben
Kombinieren Sie mehrere MCP-Server mit Tool-Suche für massive Werkzeugbibliotheken

Benutzerdefinierte Tool-Suchimplementierung

Sie können Ihre eigene Tool-Suchlogik implementieren (z. B. mit Embeddings oder semantischer Suche), indem Sie tool_reference-Blöcke aus einem benutzerdefinierten Werkzeug zurückgeben:

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Jedes referenzierte Werkzeug muss eine entsprechende Werkzeugdefinition im Top-Level-tools-Parameter mit defer_loading: true haben. Dieser Ansatz ermöglicht es Ihnen, anspruchsvollere Suchalgorithmen zu verwenden und gleichzeitig die Kompatibilität mit dem Tool-Suchsystem zu wahren.

Ein vollständiges Beispiel mit Embeddings finden Sie in unserem Tool-Suche mit Embeddings Cookbook.

Fehlerbehandlung

Das Tool-Suchwerkzeug ist nicht kompatibel mit Tool-Use-Beispielen. Wenn Sie Beispiele für die Werkzeugnutzung bereitstellen müssen, verwenden Sie Standard-Tool-Aufrufe ohne Tool-Suche.

HTTP-Fehler (400-Status)

Diese Fehler verhindern die Verarbeitung der Anfrage:

Alle Werkzeuge aufgeschoben:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Fehlende Werkzeugdefinition:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Tool-Ergebnis-Fehler (200-Status)

Fehler während der Werkzeugausführung geben eine 200-Antwort mit Fehlerinformationen im Text zurück:

JSON

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Fehlercodes:

too_many_requests: Ratenlimit für Tool-Suchvorgänge überschritten
invalid_pattern: Fehlerhaftes Regex-Muster
pattern_too_long: Muster überschreitet 200-Zeichen-Limit
unavailable: Tool-Suchservice vorübergehend nicht verfügbar

Häufige Fehler

Prompt-Caching

Die Tool-Suche funktioniert mit Prompt-Caching. Fügen Sie cache_control-Haltepunkte hinzu, um mehrteilige Gespräche zu optimieren:

Python

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Add Claude's response to conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Second request with cache breakpoint
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Das System erweitert tool_reference-Blöcke automatisch in der gesamten Gesprächshistorie, sodass Claude entdeckte Werkzeuge in nachfolgenden Durchläufen wiederverwenden kann, ohne erneut zu suchen.

Streaming

Mit aktiviertem Streaming erhalten Sie Tool-Suchereignisse als Teil des Streams:

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 query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause while search executes

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

// Claude continues with discovered tools

Batch-Anfragen

Sie können das Tool-Suchwerkzeug in die Messages Batches API einbeziehen. Tool-Suchvorgänge über die Messages Batches API werden genauso berechnet wie die in regulären Messages API-Anfragen.

Limits und Best Practices

Limits

Maximale Werkzeuge: 10.000 Werkzeuge in Ihrem Katalog
Suchergebnisse: Gibt 3-5 der relevantesten Werkzeuge pro Suche zurück
Musterlänge: Maximale 200 Zeichen für Regex-Muster
Modellunterstützung: Nur Sonnet 4.0+, Opus 4.0+ (kein Haiku)

Wann sollte die Tool-Suche verwendet werden

Gute Anwendungsfälle:

10+ Werkzeuge in Ihrem System verfügbar
Werkzeugdefinitionen verbrauchen >10K Token
Probleme mit der Genauigkeit der Werkzeugauswahl bei großen Werkzeugsätzen
Aufbau von MCP-gestützten Systemen mit mehreren Servern (200+ Werkzeuge)
Werkzeugbibliothek wächst im Laufe der Zeit

Wann könnte traditioneller Tool-Aufruf besser sein:

Weniger als 10 Werkzeuge insgesamt
Alle Werkzeuge werden in jeder Anfrage häufig verwendet
Sehr kleine Werkzeugdefinitionen (<100 Token insgesamt)

Optimierungstipps

Behalten Sie 3-5 der am häufigsten verwendeten Werkzeuge als nicht aufgeschoben
Schreiben Sie klare, aussagekräftige Werkzeugnamen und Beschreibungen
Verwenden Sie semantische Schlüsselwörter in Beschreibungen, die der Art entsprechen, wie Benutzer Aufgaben beschreiben
Fügen Sie einen System-Prompt-Abschnitt hinzu, der verfügbare Werkzeugkategorien beschreibt: "Sie können nach Werkzeugen suchen, um mit Slack, GitHub und Jira zu interagieren"
Überwachen Sie, welche Werkzeuge Claude entdeckt, um Beschreibungen zu verfeinern

Nutzung und Preisgestaltung

Die Nutzung des Tool-Suchwerkzeugs wird im Nutzungsobjekt der Antwort verfolgt:

JSON

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

Aktuelle Preisinformationen finden Sie auf der Preisseite.

Tools

Tool-Suchwerkzeug

Ermöglichen Sie Claude, mit Hunderten oder Tausenden von Werkzeugen zu arbeiten, indem Sie diese dynamisch entdecken und bei Bedarf laden.

Dieser Ansatz löst zwei kritische Herausforderungen, wenn Werkzeugbibliotheken skaliert werden:

Kontexteffizienz: Werkzeugdefinitionen können massive Teile Ihres Kontextfensters verbrauchen (50 Werkzeuge ≈ 10-20K Token), was weniger Platz für tatsächliche Arbeit lässt
Genauigkeit der Werkzeugauswahl: Claudes Fähigkeit, Werkzeuge korrekt auszuwählen, verschlechtert sich erheblich bei mehr als 30-50 konventionell verfügbaren Werkzeugen

Das Tool-Suchwerkzeug befindet sich derzeit in der öffentlichen Beta.

Um diese Funktion zu nutzen, fügen Sie den "advanced-tool-use-2025-11-20" Beta-Header zu Ihren API-Anfragen hinzu.

Bitte teilen Sie Ihre Erfahrungen mit dem Tool-Suchwerkzeug über unser Feedback-Formular mit.

Plattform- und Modellunterstützung

Plattform	Unterstützte Modelle
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Bei Amazon Bedrock ist die serverseitige Tool-Suche nur über die invoke API verfügbar, nicht über die converse API.

Sie können auch clientseitige Tool-Suche implementieren, indem Sie tool_reference-Blöcke aus Ihrer eigenen Suchimplementierung zurückgeben.

Wie die Tool-Suche funktioniert

Es gibt zwei Tool-Suchvarianten:

Regex (tool_search_tool_regex_20251119): Claude konstruiert Regex-Muster zur Suche nach Werkzeugen
BM25 (tool_search_tool_bm25_20251119): Claude verwendet natürlichsprachliche Abfragen zur Suche nach Werkzeugen

Wenn Sie das Tool-Suchwerkzeug aktivieren:

Sie fügen ein Tool-Suchwerkzeug (z. B. tool_search_tool_regex_20251119 oder tool_search_tool_bm25_20251119) in Ihre Werkzeugliste ein
Sie stellen alle Werkzeugdefinitionen mit defer_loading: true für Werkzeuge bereit, die nicht sofort geladen werden sollten
Claude sieht zunächst nur das Tool-Suchwerkzeug und alle nicht aufgeschobenen Werkzeuge
Wenn Claude zusätzliche Werkzeuge benötigt, sucht er mit einem Tool-Suchwerkzeug
Die API gibt 3-5 der relevantesten tool_reference-Blöcke zurück
Diese Referenzen werden automatisch in vollständige Werkzeugdefinitionen erweitert
Claude wählt aus den entdeckten Werkzeugen aus und ruft sie auf

Dies hält Ihr Kontextfenster effizient, während die hohe Genauigkeit der Werkzeugauswahl erhalten bleibt.

Schnellstart

Hier ist ein einfaches Beispiel mit aufgeschobenen Werkzeugen:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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
            }
        ]
    }'

Werkzeugdefinition

Das Tool-Suchwerkzeug hat zwei Varianten:

JSON

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

JSON

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

Regex-Varianten-Abfrageformat: Python-Regex, NICHT natürliche Sprache

Bei Verwendung von tool_search_tool_regex_20251119 konstruiert Claude Regex-Muster mit der Syntax von Pythons re.search(), nicht natürlichsprachliche Abfragen. Häufige Muster:

"weather" - passt Werkzeugnamen/Beschreibungen, die "weather" enthalten
"get_.*_data" - passt Werkzeuge wie get_user_data, get_weather_data
"database.*query|query.*database" - ODER-Muster für Flexibilität
"(?i)slack" - Suche ohne Berücksichtigung der Groß-/Kleinschreibung

Maximale Abfragelänge: 200 Zeichen

BM25-Varianten-Abfrageformat: Natürliche Sprache

Bei Verwendung von tool_search_tool_bm25_20251119 verwendet Claude natürlichsprachliche Abfragen zur Suche nach Werkzeugen.

Aufgeschobenes Werkzeugladen

Markieren Sie Werkzeuge für bedarfsgerechtes Laden, indem Sie defer_loading: true hinzufügen:

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
}

Wichtige Punkte:

Werkzeuge ohne defer_loading werden sofort in den Kontext geladen
Werkzeuge mit defer_loading: true werden nur geladen, wenn Claude sie durch Suche entdeckt
Das Tool-Suchwerkzeug selbst sollte niemals defer_loading: true haben
Behalten Sie Ihre 3-5 am häufigsten verwendeten Werkzeuge als nicht aufgeschoben für optimale Leistung

Beide Tool-Suchvarianten (regex und bm25) durchsuchen Werkzeugnamen, Beschreibungen, Argumentnamen und Argumentbeschreibungen.

Antwortformat

Wenn Claude das Tool-Suchwerkzeug verwendet, enthält die Antwort neue Blocktypen:

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": {
        "query": "weather"
      }
    },
    {
      "type": "tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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: Zeigt an, dass Claude das Tool-Suchwerkzeug aufruft
tool_result mit tool_reference: Die Suchergebnisse mit Referenzen zu entdeckten Werkzeugen
tool_use: Claude ruft das entdeckte Werkzeug auf

MCP-Integration

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP-Konfigurationsoptionen:

default_configs.defer_loading: Standard für alle Werkzeuge vom MCP-Server festlegen
configs: Standards für bestimmte Werkzeuge nach Name überschreiben
Kombinieren Sie mehrere MCP-Server mit Tool-Suche für massive Werkzeugbibliotheken

Benutzerdefinierte Tool-Suchimplementierung

Sie können Ihre eigene Tool-Suchlogik implementieren (z. B. mit Embeddings oder semantischer Suche), indem Sie tool_reference-Blöcke aus einem benutzerdefinierten Werkzeug zurückgeben:

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Ein vollständiges Beispiel mit Embeddings finden Sie in unserem Tool-Suche mit Embeddings Cookbook.

Fehlerbehandlung

Das Tool-Suchwerkzeug ist nicht kompatibel mit Tool-Use-Beispielen. Wenn Sie Beispiele für die Werkzeugnutzung bereitstellen müssen, verwenden Sie Standard-Tool-Aufrufe ohne Tool-Suche.

HTTP-Fehler (400-Status)

Diese Fehler verhindern die Verarbeitung der Anfrage:

Alle Werkzeuge aufgeschoben:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Fehlende Werkzeugdefinition:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Tool-Ergebnis-Fehler (200-Status)

Fehler während der Werkzeugausführung geben eine 200-Antwort mit Fehlerinformationen im Text zurück:

JSON

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Fehlercodes:

too_many_requests: Ratenlimit für Tool-Suchvorgänge überschritten
invalid_pattern: Fehlerhaftes Regex-Muster
pattern_too_long: Muster überschreitet 200-Zeichen-Limit
unavailable: Tool-Suchservice vorübergehend nicht verfügbar

Häufige Fehler

Prompt-Caching

Die Tool-Suche funktioniert mit Prompt-Caching. Fügen Sie cache_control-Haltepunkte hinzu, um mehrteilige Gespräche zu optimieren:

Python

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Add Claude's response to conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Second request with cache breakpoint
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Das System erweitert tool_reference-Blöcke automatisch in der gesamten Gesprächshistorie, sodass Claude entdeckte Werkzeuge in nachfolgenden Durchläufen wiederverwenden kann, ohne erneut zu suchen.

Streaming

Mit aktiviertem Streaming erhalten Sie Tool-Suchereignisse als Teil des Streams:

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 query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause while search executes

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

// Claude continues with discovered tools

Batch-Anfragen

Sie können das Tool-Suchwerkzeug in die Messages Batches API einbeziehen. Tool-Suchvorgänge über die Messages Batches API werden genauso berechnet wie die in regulären Messages API-Anfragen.

Limits und Best Practices

Limits

Maximale Werkzeuge: 10.000 Werkzeuge in Ihrem Katalog
Suchergebnisse: Gibt 3-5 der relevantesten Werkzeuge pro Suche zurück
Musterlänge: Maximale 200 Zeichen für Regex-Muster
Modellunterstützung: Nur Sonnet 4.0+, Opus 4.0+ (kein Haiku)

Wann sollte die Tool-Suche verwendet werden

Gute Anwendungsfälle:

10+ Werkzeuge in Ihrem System verfügbar
Werkzeugdefinitionen verbrauchen >10K Token
Probleme mit der Genauigkeit der Werkzeugauswahl bei großen Werkzeugsätzen
Aufbau von MCP-gestützten Systemen mit mehreren Servern (200+ Werkzeuge)
Werkzeugbibliothek wächst im Laufe der Zeit

Wann könnte traditioneller Tool-Aufruf besser sein:

Weniger als 10 Werkzeuge insgesamt
Alle Werkzeuge werden in jeder Anfrage häufig verwendet
Sehr kleine Werkzeugdefinitionen (<100 Token insgesamt)

Optimierungstipps

Behalten Sie 3-5 der am häufigsten verwendeten Werkzeuge als nicht aufgeschoben
Schreiben Sie klare, aussagekräftige Werkzeugnamen und Beschreibungen
Verwenden Sie semantische Schlüsselwörter in Beschreibungen, die der Art entsprechen, wie Benutzer Aufgaben beschreiben
Fügen Sie einen System-Prompt-Abschnitt hinzu, der verfügbare Werkzeugkategorien beschreibt: "Sie können nach Werkzeugen suchen, um mit Slack, GitHub und Jira zu interagieren"
Überwachen Sie, welche Werkzeuge Claude entdeckt, um Beschreibungen zu verfeinern

Nutzung und Preisgestaltung

Die Nutzung des Tool-Suchwerkzeugs wird im Nutzungsobjekt der Antwort verfolgt:

JSON

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

Aktuelle Preisinformationen finden Sie auf der Preisseite.

Plattform- und Modellunterstützung

Wie die Tool-Suche funktioniert

Schnellstart

Werkzeugdefinition

Aufgeschobenes Werkzeugladen

Antwortformat

Die Antwort verstehen

MCP-Integration

Benutzerdefinierte Tool-Suchimplementierung

Fehlerbehandlung

HTTP-Fehler (400-Status)

Tool-Ergebnis-Fehler (200-Status)

Häufige Fehler

400-Fehler: Alle Werkzeuge sind aufgeschoben

400-Fehler: Fehlende Werkzeugdefinition

Claude findet erwartete Werkzeuge nicht

Prompt-Caching

Streaming

Batch-Anfragen

Limits und Best Practices

Limits

Wann sollte die Tool-Suche verwendet werden

Optimierungstipps

Nutzung und Preisgestaltung

Plattform- und Modellunterstützung

Wie die Tool-Suche funktioniert

Schnellstart

Werkzeugdefinition

Aufgeschobenes Werkzeugladen

Antwortformat

Die Antwort verstehen

MCP-Integration

Benutzerdefinierte Tool-Suchimplementierung

Fehlerbehandlung

HTTP-Fehler (400-Status)

Tool-Ergebnis-Fehler (200-Status)

Häufige Fehler

400-Fehler: Alle Werkzeuge sind aufgeschoben

400-Fehler: Fehlende Werkzeugdefinition

Claude findet erwartete Werkzeuge nicht

Prompt-Caching

Streaming

Batch-Anfragen

Limits und Best Practices

Limits

Wann sollte die Tool-Suche verwendet werden

Optimierungstipps

Nutzung und Preisgestaltung