Toolsuche in Claude Code: Wie der Agent das benötigte MCP-Tool findet

Wenn Sie mehrere MCP-Server mit Claude Code verbunden haben, kann die Toolsuche die benötigten Tools bei Bedarf laden, ohne vorab alle Definitionen zu laden. Beim Start erhält der Agent die Namen der zurückgestellten Tools und die Anweisungen der Server und durchsucht dann den Katalog nach dem, was er benötigt. So kann er mit einer großen Anzahl von Tools arbeiten: Laut der Dokumentation von Anthropic sinkt die Auswahlgenauigkeit, wenn mehr als 30-50 Tools gleichzeitig geladen sind. Das ist eine allgemeine Orientierung und keine Messung Ihrer Sitzung. Die Toolsuche ist standardmäßig aktiviert, wenn das Modell sie unterstützt; die Plattform, ein Proxy oder Einstellungen können sie jedoch deaktivieren.

Ailoot-Dokumentation: API, Schlüssel und Einrichtung.

Was passiert mit dem Claude-Code-Kontext ohne Toolsuche?#

Jeder verbundene MCP-Server fügt seine Tools der Liste der Dinge hinzu, die der Agent aufrufen kann. Ohne Toolsuche werden ihre Definitionen — Name, Beschreibung und Parameterschema — vorab in den Kontext geladen. Die Server verbinden sich im Hintergrund, wenn eine Sitzung startet. Wird ein Tool von einem Server benötigt, dessen Verbindung noch nicht hergestellt ist, wartet Claude Code mithilfe des internen Tools WaitForMcpServers. Sie können für jede Verbindung separat ermitteln, wie viele Tools und Tokens ein bestimmter Server hinzufügt.

Die offizielle Dokumentation von Anthropic nennt zwei ungefähre Werte (allgemeine Zahlen ohne angegebene Messmethode):

• 50 Tools können 10-20 Tausend Kontext-Tokens belegen;
• die Genauigkeit bei der Auswahl des passenden Tools sinkt, wenn mehr als 30-50 gleichzeitig geladen sind.

So beurteilen Sie anhand der Einstellungen, ob die Toolsuche funktioniert#

Um festzustellen, ob die Toolsuche in der aktuellen Sitzung funktionieren sollte, prüfen Sie folgende Bedingungen:

• welches Modell antwortet — Sonnet/Haiku/Opus 4.5 oder neuer: der Mechanismus ist verfügbar; ein älteres Modell: nicht verfügbar;
• ob ANTHROPIC_BASE_URL auf einen nicht standardmäßigen Host gesetzt ist — in diesem Fall ist der Mechanismus standardmäßig ausgeschaltet, sofern er nicht ausdrücklich über ENABLE_TOOL_SEARCH aktiviert wird;
• den Wert der Variablen ENABLE_TOOL_SEARCH — false deaktiviert den Mechanismus vollständig; auto/auto:N aktiviert ihn erst, wenn die Definitionsmenge einen Schwellenwert erreicht;
• ob CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS gesetzt ist — ohne verwaltete Einstellungen der Organisation hält die Variable die Toolsuche ausgeschaltet, selbst wenn der Benutzer ENABLE_TOOL_SEARCH gesetzt hat;
• ob das Tool ToolSearch über permissions.deny in den Einstellungen blockiert wird — eine solche Einschränkung deaktiviert die Suche;
• welche Plattform verwendet wird — der Mechanismus ist bei Microsoft-Foundry-Bereitstellungen in Azure nicht verfügbar, während sein Verhalten auf der Google Cloud Agent Platform von der Claude-Code-Version und dem Modell abhängt.

Mit dieser Prüfung können Sie den Zustand anhand der Konfiguration beurteilen, aber nicht innerhalb der Sitzung beobachten. Im MCP-Abschnitt und im Abschnitt zur Toolsuche der Agent-SDK-Dokumentation wird kein direkter Hinweis „tool search: on/off“ in der Benutzeroberfläche beschrieben. Dass diese beiden Dokumente einen solchen Hinweis nicht erwähnen, beweist nicht, dass es nirgendwo einen gibt.

Sie können die Variable vor dem Start einer Sitzung setzen, zum Beispiel ENABLE_TOOL_SEARCH=auto:15 claude. Wenn die Tools eines bestimmten Servers immer geladen werden sollen, verwenden Sie in der Konfiguration dieses Servers das Feld alwaysLoad: true. Es ist für alle Servertypen verfügbar; die Bedingungen und Einschränkungen werden weiter unten im Abschnitt alwaysLoad beschrieben.

So funktioniert die Toolsuche#

Wenn die Toolsuche aktiviert ist, werden beim Sitzungsstart nur die Namen der zurückgestellten Tools und die Anweisungen des Servers in den Kontext geladen. Die Serveranweisungen beschreiben, für welche Aufgaben der Server nützlich ist. Wenn eine Aufgabe eine Funktion erfordert, die sich noch nicht im Kontext befindet, durchsucht der Agent selbst den Katalog nach einem passenden Tool.

Die Dokumentation des Agent SDK beschreibt den Suchmechanismus ausführlicher: Standardmäßig lädt eine einzelne Suche bis zu fünf der relevantesten Tools aus dem Katalog. Sie bleiben für nachfolgende Gesprächsrunden der Sitzung verfügbar, bis das SDK die Nachrichten komprimiert, in denen der Agent sie gefunden hat. Nach der Komprimierung können zuvor entdeckte Tools aus dem Kontext verschwinden, und der Agent sucht erneut nach ihnen, wenn er sie das nächste Mal benötigt. Der Katalog unterstützt bis zu 10 000 Tools. Die MCP-Dokumentation für Claude Code selbst nennt diese konkreten Zahlen nicht, beschreibt aber dasselbe Prinzip des verzögerten Ladens.

Laut der Dokumentation des Agent SDK fügt jede Suche einen zusätzlichen Roundtrip hinzu. Die Dokumentation gibt nicht genau an, was dieser Roundtrip umfasst. Für Claude Code beschreibt die MCP-Dokumentation außerdem einen Unterschied bei der Fehlermeldung: Ohne Toolsuche informiert Claude Code das Modell nicht über fehlgeschlagene Serververbindungen. Bei aktivierter Suche erhält das Modell Informationen darüber, welcher Server keine Verbindung herstellen konnte und welcher Fehler aufgetreten ist.

Claude Code legt keine feste Obergrenze für die Anzahl der Tools eines einzelnen Servers fest. Die praktische Grenze ist das Kontextfensterbudget der jeweiligen Sitzung.

Die Konfiguration von Tools gehört zu den Aufgaben bei der Verwaltung des Kontexts eines KI-Agenten.

Wann die Toolsuche standardmäßig deaktiviert ist#

Der Mechanismus ist standardmäßig aktiviert, sein Betrieb hängt jedoch vom Modell, API-Host und der Plattform ab.

Modell. Die Toolsuche erfordert ein Modell, das tool_reference-Blöcke unterstützt: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 oder neuer. Bei älteren Modellen lädt Claude Code die Tooldefinitionen vorab.

API-Host. Claude Code deaktiviert die Toolsuche, wenn die Variable ANTHROPIC_BASE_URL auf einen Drittanbieter-Host verweist: Die meisten Proxys leiten die speziellen tool_reference-Blöcke nicht weiter. Das gilt, wenn Sie Claude über Ihr eigenes Gateway oder Ihren eigenen Proxy-Server statt direkt über die Adresse von Anthropic verbinden. Der Grund für die Deaktivierung ist eine nicht standardmäßige ANTHROPIC_BASE_URL; die Art der Bezahlung des Abonnements ist dafür nicht selbst ursächlich. Sie können ENABLE_TOOL_SEARCH ausdrücklich setzen, um dieses Verhalten zu überschreiben. Unterstützt der Proxy selbst keine tool_reference-Blöcke, führt die erzwungene Aktivierung des Mechanismus zu einem Anforderungsfehler. In diesem Fall wird nicht auf das vorzeitige Laden der Definitionen zurückgegriffen.

Bereitstellungsplattform. Bei Microsoft-Foundry-Bereitstellungen auf Azure funktioniert die Toolsuche nicht: Der Server weist die Anfrage zurück, und ENABLE_TOOL_SEARCH setzt dies nicht außer Kraft. Auf der Google Cloud Agent Platform war der Mechanismus vor Claude Code Version 2.1.221 für alle Modelle ausgeschaltet, sofern ENABLE_TOOL_SEARCH=true nicht ausdrücklich gesetzt wurde. Ab dieser Version ist er für Opus/Sonnet/Haiku 4.5 und neuere Modelle standardmäßig aktiviert. Bei älteren Modellen auf der Plattform lädt Claude Code weiterhin alle Tools vorab, weil deren Serverinfrastruktur den erforderlichen internen Header zurückweist.

Die Variable ENABLE_TOOL_SEARCH hat fünf mögliche Einstellungen:

• nicht gesetzt — das Standardverhalten mit den oben aufgeführten Ausnahmen;
• true — der Mechanismus ist bei Modellen aktiviert, die ihn unterstützen, mit zwei Ausnahmen: Azure Foundry und ältere Agent-Platform-Modelle; Anfragen über einen Proxy ohne Unterstützung für tool_reference-Blöcke schlagen fehl;
• auto — Claude Code lädt Tools vorab, solange ihre kombinierten Definitionen weniger als 10% des Kontextfensters belegen, und wechselt zum verzögerten Laden, sobald dieser Schwellenwert erreicht ist;
• auto:N — dasselbe Prinzip mit einem manuell festgelegten prozentualen Schwellenwert;
• false — der Mechanismus ist vollständig deaktiviert, und alle Tools werden vorab geladen.

Außerdem gibt es die Variable CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: Ist sie gesetzt, bleibt die Toolsuche ausgeschaltet, und eine vom Benutzer gesetzte Einstellung ENABLE_TOOL_SEARCH ändert daran nichts. Eine Ausnahme besteht, wenn die Organisation die Toolsuche über verwaltete Einstellungen aktiviert hält; diese Möglichkeit gibt es ab Claude Code Version 2.1.227.

Was alwaysLoad bewirkt und wie es sich auf Kontext und Start auswirkt#

Das Feld alwaysLoad: true in der Konfiguration eines Servers ist für alle Servertypen verfügbar. Damit werden alle Tools dieses Servers beim Start in den Kontext geladen, unabhängig von der Einstellung ENABLE_TOOL_SEARCH. Der Agent muss vor ihrer Verwendung nicht nach ihnen suchen.

Das permanente Laden von Tools hat zwei Folgen. Jedes vorab geladene Tool belegt einen Teil des Kontexts, der sonst für die Aufgabe selbst verfügbar wäre. Außerdem wartet der Sitzungsstart darauf, dass sich dieser Server innerhalb des üblichen Timeouts von fünf Sekunden verbindet.

Eine Ausnahme ist ein Remote-Server mit einem gültigen Cache-Eintrag: Er liefert die Tools aus dem Cache, ohne eine Verbindung herzustellen, und verzögert den Start nicht. Der Discovery-Cache ist standardmäßig ausgeschaltet, sofern er nicht bereits im Rahmen der schrittweisen Einführung der Funktion für das Konto aktiviert wurde. Sie können ihn auch ausdrücklich über MCP_DISCOVERY_CACHE=1 aktivieren. Die Ausnahme für den schnellen Start gilt, wenn der Cache aktiv ist und einen gültigen Eintrag enthält. Tools mit alwaysLoad belegen weiterhin dauerhaft Kontext, unabhängig davon, ob der Agent sie bei der Arbeit mit der Suche benötigt hätte.

Für alle, die einen eigenen MCP-Server schreiben: Serveranweisungen helfen Claude zu verstehen, wann es nach den Server-Tools suchen soll, ähnlich wie Skills. Claude Code kürzt standardmäßig die Beschreibung jedes Tools und die Anweisungen jedes Servers auf 2048 Zeichen. Platzieren Sie wichtige Details deshalb an den Anfang.

Die Wahl, wie Claude Code erweitert wird, hängt von mehr ab als der Anzahl verbundener MCP-Server. Die Anleitungen Claude Code: Wie viele Erweiterungen sollten gleichzeitig aktiv sein und Was Sie in Claude Code wählen sollten: Skills, Subagents, MCP oder Plugins behandeln Skills, Subagents, MCP und Plugins für verschiedene Aufgaben. Eine schrittweise Anleitung zur Einrichtung bestimmter MCP-Server finden Sie unter MCP-Server für Claude Code: fertige Kombinationen.

Wie geht es weiter#

Für eine Gruppe von weniger als ungefähr 10 Tools, deren Definitionen problemlos in den Kontext passen, hält es die Dokumentation des Agent SDK für gewöhnlich für schneller, alle auf einmal zu laden. Im Standardverhalten von Claude Code ist die Toolsuche jedoch aktiviert, wenn die Variable nicht gesetzt ist und keine der oben genannten Einschränkungen gilt. MCP-Tools werden dann erst bei einer Suche geladen, mit Ausnahme von Servern mit alwaysLoad.

Hier können Sie ausdrücklich ENABLE_TOOL_SEARCH=auto setzen: Definitionen werden vorab geladen, solange ihr kombiniertes Volumen weniger als 10% des Kontextfensters beträgt; sobald der Schwellenwert erreicht ist, wird die Suche aktiviert. Eine weitere Möglichkeit ist ENABLE_TOOL_SEARCH=false, wenn Sie wissen, dass die Gruppe nicht wachsen wird. In diesem Fall informiert Claude Code das Modell nicht mehr über fehlgeschlagene Serververbindungen, wie oben beschrieben.

Prüfen Sie in anderen Fällen die Betriebsbedingungen erneut, wenn sich die Umgebung ändert:

• wechseln Sie zu Sonnet/Haiku/Opus 4.5 oder neuer, wenn die Sitzung ein älteres Modell verwendet;
• wenn die Verbindung eine nicht standardmäßige ANTHROPIC_BASE_URL verwendet, setzen Sie ENABLE_TOOL_SEARCH=true ausdrücklich nur dann, wenn der Proxy selbst tool_reference-Blöcke weiterleitet;
• stellen Sie sicher, dass die Bereitstellungsplattform nicht zu den Ausnahmen gehört: Azure Foundry oder ältere Google-Cloud-Agent-Platform-Modelle.

Sind die Bedingungen erfüllt und wird die Suche nicht durch die Einstellungen blockiert, können Sie die benötigten MCP-Server verbinden. Verwenden Sie alwaysLoad nur für Server, deren Tools in jeder Gesprächsrunde benötigt werden; die übrigen können über die Suche geladen werden.

Wenn Sie über Ailoot Zugriff auf KI-Modelle benötigen, sehen Sie sich Ailoot an.