Tool-Search-Tool

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.

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.

Modellkompatibilität

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

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:

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 unter 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 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.

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 (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:

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

{
  "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-Suche mit Embeddings.

Fehlerbehandlung

HTTP-Fehler (Status 400)

Diese Fehler verhindern, dass die API die Anfrage verarbeitet:

Alle Tools zurückgestellt:

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

Häufige Fehler

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

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

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

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

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