Tool Search & Deferred Loading
- Das eine verstehen, das fast alle bei defer_loading falsch verstehen — es macht Ihre Anfrage nicht kleiner
- Zwischen den Suchvarianten Regex und BM25 wählen und die Obergrenze der Abfragelänge jeder Variante kennen
- Das Block-Trio server_tool_use / tool_search_tool_result / tool_reference lesen und genau wissen, was zurückzuspiegeln ist
- Die fünf Anfrageformen vermeiden, die einen 400 liefern, einschließlich des cache_control-Konflikts
- Deferred Loading in ein MCP-Connector-Toolset einbinden und die eingebaute Suche durch eigene Embeddings ersetzen
Die zwei Probleme, und warum nur eines mit Geld zu tun hat
Alle Tool-Definitionen vorab zu laden bricht auf zwei getrennte Arten, wenn ein Katalog wächst.
Die erste ist die offensichtliche. Das eigene Beispiel von Anthropic: Ein MCP-Setup mit fünf Servern — GitHub, Slack, Sentry, Grafana, Splunk — verbrennt etwa 55k Tokens für Tool-Definitionen, bevor Claude überhaupt irgendeine Arbeit tut. Das ist eine Steuer, die Sie in jedem Turn der Konversation zahlen.
Die zweite ist die, die Ihre Architektur tatsächlich verändert: Die Genauigkeit der Tool-Auswahl sinkt, sobald mehr als 30–50 Tools verfügbar sind. Darüber hinaus bedeuten mehr Tools nicht mehr Fähigkeit — es bedeutet ein Modell, das aus einer überfüllten Speisekarte wählt. Deferred Loading löst das Kostenproblem und das Genauigkeitsproblem mit demselben Zug, weil das Modell nur die 3–5 Tools sieht, die für die aktuelle Anfrage relevant sind. Anthropic beziffert die Kontextreduktion bei diesem Multiserver-Setup auf über 85 Prozent.
Die Wirtschaftlichkeit und die veröffentlichten Genauigkeitsdeltas behandelt AILmanac in MCP-Token-Kosten. Diese Seite handelt von der Verdrahtung.
Das mentale Modell, das Leute falsch haben
Hier ist das Missverständnis, das man korrigieren sollte, bevor man Code schreibt:
defer_loadingreduziert nicht, was Sie senden. Sie legen weiterhin die vollständige Definition jedes Tools — Namen, Beschreibungen, vollständigesinput_schema— in dastools-Array jeder einzelnen Anfrage, auch die zurückgestellten.
Ihr HTTP-Request-Body schrumpft nicht. Ihre Upload-Bandbreite ändert sich nicht. Die API braucht diese Definitionen serverseitig, um die Suche auszuführen und die gefundenen Referenzen zu expandieren.
Was sich ändert, ist, was ins Kontextfenster gelangt und damit, wofür Sie bezahlen. Zurückgestellte Definitionen sind aus dem System-Prompt-Präfix ausgeschlossen. Entdeckt Claude eine, hängt die API einen tool_reference-Block inline an die Konversation und expandiert ihn zur vollständigen Definition, bevor das Modell sie sieht.
Dieses Detail des Inline-Anhängens ist das zweite nicht offensichtliche: Weil die Expansion in der Konversation stattfindet und nicht im Präfix, wird das gecachte Präfix nie invalidiert. Deferred Loading und Prompt Caching lassen sich kombinieren. Ebenso Strict Tool Use — die Grammatik, die die Tool-Call-Ausgabe einschränkt, wird aus dem vollständigen Toolset gebaut, es wird also nichts neu kompiliert, wenn mitten in der Konversation ein Tool eintrifft.
Einschalten
- Wählen Sie eine Variante: tool_search_tool_regex_20251119 oder tool_search_tool_bm25_20251119. Es ist ein Server-Tool — es läuft auf der Infrastruktur von Anthropic und braucht keinen Beta-Header.
- Pro Tool-Definition, neben name / description / input_schema. Das ist das Flag, das eine Definition aus dem Präfix heraushält.
- Alles, was bei den meisten Anfragen aufgerufen wird, sollte vorab geladen werden. Einen Such-Roundtrip zu zahlen, um ein Tool zu erreichen, das Sie immer brauchen, ist ein schlechter Tausch. Mindestens ein Tool MUSS nicht zurückgestellt bleiben — normalerweise das Such-Tool selbst.
- Auch die zurückgestellten, und auch bei Folge-Turns nach einem tool_result. Lassen Sie eine weg, wird ein tool_reference, der darauf zeigt, zu einem 400.
- Reichen Sie bei der nächsten Anfrage den Inhalt des Assistenten unverändert durch — einschließlich server_tool_use und tool_search_tool_result. Die API expandiert Referenzen über die gesamte Historie erneut, sodass Claude entdeckte Tools in späteren Turns wiederverwendet, ohne erneut zu suchen.
Minimale funktionierende Anfrage — ein Such-Tool, zwei zurückgestellte Tools
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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
}
]
}'Beachten Sie, was das Such-Tool im Präfix kostet: nichts außer seinem eigenen Eintrag. Die beiden zurückgestellten Definitionen stehen im Body, aber nicht im Kontext.
Regex oder BM25
Beide Varianten durchsuchen dieselben vier Felder — Tool-Namen, Beschreibungen, Argumentnamen und Argumentbeschreibungen — und beide sind bei jedem Modell verfügbar, das das Feature unterstützt. Sie unterscheiden sich nur darin, was Claude in die Abfrage schreibt.
tool_search_tool_regex_20251119 | tool_search_tool_bm25_20251119 | |
|---|---|---|
| Claude schreibt | Python-re.search()-Muster | Abfragen in natürlicher Sprache |
| Eingabefeld | pattern | query |
| Maximale Länge | 200 Zeichen | 500 Zeichen |
| Abgleich | Groß-/Kleinschreibung egal | BM25-Ranking |
| Gut, wenn | Ihre Namen Namespaces haben (github_, slack_) | Ihre Beschreibungen wie Fließtext lesen |
Die Regex-Variante ist die, die man falsch konfiguriert, weil der Name eine Stichwortsuche nahelegt und sie keine ist. Claude schreibt echte Muster: "weather", "get_.*_data", "database.*query|query.*database". Findet das Modell ein erwartetes Tool nicht, testen Sie das Muster selbst, bevor Sie dem Modell die Schuld geben:
Einen fehlgeschlagenen Regex-Treffer lokal reproduzieren
import re # Claude writes broad patterns, e.g. ".*weather.*" — not exact names. # Search the same four fields the API searches. haystacks = ["get_weather", "Get the weather at a specific location", "location", "unit"] print(any(re.search(r"weather", h, re.IGNORECASE) for h in haystacks))
Die praktische Lösung für einen verpassten Treffer ist fast nie ein cleveres Muster — es sind Schlüsselwörter in der Beschreibung. Schreiben Sie die Wörter hinein, die Ihre Nutzer verwenden würden. Geben Sie Ihren Tool-Namen einen Namespace pro Dienst, damit ein Muster eine ganze Gruppe erfasst.
Die Antwort lesen
Eine erfolgreiche Suche erzeugt im Assistant-Turn drei neue Blocktypen, in dieser Reihenfolge:
{
"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": "tool_use",
"id": "toolu_01XYZ789",
"name": "get_weather",
"input": { "location": "San Francisco", "unit": "fahrenheit" }
}
],
"stop_reason": "tool_use"
}
Drei Regeln für den Umgang damit:
- Geben Sie nie ein
tool_resultfür die IDsrvtoolu_...zurück. Die Suche lief bereits auf den Servern von Anthropic. Antworten Sie darauf, lehnt die API die Anfrage ab. Ihrtool_resultgeht nur an die IDtoolu_...— ab da gewöhnliche Tool-Nutzung. - Expandieren Sie
tool_reference-Blöcke nie selbst. Das tut die API, solange die passende Definition intoolsvorhanden ist. - Lassen Sie
tool_search_tool_resultunverändert in der Historie. So erfahren spätere Turns, welche Tools schon entdeckt sind.
Eine Suche ohne Treffer ist kein Fehler — Sie erhalten ein tool_search_tool_search_result mit leerem tool_references-Array, und Claude entscheidet, was als Nächstes geschieht.
Ein stilles Detail zu limit: Er steht standardmäßig auf 5 Ergebnisse, aber Claude kann in seiner eigenen Sucheingabe alles von 1 bis 10.000 setzen. Sie steuern ihn nicht direkt. Wenn Sie eine harte Obergrenze dafür brauchen, wie viele Definitionen hereinfluten können, ist das ein Argument für die benutzerdefinierte Implementierung unten.
Die fünf 400er
Vier davon sind Fehler der Anfrageform, die vor jeder Inferenz auftreten, und einer ist der Konflikt, den niemand erwartet.
- „At least one tool must have defer_loading=false. All tools cannot be deferred.“ Die übliche Ursache ist eine Schleife, die defer_loading: true über das ganze Array stempelt, das Such-Tool eingeschlossen. Stellen Sie das Such-Tool nie zurück.
- „Tool reference 'unknown_tool' not found in available tools.“ Verursacht dadurch, dass zurückgestellte Definitionen aus Folgeanfragen herausgekürzt werden, um Bytes zu sparen. Senden Sie das vollständige Array in jedem Turn.
- Ein zurückgestelltes Tool kann keinen Cache-Breakpoint tragen — die API liefert einen 400. Setzen Sie den Breakpoint stattdessen auf ein nicht zurückgestelltes Tool. Das ist der, der Teams trifft, die ihr Caching schon abgestimmt hatten.
- Die Toolsets für Computer Use und Browser Use (computer_toolset_20260801, browser_toolset_20260801) nehmen defer_loading pro Mitglieds-Tool im configs-Objekt des Eintrags. Es am Eintrag selbst zu setzen wird abgelehnt.
- Weil ein Toolset als Einheit zurückstellt und expandiert, muss defer_loading bei jedem aktivierten Mitglied denselben Wert ergeben. Entdecken Sie das Toolset, werden alle aktivierten Mitglieder auf einmal geladen — es gibt keine teilweise Expansion.
Suchfehler während der Ausführung sind anders: Sie kommen mit HTTP 200 zurück, mit dem Fehler in einem Objekt tool_search_tool_result_error.
error_code | Was passiert ist |
|---|---|
invalid_tool_input | Fehlerhafter Regex oder ein Muster über dem 200-Zeichen-Limit |
unavailable | Die Suche konnte nicht laufen — Timeout oder Dienst nicht verfügbar |
too_many_requests | Rate Limit speziell für Tool-Search-Operationen |
execution_time_exceeded | Die Suche hat ihr Ausführungszeitlimit überschritten |
Behandeln Sie diese als behebbar: Die Konversation ist intakt, und der ehrliche Zug ist meist, Claude mit einem anderen Muster erneut versuchen zu lassen, statt den ganzen Turn scheitern zu lassen. Die umgebende Retry-Richtlinie siehe Fehler & Rate Limits.
Prompt Caching
Die Schlagzeile ist gut: Zurückgestellte Definitionen liegen außerhalb des gecachten Präfix, das Hinzufügen und Entdecken von Tools mitten in der Konversation invalidiert es also nicht. Die Präfix-Regeln siehe Prompt Caching, und Cache diagnostics, wenn Sie einen Treffer belegen müssen.
Die Falle ist die oben genannte — defer_loading: true und cache_control schließen sich an einem einzelnen Tool gegenseitig aus. Wenn Ihr Breakpoint derzeit am letzten Tool eines langen Arrays sitzt und Sie dieses Array dann zurückstellen, sind Sie stillschweigend von „gecacht“ zu „400“ gewechselt. Verankern Sie den Breakpoint an einem Tool, das Sie ohnehin immer geladen halten wollten.
MCP-Connector: am Toolset setzen, nicht am Tool
Wenn Tools über den MCP-Connector von Remote-Servern eintreffen, fassen Sie einzelne Definitionen nicht an — sie gehören Ihnen nicht. Konfigurieren Sie es am Eintrag mcp_toolset: einmal für den ganzen Server über default_config oder pro Tool in configs.
Einen ganzen MCP-Server zurückstellen, bis auf das eine Tool, das Sie immer brauchen
{
"type": "mcp_toolset",
"mcp_server_name": "observability",
"default_config": { "defer_loading": true },
"configs": {
"search_events": { "defer_loading": false }
}
}Das ist die Form, die sich in der Praxis am schnellsten auszahlt: Mehrere Server zu aggregieren ist genau die Situation mit über 200 Tools, für die das Feature existiert, und fast immer gibt es ein oder zwei Einstiegs-Tools, die es wert sind, warm gehalten zu werden.
Die Suche durch eine eigene ersetzen
Beide eingebauten Varianten sind lexikalisch. Wenn Ihre Tools besser nach Bedeutung als nach Wortlaut zu finden sind, implementieren Sie die Suche selbst: Definieren Sie ein gewöhnliches benutzerdefiniertes Tool und geben Sie tool_reference-Blöcke in einem normalen tool_result zurück.
Ein clientseitiges Suchergebnis, das die API expandiert
{
"type": "tool_result",
"tool_use_id": "toolu_your_tool_id",
"content": [
{ "type": "tool_reference", "tool_name": "discovered_tool_name" }
]
}Jeder Name, den Sie referenzieren, braucht weiterhin seine vollständige Definition im tools-Array der obersten Ebene, normalerweise mit defer_loading: true. Der Expansionspfad ist identisch — Sie haben nur das Retrieval ausgetauscht. Beachten Sie den Formatunterschied: tool_search_tool_result ist die serverseitige Form, intern zu den eingebauten Varianten. Ihr benutzerdefiniertes Tool gibt die oben gezeigte Standardform tool_result zurück. Anthropic veröffentlicht ein durchgespieltes Embeddings-Rezept.
Das ist auch Ihr Notausgang für das limit-Problem: Ihre eigene Suche entscheidet, wie viele Referenzen zurückkommen.
Wann man es weglässt
Deferred Loading bringt nichts — und kostet einen Such-Roundtrip —, wenn die Prämisse nicht zutrifft. Greifen Sie danach, wenn irgendeines davon zutrifft:
- 10 oder mehr verfügbare Tools
- Tool-Definitionen über etwa 10k Tokens
- Auswahlgenauigkeit sinkt sichtbar, wenn der Katalog wächst
- mehrere aggregierte MCP-Server (über 200 Tools)
- eine Tool-Bibliothek, die weiter wächst
Bleiben Sie beim einfachen Tool Calling, wenn Sie weniger als 10 Tools haben, oder jedes Tool bei jeder Anfrage genutzt wird, oder der gesamte Katalog unter etwa 100 Tokens liegt. Und beachten Sie die Abrechnungsform: Tool Search wird nicht als separates Server-Tool bemessen. Es gibt kein Tool-Search-Feld in usage.server_tool_use. Die einzigen Tokens, die es kostet, sind die Definitionen, die es in den Kontext zieht, bepreist wie jede andere Tool-Definition.
Die harten Obergrenzen, für die Kapazitätsplanung: 10.000 zurückgestellte Tools pro Anfrage, 200-Zeichen-Regex-Muster, 500-Zeichen-BM25-Abfragen.
Plattformhinweise
Zwei Deployment-Fußnoten, die leicht einen Tag kosten. Auf Amazon Bedrock funktioniert serverseitiges Tool Search nur über die InvokeModel API — nicht über die Converse API. Auf Claude Platform on AWS verhält es sich genau wie in der Claude API, weil dieser Pfad die Messages API direkt nutzt und keine Aufteilung in InvokeModel/Converse hat. Claude Opus 4.1 und früher unterstützen das Feature überhaupt nicht.
Prüfen Sie sich selbst
0/6Quellen & weiterführende Literatur
- Tool search tool — Claude Platform docs — die zwei Varianten und ihre Versionsstrings, die Semantik von
defer_loading, die Zahl von ~55k Tokens beim Multiserver-Setup und die 85-Prozent-Reduktion, die Genauigkeitsklippe bei 30–50 Tools, die Formen der Antwortblöcke, alle fünf 400er, die viererror_code-Werte, die Obergrenze von 10.000 Tools, der Bedrock-InvokeModel-Hinweis und die Modell-Support-Tabelle. - Tool use with prompt caching — Claude Platform docs — was einen Cache von Tool-Definitionen invalidiert und warum die zurückgestellte Menge außerhalb des Präfix liegt.
- MCP connector — Claude Platform docs — Form von
mcp_toolset,default_configundconfigspro Tool. - Tool reference — Claude Platform docs — Client-Toolsets und das
configs-Format, das die Computer-/Browser-Toolsets verlangen. - Tool search with embeddings — Anthropic cookbook — eine vollständige benutzerdefinierte, semantische Implementierung, die
tool_reference-Blöcke zurückgibt. - Introducing advanced tool use on the Claude Developer Platform — Anthropic Engineering, der Launch-Beitrag hinter den veröffentlichten Token- und Genauigkeitszahlen.
- Effective context engineering for AI agents — das Just-in-time-Retrieval-Prinzip, dessen Instanz Deferred Loading ist.
- Verwandt auf AILmanac: Tool Use / Function Calling · Programmatic Tool Calling · MCP · MCP-Token-Kosten · Prompt Caching · Cache diagnostics
Weiter
- Programmatic Tool Calling — die andere Hälfte fortgeschrittener Tool-Nutzung: Die Suche findet das richtige Tool, Programmatic Calling führt es aus, ohne Ergebnisse durch den Kontext zu schleppen.
- MCP-Token-Kosten — die Wirtschaftlichkeit und die veröffentlichten Genauigkeitsdeltas hinter diesem Feature.
- Memory & Context Editing — was zu tun ist, wenn die Ergebnisse Ihren Kontext füllen, sobald die Definitionen erledigt sind.