Vyhledávání nástrojů v Claude Code: jak agent najde potřebný nástroj MCP

Pokud jste ke Claude Code připojili několik serverů MCP, vyhledávání nástrojů mu umožňuje načítat potřebné nástroje podle potřeby, aniž by předem načítalo všechny jejich definice. Při spuštění agent obdrží názvy odložených nástrojů a pokyny serverů, poté v katalogu vyhledá, co potřebuje. Díky tomu může pracovat s rozsáhlou sadou nástrojů: dokumentace společnosti Anthropic uvádí, že přesnost výběru klesá, když je najednou načteno více než 30–50 nástrojů. Jde o obecné doporučení, nikoli o měření vaší relace. Vyhledávání nástrojů je ve výchozím nastavení zapnuté, pokud ho model podporuje, ale platforma, proxy nebo nastavení ho mohou vypnout.

Dokumentace Ailoot: API, klíče a nastavení.

Jak nástroje MCP ovlivňují kontext Claude Code bez vyhledávání nástrojů?#

Každý připojený server MCP přidává své nástroje do seznamu nástrojů, které může agent volat. Bez vyhledávání nástrojů se jejich definice — název, popis a schéma parametrů — načítají do kontextu předem. Servery se připojují na pozadí při spuštění relace. Pokud je potřeba nástroj ze serveru, jehož připojování ještě nebylo dokončeno, Claude Code čeká prostřednictvím interního nástroje WaitForMcpServers. Kolik nástrojů a tokenů konkrétní server přidává, můžete vyhodnotit samostatně pro každé připojení.

Oficiální dokumentace společnosti Anthropic uvádí dva přibližné údaje (obecná čísla bez uvedení metody měření):

• 50 nástrojů může zabrat 10–20 tisíc tokenů kontextu;
• přesnost výběru správného nástroje klesá, když je najednou načteno více než 30–50 nástrojů.

Jak v Claude Code vyhodnotit nastavení vyhledávání nástrojů?#

Chcete-li zjistit, zda by vyhledávání nástrojů mělo v aktuální relaci fungovat, zkontrolujte tyto podmínky:

• který model odpovídá — Sonnet/Haiku/Opus 4.5 nebo novější: mechanismus je dostupný; starší model: není;
• zda je ANTHROPIC_BASE_URL nastaven na nestandardního hostitele — v takovém případě je mechanismus ve výchozím nastavení vypnutý, pokud ho výslovně nezapnete pomocí ENABLE_TOOL_SEARCH;
• hodnotu proměnné ENABLE_TOOL_SEARCH — false mechanismus zcela vypne; auto/auto:N ho zapne pouze tehdy, když objem definic dosáhne určitého prahu;
• zda je nastavena proměnná CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS — bez spravovaného nastavení organizace ponechá vyhledávání nástrojů vypnuté, i když uživatel nastavil ENABLE_TOOL_SEARCH;
• zda je nástroj ToolSearch blokován prostřednictvím permissions.deny v nastavení — takové omezení vyhledávání vypne;
• která platforma se používá — mechanismus není dostupný při nasazení Microsoft Foundry v Azure, zatímco na Google Cloud Agent Platform závisí jeho chování na verzi Claude Code a modelu.

Tato kontrola umožňuje posoudit stav podle konfigurace, ale nepozorovat ho uvnitř relace. Část o MCP ani část o vyhledávání nástrojů v dokumentaci Agent SDK nepopisují přímý indikátor „vyhledávání nástrojů: zapnuto/vypnuto“ v rozhraní. To, že se o něm tyto dva dokumenty nezmiňují, nedokazuje, že takový indikátor neexistuje nikde jinde.

Proměnnou můžete nastavit před spuštěním relace, například ENABLE_TOOL_SEARCH=auto:15 claude. Chcete-li zajistit, aby se nástroje konkrétního serveru načítaly vždy, použijte v konfiguraci daného serveru pole alwaysLoad: true. Je dostupné pro všechny typy serverů; podmínky a omezení jsou popsány níže v části alwaysLoad.

Jak funguje vyhledávání nástrojů#

Když je vyhledávání nástrojů zapnuté, při spuštění relace se do kontextu načítají pouze názvy odložených nástrojů a pokyny serveru. Pokyny serveru popisují, pro jaké úlohy se server hodí. Když úloha vyžaduje schopnost, která zatím není v kontextu, agent sám vyhledá vhodný nástroj v katalogu.

Dokumentace Agent SDK popisuje mechanismus vyhledávání podrobněji: ve výchozím nastavení jedno vyhledávání načte z katalogu až pět nejrelevantnějších nástrojů. Zůstávají dostupné pro další tahy v relaci, dokud SDK nezkomprimuje zprávy, ve kterých je agent našel. Po kompakci mohou dříve objevené nástroje z kontextu vypadnout a agent je při další potřebě znovu vyhledá. Katalog podporuje až 10 000 nástrojů. Dokumentace MCP pro samotné Claude Code tyto konkrétní údaje neuvádí, ale popisuje stejný princip odloženého načítání.

Podle dokumentace Agent SDK každé vyhledávání přidá jedno další opakované volání. Dokumentace přesně neuvádí, co toto opakované volání zahrnuje. Dokumentace MCP pro Claude Code také popisuje rozdíl v hlášení chyb: bez vyhledávání nástrojů Claude Code modelu neoznamuje neúspěšná připojení serverů. Když je vyhledávání zapnuté, model dostane informaci o tom, který server se nepodařilo připojit a jaká chyba nastala.

Claude Code nestanovuje pevný limit počtu nástrojů z jednoho serveru. Praktickým limitem je rozpočet kontextového okna pro danou relaci.

Konfigurace nástrojů patří k úkolům spojeným se správou kontextu AI agenta.

Kdy je vyhledávání nástrojů ve výchozím nastavení vypnuté#

Mechanismus je ve výchozím nastavení zapnutý, jeho fungování však závisí na modelu, hostiteli API a platformě.

Model. Vyhledávání nástrojů vyžaduje model podporující bloky tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 nebo novější. U starších modelů Claude Code načítá definice nástrojů předem.

Hostitel API. Claude Code vypne vyhledávání nástrojů, když proměnná ANTHROPIC_BASE_URL odkazuje na hostitele třetí strany: většina proxy nepředává speciální bloky tool_reference. Týká se to připojení ke Claude přes vlastní bránu nebo proxy server namísto přímého připojení na adresu společnosti Anthropic. Důvodem vypnutí je nestandardní ANTHROPIC_BASE_URL; způsob platby za předplatné sám o sobě příčinou není. Toto chování můžete přepsat výslovným nastavením ENABLE_TOOL_SEARCH. Pokud samotná proxy bloky tool_reference nepodporuje, vynucené zapnutí mechanismu způsobí chybu požadavku. V takovém případě se nástroje nezačnou načítat předem jako náhradní řešení.

Platforma nasazení. Vyhledávání nástrojů nefunguje při nasazení Microsoft Foundry hostovaném v Azure: server požadavek odmítne a ENABLE_TOOL_SEARCH toto chování nepřepíše. Na Google Cloud Agent Platform byl mechanismus před verzí Claude Code 2.1.221 vypnutý pro všechny modely, pokud nebylo výslovně nastaveno ENABLE_TOOL_SEARCH=true. Od této verze je ve výchozím nastavení zapnutý pro Opus/Sonnet/Haiku 4.5 a novější. U starších modelů na této platformě Claude Code stále načítá všechny nástroje předem, protože jejich serverová infrastruktura odmítá požadovanou interní hlavičku.

Proměnná ENABLE_TOOL_SEARCH má pět možných nastavení:

• není nastavena — standardní chování s výše uvedenými výjimkami;
• true — mechanismus je zapnutý u modelů, které ho podporují, s výjimkou dvou případů: Azure Foundry a starší modely na Agent Platform; požadavky odesílané přes proxy bez podpory bloků tool_reference selžou;
• auto — Claude Code načítá nástroje předem, dokud jejich souhrnné definice zabírají méně než 10 % kontextového okna, a po dosažení tohoto prahu přejde na odložené načítání;
• auto:N — stejný princip s ručně určeným procentním prahem;
• false — mechanismus je zcela vypnutý a všechny nástroje se načítají předem.

Existuje také proměnná CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: pokud je nastavena, vyhledávání nástrojů zůstane vypnuté a uživatel jeho stav změnou ENABLE_TOOL_SEARCH nezmění. Výjimkou je případ, kdy organizace udržuje vyhledávání nástrojů zapnuté prostřednictvím spravovaného nastavení, které je dostupné od verze Claude Code 2.1.227.

Co dělá alwaysLoad a jak ovlivňuje kontext a spuštění#

Pole alwaysLoad: true v konfiguraci serveru je dostupné pro všechny typy serverů. Díky němu se všechny nástroje daného serveru načítají do kontextu při spuštění bez ohledu na nastavení ENABLE_TOOL_SEARCH. Agent je před použitím nemusí vyhledávat.

Trvalé načítání nástrojů má dva důsledky. Každý nástroj načtený předem zabírá část kontextu, která by jinak byla k dispozici pro samotnou úlohu. Spuštění relace navíc čeká na připojení tohoto serveru, a to v rámci standardního pětisekundového časového limitu.

Výjimkou je vzdálený server s platnou položkou v mezipaměti: poskytne nástroje z mezipaměti bez připojení a spuštění nezdrží. Mezipaměť zjišťování je ve výchozím nastavení vypnutá, pokud již nebyla pro účet zapnuta během postupného zavádění této funkce. Můžete ji také zapnout výslovně pomocí MCP_DISCOVERY_CACHE=1. Výjimka pro rychlé spuštění platí, když je mezipaměť aktivní a obsahuje platnou položku. Nástroje s nastavením alwaysLoad stále trvale zabírají kontext bez ohledu na to, zda by je agent při práci prostřednictvím vyhledávání potřeboval.

Pokud píšete vlastní server MCP: pokyny serveru pomáhají Claude pochopit, kdy má jeho nástroje vyhledávat, podobně jako Skills. Claude Code ve výchozím nastavení zkracuje popis každého nástroje a pokyny každého serveru na 2048 znaků, proto umístěte důležité podrobnosti na začátek.

Volba způsobu rozšíření Claude Code závisí na více než jen počtu připojených serverů MCP. Průvodci Claude Code: kolik rozšíření ponechat najednou a Co zvolit v Claude Code: Skills, Subagents, MCP, nebo Plugins se věnují možnostem Skills, Subagents, MCP a Plugins pro různé úlohy. Podrobný postup nastavení konkrétních serverů MCP najdete v průvodci Servery MCP pro Claude Code: připravené kombinace.

Co dál#

U sady obsahující méně než přibližně 10 nástrojů, jejichž definice se bez potíží vejdou do kontextu, dokumentace Agent SDK uvádí, že obvykle bývá rychlejší načíst je všechny najednou. Ve výchozím chování Claude Code je však vyhledávání nástrojů zapnuté, když proměnná není nastavena a neplatí žádné z výše uvedených omezení; nástroje MCP se proto načítají odloženě při vyhledávání, s výjimkou serverů s nastavením alwaysLoad.

Zde můžete výslovně nastavit ENABLE_TOOL_SEARCH=auto: definice se budou načítat předem, dokud jejich souhrnný objem nedosáhne 10 % kontextového okna, a po dosažení prahu se zapne vyhledávání. Další možností je ENABLE_TOOL_SEARCH=false, pokud víte, že se sada nebude rozrůstat. V takovém případě Claude Code přestane modelu oznamovat selhání připojení serverů, jak je popsáno výše.

V ostatních případech znovu zkontrolujte provozní podmínky, když se prostředí změní:

• pokud relace používá starší model, přejděte na Sonnet/Haiku/Opus 4.5 nebo novější;
• pokud připojení používá nestandardní ANTHROPIC_BASE_URL, nastavte výslovně ENABLE_TOOL_SEARCH=true pouze tehdy, když samotná proxy předává bloky tool_reference;
• ujistěte se, že platforma nasazení nepatří mezi výjimky: Azure Foundry nebo starší modely na Google Cloud Agent Platform.

Jsou-li podmínky splněny a nastavení vyhledávání neblokují, můžete připojit potřebné servery MCP. alwaysLoad použijte pouze u serverů, jejichž nástroje jsou potřeba při každém tahu relace; ostatní nechte načítat prostřednictvím vyhledávání.

Pokud potřebujete přístup k modelům AI prostřednictvím Ailoot, podívejte se na Ailoot.