Tool-Search-Tool

Das Tool-Search-Tool (Tool-Such-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:

• Kontextaufblä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, nimmt ab, sobald du 30–50 verfügbare Tools überschreitest. Da Tool Search bei Bedarf nur eine fokussierte Menge relevanter Tools lädt, bleibt die Auswahlgenauigkeit selbst bei Tausenden von Tools hoch.

Welche Modelle Tool Search unterstützen, findest du unter Modellkompatibilität.

Tool Search läuft als serverseitiges Tool, aber du kannst auch deine eigene clientseitige Tool-Suche implementieren. Details findest du unter Benutzerdefinierte Tool-Search-Implementierung.



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.



So funktioniert Tool Search

Es gibt zwei Tool-Search-Varianten:

• 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 verzögert bleiben.
3. Anfangs enthält Claudes Kontext nur das Tool-Search-Tool und alle nicht verzögerten 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 verzögerte 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ückerhältst, 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"
}



Verzögertes Laden von Tools

Markiere Tools für das bedarfsgesteuerte 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 bei jeder Anfrage die vollständige Definition jedes Tools im tools-Array, einschließlich der verzögerten. 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.
• Belasse deine 3–5 am häufigsten verwendeten Tools nicht verzögert, 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 am Eintrag selbst; eine Anfrage, die es auf Eintragsebene setzt, wird abgelehnt. Da ein Toolset als Einheit verzögert 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.

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

Intern schließt die API verzögerte Tools aus dem System-Prompt-Präfix aus. Wenn Claude ein verzögertes Tool über Tool Search 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-Modus (die Regeln, die die Tool-Aufruf-Ausgabe auf deine Schemas beschränken) wird aus dem vollständigen Toolset erstellt, sodass defer_loading und der Strict-Modus ohne Neukompilierung der Grammatik 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",
        "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. Belasse 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 Standard-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

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 Benutzernachricht hinzu und sende dasselbe tools-Array: das Such-Tool plus jede verzögerte 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 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.



Benutzerdefinierte Tool-Search-Implementierung

Du kannst deine eigene Tool-Search-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 Standard-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 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.

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



Fehlerbehandlung



HTTP-Fehler (Status 400)

Diese Fehler verhindern, dass die API die Anfrage verarbeitet:

Alle Tools verzögert:

{
  "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-Search-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 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-Search-Operationen überschritten
• execution_time_exceeded: Die Suche hat ihr Ausführungszeitlimit überschritten



Häufige Fehler



Prompt-Caching

Wie defer_loading das 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-Fehler zurück. Setze den Cache-Breakpoint auf ein nicht verzögertes Tool.



Streaming

Bei aktiviertem Streaming erhältst du Tool-Search-Ereignisse 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 Anzahl verzögerter 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



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 im Laufe der Zeit.

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

• Belasse deine 3–5 am häufigsten verwendeten Tools nicht verzögert.
• Schreibe klare, aussagekräftige Tool-Namen und Beschreibungen.
• Verwende konsistente Namensräume in Tool-Namen: Setze ein Präfix nach Dienst oder Ressource (zum Beispiel github_, slack_), damit eine Suche die gesamte Gruppe findet.
• Verwende in Beschreibungen Schlüsselwörter, die der Art entsprechen, wie Benutzer 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

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