# Toolsuche in Claude Code: Wie der Agent das benötigte MCP-Tool findet > Wie die Toolsuche in Claude Code funktioniert: Was sofort in den Kontext geladen wird, wann sich der Mechanismus selbst ausschaltet und wie ENABLE_TOOL_SEARCH und alwaysLoad konfiguriert werden. Source: https://ailoot.ai/blog/de/claude-code-tool-search-mcp-limit/ Canonical: https://ailoot.ai/blog/de/claude-code-tool-search-mcp-limit/ Language: de Publisher: Ailoot (https://ailoot.ai/) Translation: guide-055 Revision: sha256-6e5899209e70a76d88133a9f3a43cce19b111b631a55f16b714781ce591ecb59 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](https://ailoot.ai/docs/). ## 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](https://ailoot.ai/blog/de/claude-code-skills-subagents-mcp-plugins/) und [Was Sie in Claude Code wählen sollten: Skills, Subagents, MCP oder Plugins](https://ailoot.ai/blog/de/skills-subagents-mcp-plugins-claude-code/) 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](https://ailoot.ai/blog/de/mcp-servers-claude-code/). ## 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.
### Quellen - [MCP in Claude Code, Abschnitt „Mit MCP-Toolsuche skalieren“ — offizielle Dokumentation von Anthropic](https://code.claude.com/docs/en/mcp.md) - [Toolsuche im Agent SDK — offizielle Dokumentation von Anthropic](https://code.claude.com/docs/en/agent-sdk/tool-search.md)
Wenn Sie über Ailoot Zugriff auf KI-Modelle benötigen, sehen Sie sich [Ailoot](https://ailoot.ai/) an. ## Fragen und Antworten ### Warum kann die aktivierte Toolsuche hinter einem Proxy scheitern? Ein fremder API-Host muss tool_reference-Blöcke unterstützen. Das Erzwingen von ENABLE_TOOL_SEARCH ergänzt diese Unterstützung nicht. Ein inkompatibler Proxy kann die Anfrage ablehnen, statt alle Tools vorab zu laden. ### Wann sollte ich alwaysLoad für einen MCP-Server setzen? Wenn dessen Tools in jeder Runde gebraucht werden. Dann belegen alle Tooldefinitionen bereits beim Start Kontext. Der Start kann auf die Verbindung warten, sofern kein gültiger Eintrag im Discovery-Cache greift. ## Ailoot · Das Unternehmen und sein Projektportfolio Ailoot baut auf bewährte Betriebserfahrung, einen großen Kundenstamm, stabilen Service und kontinuierliche KPI-Kontrolle. Das Unternehmen und sein Projektportfolio: Millionen von Kunden; monatliche Umsätze in Milliardenhöhe. Ailoot nutzt diese Betriebserfahrung für den API-Zugang zu KI-Funktionen in Kundenprodukten, Agenten, Anwendungen und Automatisierungen.