Tools zoeken in Claude Code: hoe de agent de MCP-tool vindt die hij nodig heeft

Als je meerdere MCP-servers met Claude Code hebt verbonden, kan het zoeken naar tools de benodigde tools op verzoek laden, zonder eerst alle definities te laden. Bij het opstarten ontvangt de agent de namen van uitgestelde tools en de instructies van de servers. Daarna doorzoekt de agent de catalogus op wat nodig is. Zo kan de agent met een grote verzameling tools werken: in de documentatie van Anthropic staat dat de selectienauwkeurigheid daalt wanneer er meer dan 30-50 tools tegelijk zijn geladen. Dit is algemene richtlijn, geen meting van jouw sessie. Het zoeken naar tools is standaard ingeschakeld wanneer het model dit ondersteunt, maar het platform, een proxy of instellingen kunnen het uitschakelen.

Ailoot-documentatie: API, sleutels en configuratie.

Wat er zonder zoeken naar tools met de context gebeurt#

Elke verbonden MCP-server voegt zijn tools toe aan de lijst met dingen die de agent kan aanroepen. Zonder zoeken naar tools worden de definities — naam, beschrijving en parameterschema — vooraf in de context geladen. Servers maken op de achtergrond verbinding wanneer een sessie start. Als er een tool nodig is van een server die nog geen verbinding heeft gemaakt, wacht Claude Code via de interne tool WaitForMcpServers. Je kunt per verbinding afzonderlijk beoordelen hoeveel tools en tokens een bepaalde server toevoegt.

De officiële documentatie van Anthropic geeft twee geschatte cijfers (algemene getallen, zonder vermelde meetmethode):

• 50 tools kunnen 10-20 duizend contexttokens in beslag nemen;
• de nauwkeurigheid bij het selecteren van de juiste tool daalt wanneer er meer dan 30-50 tegelijk zijn geladen.

Hoe je aan de hand van de instellingen kunt beoordelen of tools zoeken werkt#

Controleer de volgende voorwaarden om te bepalen of zoeken naar tools in de huidige sessie zou moeten werken:

• welk model antwoordt — Sonnet/Haiku/Opus 4.5 of nieuwer: het mechanisme is beschikbaar; een ouder model: niet beschikbaar;
• of ANTHROPIC_BASE_URL is ingesteld op een niet-standaardhost — in dat geval staat het mechanisme standaard uit, tenzij het expliciet wordt ingeschakeld via ENABLE_TOOL_SEARCH;
• de waarde van de variabele ENABLE_TOOL_SEARCH — false schakelt het mechanisme volledig uit; auto/auto:N schakelt het alleen in wanneer het volume van de definities een drempel bereikt;
• of CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS is ingesteld — zonder de beheerde instellingen van de organisatie houdt deze tool zoeken uitgeschakeld, zelfs als de gebruiker ENABLE_TOOL_SEARCH heeft ingesteld;
• of de tool ToolSearch via permissions.deny in de instellingen is geblokkeerd — zo'n beperking schakelt het zoeken uit;
• welk platform wordt gebruikt — het mechanisme is niet beschikbaar bij Microsoft Foundry-implementaties in Azure; op Google Cloud Agent Platform hangt het gedrag af van de versie van Claude Code en het model.

Met deze controle kun je de status op basis van de configuratie beoordelen, maar niet binnen de sessie waarnemen. De MCP-sectie en de sectie over zoeken naar tools in de Agent SDK-documentatie beschrijven geen directe indicator in de interface voor ‘zoeken naar tools: aan/uit’. Dat deze indicator niet in deze twee documenten wordt genoemd, bewijst niet dat zo'n indicator nergens bestaat.

Je kunt de variabele instellen voordat je een sessie start, bijvoorbeeld met ENABLE_TOOL_SEARCH=auto:15 claude. Gebruik het veld alwaysLoad: true in de configuratie van een server om ervoor te zorgen dat de tools van die server altijd worden geladen. Dit is beschikbaar voor alle servert typen; de voorwaarden en beperkingen staan beschreven in de sectie over alwaysLoad hieronder.

Hoe zoeken naar tools werkt#

Wanneer zoeken naar tools is ingeschakeld, worden bij het starten van de sessie alleen de namen van uitgestelde tools en de instructies van de server in de context geladen. De serverinstructies beschrijven voor welke taken de server nuttig is. Wanneer een taak een mogelijkheid vereist die nog niet in de context staat, zoekt de agent zelf in de catalogus naar een geschikte tool.

De Agent SDK-documentatie beschrijft het zoekmechanisme gedetailleerder: standaard laadt één zoekopdracht maximaal vijf van de meest relevante tools uit de catalogus. Deze blijven beschikbaar tijdens latere beurten in de sessie totdat de SDK de berichten comprimeert waarin de agent ze heeft gevonden. Na het comprimeren kunnen eerder gevonden tools uit de context verdwijnen. De agent zoekt ze dan opnieuw op wanneer ze de volgende keer nodig zijn. De catalogus ondersteunt maximaal 10 000 tools. De MCP-documentatie voor Claude Code zelf geeft deze specifieke cijfers niet, maar beschrijft hetzelfde principe van uitgesteld laden.

Volgens de Agent SDK-documentatie voegt elke zoekopdracht één extra heen-en-terugverzoek toe. De documentatie specificeert niet precies wat dat verzoek omvat. Voor Claude Code beschrijft de MCP-documentatie ook een verschil in foutmeldingen: zonder zoeken naar tools meldt Claude Code mislukte serververbindingen niet aan het model. Als zoeken is ingeschakeld, ontvangt het model informatie over welke server geen verbinding kon maken en wat de fout was.

Claude Code hanteert geen vaste limiet voor het aantal tools van één server. De praktische limiet is het budget van het contextvenster voor de specifieke sessie.

Tools configureren is een van de taken bij het beheren van de context van een AI-agent.

Wanneer zoeken naar tools standaard is uitgeschakeld#

Het mechanisme is standaard ingeschakeld, maar de werking ervan hangt af van het model, de API-host en het platform.

Model. Voor zoeken naar tools is een model nodig dat tool_reference-blokken ondersteunt: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 of later. Voor oudere modellen laadt Claude Code de tooldefinities vooraf.

API-host. Claude Code schakelt zoeken naar tools uit wanneer de variabele ANTHROPIC_BASE_URL naar een host van een derde partij verwijst: de meeste proxies geven de speciale tool_reference-blokken niet door. Dit geldt wanneer je met Claude verbinding maakt via je eigen gateway of proxyserver in plaats van rechtstreeks via het adres van Anthropic. De reden voor het uitschakelen is een niet-standaard ANTHROPIC_BASE_URL; de manier waarop het abonnement wordt betaald, veroorzaakt dit op zichzelf niet. Je kunt dit gedrag overschrijven door ENABLE_TOOL_SEARCH expliciet in te stellen. Als de proxy zelf geen tool_reference-blokken ondersteunt, leidt het geforceerd inschakelen van het mechanisme tot een verzoekfout. In dat geval valt het systeem niet terug op het vooraf laden van definities.

Implementatieplatform. Zoeken naar tools werkt niet bij Microsoft Foundry-implementaties die op Azure worden gehost: de server weigert het verzoek en ENABLE_TOOL_SEARCH overschrijft dit niet. Op Google Cloud Agent Platform stond het mechanisme vóór versie 2.1.221 van Claude Code voor alle modellen uit, tenzij ENABLE_TOOL_SEARCH=true expliciet was ingesteld. Vanaf die versie is het standaard ingeschakeld voor Opus/Sonnet/Haiku 4.5 en nieuwer. Voor oudere modellen op het platform blijft Claude Code alle tools vooraf laden, omdat hun serverinfrastructuur de vereiste interne header weigert.

De variabele ENABLE_TOOL_SEARCH heeft vijf mogelijke instellingen:

• niet ingesteld — het standaardgedrag, met de hierboven genoemde uitzonderingen;
• true — het mechanisme wordt ingeschakeld voor modellen die het ondersteunen, behalve in twee gevallen: Azure Foundry en oudere Agent Platform-modellen; verzoeken via een proxy die geen tool_reference-blokken ondersteunt, mislukken;
• auto — Claude Code laadt tools vooraf zolang hun gecombineerde definities minder dan 10% van het contextvenster innemen. Zodra die drempel wordt bereikt, schakelt Claude Code over op uitgesteld laden;
• auto:N — hetzelfde principe, met een handmatig opgegeven procentuele drempel;
• false — het mechanisme wordt volledig uitgeschakeld en alle tools worden vooraf geladen.

Er is ook de variabele CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: als deze is ingesteld, blijft zoeken naar tools uitgeschakeld en verandert het instellen van ENABLE_TOOL_SEARCH door een gebruiker daar niets aan. De uitzondering is wanneer de organisatie zoeken naar tools ingeschakeld houdt via beheerde instellingen, beschikbaar vanaf versie 2.1.227 van Claude Code.

Wat alwaysLoad doet en welk effect het op de context en het opstarten heeft#

Het veld alwaysLoad: true in de configuratie van een server is beschikbaar voor alle servert typen. Hiermee worden alle tools van die server bij het opstarten in de context geladen, ongeacht de instelling van ENABLE_TOOL_SEARCH. De agent hoeft er vóór gebruik niet naar te zoeken.

Tools altijd laden heeft twee gevolgen. Elke vooraf geladen tool neemt een deel in beslag van de context die anders beschikbaar zou zijn voor de taak zelf. Daarnaast wacht het opstarten van de sessie totdat deze server verbinding heeft gemaakt, binnen de standaardtimeout van vijf seconden.

Een uitzondering is een externe server met een geldige cachevermelding: deze levert de tools uit de cache zonder verbinding te maken en vertraagt het opstarten niet. De ontdekkingscache staat standaard uit, tenzij deze al voor het account is ingeschakeld tijdens de gefaseerde uitrol van de functie. Je kunt deze ook expliciet inschakelen via MCP_DISCOVERY_CACHE=1. De uitzondering voor snel opstarten geldt wanneer de cache actief is en een geldige vermelding bevat. Tools met alwaysLoad blijven permanent context innemen, ongeacht of de agent ze nodig zou hebben gehad bij het werken via zoeken.

Voor iedereen die een eigen MCP-server schrijft: serverinstructies helpen Claude te begrijpen wanneer het naar de tools van die server moet zoeken, net als Skills. Claude Code kort standaard de beschrijving van elke tool en de instructies van elke server in tot 2048 tekens. Zet belangrijke details daarom aan het begin.

De keuze hoe je Claude Code uitbreidt, hangt van meer af dan alleen het aantal verbonden MCP-servers. De gidsen Claude Code: hoeveel extensies houd je tegelijk aan en Wat kies je in Claude Code: Skills, Subagents, MCP of Plugins behandelen Skills, Subagents, MCP en Plugins voor verschillende taken. Raadpleeg MCP-servers voor Claude Code: kant-en-klare combinaties voor stapsgewijze configuratie van specifieke MCP-servers.

Wat nu#

Voor een set van minder dan ongeveer 10 tools waarvan de definities zonder problemen in de context passen, vermeldt de Agent SDK-documentatie dat alles in één keer laden meestal sneller is. In het standaardgedrag van Claude Code is zoeken naar tools echter ingeschakeld wanneer de variabele niet is ingesteld en geen van de bovenstaande beperkingen geldt. MCP-tools worden dan pas na een zoekopdracht geladen, behalve voor servers met alwaysLoad.

Je kunt hier expliciet ENABLE_TOOL_SEARCH=auto instellen: definities worden vooraf geladen zolang hun gecombineerde volume minder dan 10% van het contextvenster bedraagt; zodra de drempel wordt bereikt, wordt zoeken ingeschakeld. Een andere optie is ENABLE_TOOL_SEARCH=false als je weet dat de set niet groter zal worden. In dat geval stopt Claude Code, zoals hierboven beschreven, met het melden van fouten bij serververbindingen aan het model.

Controleer in andere gevallen de werkingsvoorwaarden opnieuw wanneer de omgeving verandert:

• stap over op Sonnet/Haiku/Opus 4.5 of nieuwer als de sessie een ouder model gebruikt;
• als de verbinding een niet-standaard ANTHROPIC_BASE_URL gebruikt, stel ENABLE_TOOL_SEARCH=true dan alleen expliciet in wanneer de proxy zelf tool_reference-blokken doorgeeft;
• controleer of het implementatieplatform niet op de uitzonderingenlijst staat: Azure Foundry of oudere Google Cloud Agent Platform-modellen.

Als aan de voorwaarden is voldaan en de instellingen het zoeken niet blokkeren, kun je de benodigde MCP-servers verbinden. Gebruik alwaysLoad alleen voor servers waarvan de tools bij elke beurt van de sessie nodig zijn; laat de overige tools via zoeken laden.

Als je via Ailoot toegang wilt tot AI-modellen, neem dan een kijkje bij Ailoot.