Zum Hauptinhalt springen
Die Tool-Suche ermöglicht es Ihrem Agenten, mit Hunderten oder Tausenden von Tools zu arbeiten, indem er sie dynamisch entdeckt und bei Bedarf lädt. Anstatt alle Tool-Definitionen vorab in das Kontextfenster zu laden, durchsucht der Agent Ihren Tool-Katalog und lädt nur die Tools, die er benötigt. Dieser Ansatz löst zwei Herausforderungen, wenn Tool-Bibliotheken skalieren:
  • Kontexteffizienz: Tool-Definitionen können große Teile des Kontextfensters verbrauchen (50 Tools können 10–20 K Token verwenden), was weniger Platz für tatsächliche Arbeit lässt.
  • Genauigkeit der Tool-Auswahl: Die Genauigkeit der Tool-Auswahl verschlechtert sich, wenn mehr als 30–50 Tools gleichzeitig geladen sind.
Die Tool-Suche ist standardmäßig aktiviert. Diese Seite behandelt wie sie funktioniert, wie man sie konfiguriert, und wie man die Tool-Entdeckung optimiert.

​
Wie die Tool-Suche funktioniert

Wenn die Tool-Suche aktiv ist, werden Tool-Definitionen aus dem Kontextfenster zurückgehalten. Der Agent erhält eine Zusammenfassung der verfügbaren Tools und sucht nach relevanten, wenn die Aufgabe eine Fähigkeit erfordert, die nicht bereits geladen ist. Die 3–5 relevantesten Tools werden in den Kontext geladen, wo sie für nachfolgende Durchläufe verfügbar bleiben. Wenn das Gespräch lang genug ist, dass das SDK frühere Nachrichten komprimiert, um Platz freizugeben, können zuvor entdeckte Tools entfernt werden, und der Agent sucht bei Bedarf erneut. Die Tool-Suche fügt beim ersten Mal, wenn Claude ein Tool entdeckt (der Suchschritt), einen zusätzlichen Roundtrip hinzu, aber bei großen Tool-Sets wird dies durch einen kleineren Kontext bei jedem Durchlauf ausgeglichen. Mit weniger als etwa 10 Tools ist das Laden von allem vorab normalerweise schneller. Weitere Informationen zum zugrunde liegenden API-Mechanismus finden Sie unter Tool-Suche in der API.
Die Tool-Suche erfordert Claude Sonnet 4 oder später oder Claude Opus 4 oder später. Haiku-Modelle unterstützen die Tool-Suche nicht.

​
Tool-Suche konfigurieren

Die Tool-Suche ist standardmäßig aktiviert. Sie ist standardmäßig auf Vertex AI deaktiviert, wo sie für Claude Sonnet 4.5 und später sowie Claude Opus 4.5 und später unterstützt wird. Sie ist auch deaktiviert, wenn ANTHROPIC_BASE_URL auf einen Host eines Drittanbieters verweist, da die meisten Proxys tool_reference-Blöcke nicht weiterleiten. Sie können jeden Standard mit der Umgebungsvariablen ENABLE_TOOL_SEARCH überschreiben:
WertVerhalten
(nicht gesetzt)Die Tool-Suche ist aktiviert. Tool-Definitionen werden aufgeschoben und bei Bedarf entdeckt. Fällt auf Vertex AI oder einen ANTHROPIC_BASE_URL eines Drittanbieters auf das Laden vorab zurück.
trueDie Tool-Suche ist immer aktiviert. Das SDK sendet den Beta-Header auch auf Vertex AI und durch Proxys. Anfragen schlagen auf Vertex AI-Modellen früher als Sonnet 4.5 oder Opus 4.5 oder auf Proxys fehl, die tool_reference-Blöcke nicht unterstützen.
autoÜberprüft die kombinierte Token-Anzahl aller Tool-Definitionen gegen das Kontextfenster des Modells. Wenn sie 10 % überschreiten, wird die Tool-Suche aktiviert. Wenn sie unter 10 % liegen, werden alle Tools normal in den Kontext geladen.
auto:NWie auto mit einem benutzerdefinierten Prozentsatz. auto:5 wird aktiviert, wenn Tool-Definitionen 5 % des Kontextfensters überschreiten. Niedrigere Werte werden früher aktiviert.
falseDie Tool-Suche ist deaktiviert. Alle Tool-Definitionen werden bei jedem Durchlauf in den Kontext geladen.
Die Tool-Suche gilt für alle registrierten Tools, unabhängig davon, ob sie von Remote-MCP-Servern oder benutzerdefinierten SDK-MCP-Servern stammen. Bei Verwendung von auto basiert der Schwellenwert auf der kombinierten Größe aller Tool-Definitionen auf allen Servern. Legen Sie den Wert in der env-Option auf query() fest. Dieses Beispiel verbindet sich mit einem Remote-MCP-Server, der viele Tools bereitstellt, genehmigt alle vorab mit einem Platzhalter und verwendet auto:5, sodass die Tool-Suche aktiviert wird, wenn ihre Definitionen 5 % des Kontextfensters überschreiten: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        // Connect to a remote MCP server
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
Das Setzen von ENABLE_TOOL_SEARCH auf "false" deaktiviert die Tool-Suche und lädt alle Tool-Definitionen bei jedem Durchlauf in den Kontext. Dies entfernt den Suchrundruf, was schneller sein kann, wenn der Tool-Satz klein ist (weniger als etwa 10 Tools) und die Definitionen bequem in das Kontextfenster passen.

​
Tool-Entdeckung optimieren

Der Suchmechanismus gleicht Abfragen mit Tool-Namen und Beschreibungen ab. Namen wie search_slack_messages erscheinen für eine breitere Palette von Anfragen als query_slack. Beschreibungen mit spezifischen Schlüsselwörtern („Slack-Nachrichten nach Schlüsselwort, Kanal oder Datumsbereich durchsuchen”) entsprechen mehr Abfragen als generische („Slack abfragen”). Sie können auch einen Systemaufforderungsabschnitt hinzufügen, der verfügbare Tool-Kategorien auflistet. Dies gibt dem Agenten Kontext darüber, welche Arten von Tools verfügbar sind, um danach zu suchen: 
You can search for tools to interact with Slack, GitHub, and Jira.

​
Limits

  • Maximale Tools: 10.000 Tools in Ihrem Katalog
  • Suchergebnisse: Gibt 3–5 relevanteste Tools pro Suche zurück
  • Modellunterstützung: Claude Sonnet 4 und später, Claude Opus 4 und später (kein Haiku)

​
Zugehörige Dokumentation