Tool-Suchwerkzeug

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 Probleme, die sich schnell verschärfen, wenn Werkzeugbibliotheken skaliert werden:

• Kontextüberlauf: Werkzeugdefinitionen verbrauchen schnell Ihr Kontextbudget. Ein typisches Multi-Server-Setup (GitHub, Slack, Sentry, Grafana, Splunk) kann ~55k Token in Definitionen verbrauchen, bevor Claude überhaupt etwas leistet. Die Tool-Suche reduziert dies typischerweise um über 85%, indem nur die 3–5 Werkzeuge geladen werden, die Claude tatsächlich benötigt.
• Genauigkeit der Werkzeugauswahl: Claudes Fähigkeit, das richtige Werkzeug auszuwählen, verschlechtert sich erheblich, wenn Sie über 30–50 verfügbare Werkzeuge hinausgehen. Durch die Bereitstellung einer fokussierten Menge relevanter Werkzeuge bei Bedarf behält die Tool-Suche die Auswahlgenauigkeit hoch, auch über Tausende von Werkzeugen hinweg.

Obwohl dies als serverseitiges Werkzeug bereitgestellt wird, können Sie auch Ihre eigene clientseitige Tool-Suchfunktionalität implementieren. Weitere Informationen finden Sie unter Custom tool search implementation.

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

• Regex (tool_search_tool_regex_20251119): Claude konstruiert Regex-Muster, um nach Werkzeugen zu suchen
• BM25 (tool_search_tool_bm25_20251119): Claude verwendet natürlichsprachliche Abfragen, um nach Werkzeugen zu suchen

Wenn Sie das Tool-Suchwerkzeug aktivieren:

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

Dies hält Ihr Kontextfenster effizient, während eine hohe Werkzeugauswahlgenauigkeit beibehalten wird.

Schnellstart

Hier ist ein einfaches Beispiel mit aufgeschobenen Werkzeugen:

client = anthropic.Anthropic()

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

Werkzeugdefinition

Das Tool-Suchwerkzeug 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"
}

Aufgeschobenes Werkzeugladen

Markieren Sie Werkzeuge für On-Demand-Laden, indem Sie defer_loading: true hinzufügen:

{
  "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-Such-Varianten (regex und bm25) durchsuchen Werkzeugnamen, Beschreibungen, Argumentnamen und Argumentbeschreibungen.

Wie Aufschub intern funktioniert: Aufgeschobene Werkzeuge sind nicht im System-Prompt-Präfix enthalten. Wenn das Modell ein aufgeschobenes Werkzeug durch Tool-Suche entdeckt, wird die Werkzeugdefinition inline als tool_reference-Block in der Konversation angehängt. Das Präfix bleibt unverändert, sodass Prompt-Caching erhalten bleibt. Die Grammatik für den strikten Modus wird aus dem vollständigen Werkzeugsatz erstellt, sodass defer_loading und der strikte Modus ohne Grammatik-Neukompilierung zusammengesetzt werden.

Antwortformat

Wenn Claude das Tool-Suchwerkzeug verwendet, enthält die Antwort neue 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": {
        "query": "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"
}

Verständnis der Antwort

• server_tool_use: Zeigt an, dass Claude das Tool-Suchwerkzeug aufruft
• tool_search_tool_result: Enthält die Suchergebnisse mit einem verschachtelten tool_search_tool_search_result-Objekt
• tool_references: Array von tool_reference-Objekten, die auf entdeckte Werkzeuge verweisen
• 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

Informationen zum Konfigurieren von mcp_toolset mit defer_loading finden Sie unter MCP connector.

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. Wenn Claude Ihr benutzerdefiniertes Suchwerkzeug aufruft, geben Sie 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 Werkzeug muss eine entsprechende Werkzeugdefinition im Top-Level-tools-Parameter mit defer_loading: true haben. Dieser Ansatz ermöglicht es Ihnen, ausgefeilteren Suchalgorithmen zu verwenden und gleichzeitig die Kompatibilität mit dem Tool-Suchsystem zu bewahren.

Ein vollständiges Beispiel mit Embeddings finden Sie im tool search with embeddings cookbook.

Fehlerbehandlung

HTTP-Fehler (400-Status)

Diese Fehler verhindern, dass die Anfrage verarbeitet wird:

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

Werkzeug-Ergebnis-Fehler (200-Status)

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

{
  "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: Malformed Regex-Muster
• pattern_too_long: Muster überschreitet 200-Zeichen-Limit
• unavailable: Tool-Suchservice vorübergehend nicht verfügbar

Häufige Fehler

Prompt-Caching

Informationen dazu, wie defer_loading Prompt-Caching bewahrt, finden Sie unter Tool use with prompt caching.

Das System erweitert tool_reference-Blöcke automatisch in der gesamten Konversationshistorie, sodass Claude entdeckte Werkzeuge in nachfolgenden Turns wiederverwenden kann, ohne erneut zu suchen.

Streaming

Mit aktiviertem Streaming erhalten Sie Tool-Such-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 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_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

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.

Datenspeicherung

Die serverseitige Tool-Suche (tool_search-Werkzeug) indiziert und speichert Werkzeugkatalogdaten (Werkzeugnamen, Beschreibungen und Argument-Metadaten) über die unmittelbare API-Antwort hinaus; diese Katalogdaten werden gemäß der Standard-Aufbewahrungsrichtlinie von Anthropic beibehalten. Benutzerdefinierte clientseitige Tool-Suchimplementierungen, die die Standard-Messages API verwenden, sind vollständig ZDR-berechtigt.

Informationen zur ZDR-Berechtigung über alle Funktionen hinweg finden Sie unter API and data retention.

Limits und Best Practices

Limits

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

Wann Tool-Suche verwendet werden sollte

Gute Anwendungsfälle:

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

Wann traditioneller Werkzeugaufruf besser sein könnte:

• 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 am häufigsten verwendete Werkzeuge als nicht aufgeschoben
• Schreiben Sie klare, aussagekräftige Werkzeugnamen und Beschreibungen
• Verwenden Sie konsistente Namensgebung in Werkzeugnamen: Präfix nach Service oder Ressource (z. B. github_, slack_), damit Suchabfragen natürlich die richtige Werkzeuggruppe anzeigen
• Verwenden Sie semantische Schlüsselwörter in Beschreibungen, die damit übereinstimmen, 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

Verwendung

Die Verwendung des Tool-Suchwerkzeugs wird im Antwort-Nutzungsobjekt verfolgt:

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

Nächste Schritte