Tool-Search-Tool

Das Tool-Search-Tool ermöglicht es Claude, mit Hunderten oder Tausenden von Tools zu arbeiten, indem es sie bei Bedarf entdeckt und lädt. Anstatt alle Tool-Definitionen von vornherein in das 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 Laden jeder Tool-Definition von vornherein verursacht zwei Probleme, wenn eine Tool-Bibliothek wächst:

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

Tool-Search ist auf der Claude API allgemein verfügbar. Unterstützte Modelle findest du unter Modellkompatibilität.

Tool-Search läuft als serverseitiges Tool, aber du kannst auch deine eigene clientseitige Tool-Suche implementieren. Siehe Benutzerdefinierte Tool-Search-Implementierung für Details.



Modellkompatibilität

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

Claude Opus 4.1 und frühere Modelle unterstützen das Tool-Search-Tool nicht.



Wie Tool-Search funktioniert

Es gibt zwei Tool-Search-Varianten:

• Regex (tool_search_tool_regex_20251119): Claude konstruiert Regex-Muster, um nach Tools zu suchen.
• BM25 (tool_search_tool_bm25_20251119): Claude verwendet natürlichsprachliche Abfragen, 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 von vornherein geladen werden sollen. Mindestens ein Tool, normalerweise das Tool-Search-Tool selbst, muss nicht-deferred bleiben.
3. Anfänglich enthält Claudes Kontext nur das Tool-Search-Tool und alle nicht-deferred Tools.
4. Wenn Claude zusätzliche Tools benötigt, sucht es mit einem Tool-Search-Tool.
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).
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 deferred Tools:

client = anthropic.Anthropic()

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

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 in Tool-Aufrufe verarbeiten beschrieben. Antwortformat zeigt die Blöcke, die du zurückbekommst, und was du als Nächstes senden musst.



Tool-Definition

Das Tool-Search-Tool hat zwei Varianten:

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

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



Deferred Tool Loading

Markiere Tools für bedarfsgesteuertes Laden, indem du defer_loading: true hinzufügst:

{
  "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 die vollständige Definition jedes Tools im tools-Array bei jeder Anfrage, einschließlich der deferred Tools. 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 durch die Suche entdeckt.
• Setze niemals defer_loading: true auf dem Tool-Search-Tool selbst.
• Halte deine 3–5 am häufigsten verwendeten Tools nicht-deferred, damit Claude sie aufrufen kann, ohne zuerst zu suchen.

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

Intern schließt die API deferred Tools aus dem System-Prompt-Präfix aus. Wenn Claude ein deferred Tool durch Tool-Search entdeckt, fügt die API einen tool_reference-Block inline in die Konversation ein und erweitert ihn dann zur vollständigen Tool-Definition, bevor er an Claude übergeben wird. Das Präfix bleibt unberührt, sodass Prompt-Caching erhalten bleibt. Die Grammatik für den Strict Mode (die Regeln, die die Tool-Aufruf-Ausgabe auf deine Schemas beschränken) wird aus dem vollständigen Toolset aufgebaut, sodass defer_loading und Strict Mode ohne Grammatik-Neukompilierung zusammenwirken.



Antwortformat

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

{
  "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"
      }
    },
    {
      "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 Anthropics Servern. Gib niemals ein tool_result für dessen srvtoolu_...-ID zurück.
• 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 handhaben, solange du alle passenden Tool-Definitionen im tools-Parameter bereitstellst.



Die Konversation fortsetzen

Übergib 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 deferred 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, die nichts findet, gibt ein tool_search_tool_search_result mit einem leeren tool_references-Array zurück, keinen Fehler.



MCP-Integration

Wenn deine Tools von MCP-Servern über den MCP-Connector kommen, setzt du defer_loading nicht auf 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.



Benutzerdefinierte Tool-Search-Implementierung

Du kannst deine eigene Tool-Such-Logik 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:

{
  "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 Top-Level-tools-Parameter haben, normalerweise mit defer_loading: true. Dies ermöglicht dir, Suchmethoden zu verwenden, die die eingebauten Varianten nicht bieten, wie z. B. Embedding-basiertes Retrieval, und die API erweitert die zurückgegebenen tool_reference-Blöcke auf dieselbe Weise.

Ein vollständiges Beispiel mit Embeddings findest du im Rezept Tool-Suche mit Embeddings.



Fehlerbehandlung



HTTP-Fehler (Status 400)

Diese Fehler verhindern, dass die API die Anfrage verarbeitet:

Alle Tools deferred:

{
  "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:

{
  "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-Such-Operation während der Ausführung fehlschlägt, gibt die API eine 200-Antwort mit dem Fehler im Body zurück:

{
  "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 200-Zeichen-Limit
• unavailable: Die Suche konnte nicht ausgeführt werden, zum Beispiel weil sie ein Timeout hatte oder der Dienst nicht verfügbar war
• too_many_requests: Ratenlimit für Tool-Such-Operationen überschritten
• execution_time_exceeded: Die Suche hat ihr Ausführungszeitlimit überschritten



Häufige Fehler



Prompt-Caching

Wie defer_loading Prompt-Caching erhält, erfährst du unter Tool-Nutzung mit Prompt-Caching.

Ein Tool mit defer_loading: true kann nicht gleichzeitig cache_control tragen: Die API gibt einen 400 zurück. Setze den Cache-Breakpoint auf ein nicht-deferred Tool.



Streaming

Mit aktiviertem Streaming erhältst du Tool-Search-Events 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 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 die Messages Batches API einbinden.



Limits und Best Practices



Limits

• Maximale deferred Tools: 10.000 Tools mit defer_loading: true pro Anfrage
• Suchergebnisse: Jede Suche gibt standardmäßig bis zu 5 passende Tools zurück
• Muster- und Abfragelänge: maximal 200 Zeichen für Regex-Muster und 500 Zeichen für BM25-Abfragen
• Modellunterstützung: siehe Modellkompatibilität



Wann du Tool-Search verwenden solltest

Verwende Tool-Search, wenn einer der folgenden Punkte zutrifft:

• Du hast 10 oder mehr Tools verfügbar.
• 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 mit der Zeit.

Standardmäßige Tool-Aufrufe ohne Tool-Search 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

• Halte deine 3–5 am häufigsten verwendeten Tools nicht-deferred.
• Schreibe klare, beschreibende Tool-Namen und Beschreibungen.
• Verwende konsistentes Namespacing in Tool-Namen: Präfixe nach Dienst oder Ressource (zum Beispiel github_, slack_), damit eine Suche die gesamte Gruppe findet.
• Verwende Schlüsselwörter in Beschreibungen, die dazu passen, wie Benutzer Aufgaben beschreiben.
• Füge einen System-Prompt-Abschnitt hinzu, der verfügbare Tool-Kategorien beschreibt: „Du kannst nach Tools suchen, um mit Slack, GitHub und Jira zu interagieren."
• Beobachte, welche Tools Claude entdeckt, um deine Beschreibungen zu verfeinern.



Nutzung

Tool-Search wird nicht als separates Server-Tool abgerechnet. Das usage.server_tool_use-Objekt der Antwort hat kein Tool-Search-Feld, 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