Tool-Suchwerkzeug

Das Tool-Suchwerkzeug ermöglicht es Claude, mit Hunderten oder Tausenden von Tools zu arbeiten, indem diese dynamisch bei Bedarf entdeckt und geladen werden. Anstatt alle Tool-Definitionen vorab in das Kontextfenster zu laden, durchsucht Claude Ihren Tool-Katalog (einschließlich Tool-Namen, Beschreibungen, Argumentnamen und Argumentbeschreibungen) und lädt nur die benötigten Tools.

Dieser Ansatz löst zwei Probleme, die sich mit zunehmender Skalierung von Tool-Bibliotheken schnell verstärken:

• Kontext-Überflutung: Tool-Definitionen verbrauchen schnell Ihr Kontextbudget. Ein typisches Multi-Server-Setup (GitHub, Slack, Sentry, Grafana, Splunk) kann ~55k Token in Definitionen verbrauchen, bevor Claude eigentliche Arbeit leistet. Die Tool-Suche reduziert dies typischerweise um über 85%, indem nur die 3–5 Tools geladen werden, die Claude für eine bestimmte Anfrage tatsächlich benötigt.
• Genauigkeit der Tool-Auswahl: Claudes Fähigkeit, das richtige Tool korrekt auszuwählen, verschlechtert sich erheblich, sobald mehr als 30–50 verfügbare Tools vorhanden sind. Durch die bedarfsgerechte Bereitstellung eines fokussierten Satzes relevanter Tools hält die Tool-Suche die Auswahlgenauigkeit auch bei Tausenden von Tools hoch.

Obwohl dies als serverseitiges Tool bereitgestellt wird, können Sie auch Ihre eigene clientseitige Tool-Suchfunktionalität implementieren. Weitere Informationen finden Sie unter Benutzerdefinierte Tool-Suchimplementierung.

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 Varianten der Tool-Suche:

• Regex (tool_search_tool_regex_20251119): Claude erstellt Regex-Muster zur Suche nach Tools
• BM25 (tool_search_tool_bm25_20251119): Claude verwendet natürlichsprachliche Abfragen zur Suche nach Tools

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 Tools-Liste ein
2. Sie stellen alle Tool-Definitionen mit defer_loading: true für Tools bereit, die nicht sofort geladen werden sollen
3. Claude sieht zunächst nur das Tool-Suchwerkzeug und alle nicht verzögerten Tools
4. Wenn Claude zusätzliche Tools benötigt, sucht es mit einem Tool-Suchwerkzeug
5. Die API gibt 3–5 der relevantesten tool_reference-Blöcke zurück
6. Diese Referenzen werden automatisch in vollständige Tool-Definitionen erweitert
7. Claude wählt aus den entdeckten Tools aus und ruft sie auf

Dies hält Ihr Kontextfenster effizient und gewährleistet gleichzeitig eine hohe Genauigkeit bei der Tool-Auswahl.

Schnellstart

Hier ist ein einfaches Beispiel mit verzögerten Tools:

Tool-Definition

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

Verzögertes Tool-Laden

Markieren Sie Tools für das bedarfsgesteuerte 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:

• 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
• Das Tool-Suchwerkzeug selbst sollte niemals defer_loading: true haben
• Behalten Sie Ihre 3–5 am häufigsten verwendeten Tools als nicht verzögert für optimale Leistung

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

Wie die Verzögerung intern funktioniert: Verzögerte Tools sind nicht im System-Prompt-Präfix enthalten. Wenn das Modell ein verzögertes Tool durch die Tool-Suche entdeckt, wird die Tool-Definition inline als tool_reference-Block in der Konversation angehängt. Das Präfix bleibt unberührt, sodass das Prompt-Caching erhalten bleibt. Die Grammatik für den strikten Modus wird aus dem vollständigen Toolset aufgebaut, sodass defer_loading und der strikte Modus ohne Grammatik-Neukompilierung zusammenwirken.

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

Die Antwort verstehen

• 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 Tools verweisen
• tool_use: Claude ruft das entdeckte Tool auf

Die tool_reference-Blöcke werden automatisch in vollständige Tool-Definitionen erweitert, bevor sie Claude angezeigt werden. Sie müssen diese Erweiterung nicht selbst handhaben. Sie erfolgt automatisch in der API, solange Sie alle passenden Tool-Definitionen im tools-Parameter angeben.

MCP-Integration

Informationen zur Konfiguration 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 Tool zurückgeben. Wenn Claude Ihr benutzerdefiniertes Suchwerkzeug aufruft, geben Sie ein Standard-tool_result mit tool_reference-Blöcken im Inhalts-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 mit defer_loading: true haben. Dieser Ansatz ermöglicht die Verwendung ausgefeilterer Suchalgorithmen bei gleichzeitiger Kompatibilität mit dem Tool-Suchsystem.

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

Fehlerbehandlung

HTTP-Fehler (Status 400)

Diese Fehler verhindern die Verarbeitung der Anfrage:

Alle Tools verzögert:

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

Fehlende Tool-Definition:

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

Tool-Ergebnisfehler (Status 200)

Fehler während der Tool-Ausfü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-Suchoperationen überschritten
• invalid_pattern: Fehlerhaftes Regex-Muster
• pattern_too_long: Muster überschreitet das Limit von 200 Zeichen
• unavailable: Tool-Suchdienst vorübergehend nicht verfügbar

Häufige Fehler

Prompt-Caching

Informationen dazu, wie defer_loading das Prompt-Caching erhält, finden Sie unter Tool-Nutzung mit Prompt-Caching.

Das System erweitert tool_reference-Blöcke automatisch im gesamten Konversationsverlauf, sodass Claude entdeckte Tools in nachfolgenden Gesprächsrunden wiederverwenden kann, ohne erneut suchen zu müssen.

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

// Suchabfrage wird gestreamt
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause während die Suche ausgeführt wird

// Suchergebnisse werden gestreamt
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 fährt mit den entdeckten Tools fort

Batch-Anfragen

Sie können das Tool-Suchwerkzeug in der Messages Batches API verwenden. Tool-Suchoperationen über die Messages Batches API werden zum gleichen Preis wie in regulären Messages API-Anfragen abgerechnet.

Datenspeicherung

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

Informationen zur ZDR-Berechtigung für alle Funktionen finden Sie unter API und Datenspeicherung.

Limits und Best Practices

Limits

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

Wann die Tool-Suche verwendet werden sollte

Gute Anwendungsfälle:

• 10+ Tools in Ihrem System verfügbar
• Tool-Definitionen verbrauchen >10k Token
• Probleme mit der Tool-Auswahlgenauigkeit bei großen Tool-Sets
• Aufbau von MCP-gestützten Systemen mit mehreren Servern (200+ Tools)
• Tool-Bibliothek wächst im Laufe der Zeit

Wann herkömmliche Tool-Aufrufe besser sein könnten:

• Weniger als 10 Tools insgesamt
• Alle Tools werden bei jeder Anfrage häufig verwendet
• Sehr kleine Tool-Definitionen (<100 Token insgesamt)

Optimierungstipps

• Behalten Sie 3–5 am häufigsten verwendete Tools als nicht verzögert
• Schreiben Sie klare, beschreibende Tool-Namen und -Beschreibungen
• Verwenden Sie konsistente Namensgebung in Tool-Namen: Präfix nach Dienst oder Ressource (z. B. github_, slack_), damit Suchabfragen natürlich die richtige Tool-Gruppe aufzeigen
• 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 Tool-Kategorien beschreibt: "Sie können nach Tools suchen, um mit Slack, GitHub und Jira zu interagieren"
• Überwachen Sie, welche Tools Claude entdeckt, um Beschreibungen zu verfeinern

Nutzung

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

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

Nächste Schritte