Työkaluhaku Claude Codessa: miten agentti löytää tarvitsemansa MCP-työkalun

Jos olet yhdistänyt Claude Codeen useita MCP-palvelimia, työkaluhaku voi ladata tarvittavat työkalut tarpeen mukaan ilman, että kaikkien määritelmät ladataan etukäteen. Käynnistyksen yhteydessä agentti saa lykättyjen työkalujen nimet ja palvelimien ohjeet ja etsii sitten luettelosta tarvitsemansa. Näin se pystyy työskentelemään suuren työkalujoukon kanssa: Anthropicin dokumentaation mukaan valinnan tarkkuus heikkenee, kun kerralla ladataan yli 30–50 työkalua. Tämä on yleisluonteinen suositus, ei mittaustulos sinun istunnostasi. Työkaluhaku on oletusarvoisesti käytössä, kun malli tukee sitä, mutta alusta, välityspalvelin tai asetukset voivat poistaa sen käytöstä.

Ailoot-dokumentaatio: API, avaimet ja käyttöönotto.

Mitä kontekstille tapahtuu ilman työkaluhakua#

Jokainen yhdistetty MCP-palvelin lisää työkalunsa niiden työkalujen luetteloon, joita agentti voi kutsua. Ilman työkaluhakua niiden määritelmät — nimi, kuvaus ja parametris skeema — ladataan kontekstiin etukäteen. Palvelimet yhdistyvät taustalla istunnon käynnistyessä. Jos tarvittavan työkalun palvelin ei ole vielä saanut yhteyttä muodostettua, Claude Code odottaa sisäisen WaitForMcpServers-työkalun kautta. Voit arvioida erikseen, kuinka monta työkalua ja tokenia tietty palvelin lisää kullakin yhteyskerralla.

Anthropic ilmoittaa virallisessa dokumentaatiossaan kaksi likimääräistä lukua (yleisluonteisia lukuja, joiden mittausmenetelmää ei täsmennetä):

• 50 työkalua voi viedä 10–20 tuhatta kontekstitokenia;
• oikean työkalun valinnan tarkkuus heikkenee, kun kerralla ladataan yli 30–50 työkalua.

Työkalumahaun toiminnan arviointi asetuksista#

Voit tarkistaa seuraavat asiat selvittääksesi, pitäisikö työkalumahaun toimia nykyisessä istunnossa:

• mikä malli vastaa — Sonnet/Haiku/Opus 4.5 tai uudempi: mekanismi on käytettävissä; vanhempi malli: se ei ole käytettävissä;
• onko ANTHROPIC_BASE_URL määritetty epätyypilliseksi palvelinosoitteeksi — siinä tapauksessa mekanismi on oletusarvoisesti pois käytöstä, ellei sitä erikseen oteta käyttöön asetuksella ENABLE_TOOL_SEARCH;
• ENABLE_TOOL_SEARCH-muuttujan arvo — false poistaa mekanismin kokonaan käytöstä; auto/auto:N ottaa sen käyttöön vasta, kun määritelmien määrä saavuttaa kynnysarvon;
• onko CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS määritetty — ilman organisaation hallittuja asetuksia se pitää työkalumahaun pois käytöstä, vaikka käyttäjä olisi asettanut ENABLE_TOOL_SEARCH-muuttujan;
• onko ToolSearch-työkalu estetty asetusten permissions.deny-kohdassa — tällainen rajoitus poistaa haun käytöstä;
• mitä alustaa käytetään — mekanismi ei ole käytettävissä Azuren Microsoft Foundry -käyttöönotossa, kun taas sen toiminta Google Cloud Agent Platformissa riippuu Claude Code -versiosta ja mallista.

Tämän tarkistuksen avulla voit arvioida tilannetta määritysten perusteella, mutta et nähdä sitä istunnon aikana. Agent SDK:n dokumentaation MCP-osiossa ja työkaluhakua käsittelevässä osiossa ei kuvata käyttöliittymän suoraa ”työkaluhaku: käytössä/pois käytöstä” -ilmaisinta. Se, ettei näissä kahdessa dokumentissa mainita tällaista ilmaisinta, ei todista, ettei sellaista olisi muualla.

Voit määrittää muuttujan ennen istunnon käynnistämistä, esimerkiksi näin: ENABLE_TOOL_SEARCH=auto:15 claude. Jos haluat varmistaa, että tietyn palvelimen työkalut ladataan aina, käytä palvelimen määrityksissä kenttää alwaysLoad: true. Se on käytettävissä kaikille palvelintyypeille; ehdot ja rajoitukset kuvataan jäljempänä olevassa alwaysLoad-osiossa.

Näin työkaluhaku toimii#

Kun työkaluhaku on käytössä, istunnon käynnistyessä kontekstiin ladataan vain lykättyjen työkalujen nimet ja palvelimen ohjeet. Palvelimen ohjeissa kuvataan, mihin tehtäviin palvelin soveltuu. Kun tehtävä edellyttää kykyä, jota ei vielä ole kontekstissa, agentti etsii itse luettelosta sopivan työkalun.

Agent SDK:n dokumentaatiossa hakumekanismia kuvataan tarkemmin: oletusarvoisesti yksi haku lataa luettelosta enintään viisi osuvinta työkalua. Ne pysyvät käytettävissä istunnon seuraavilla vuoroilla, kunnes SDK tiivistää viestit, joiden kautta agentti löysi ne. Tiivistämisen jälkeen aiemmin löydetyt työkalut voivat poistua kontekstista, ja agentti etsii ne uudelleen seuraavan kerran, kun niitä tarvitaan. Luettelo tukee enintään 10 000 työkalua. Claude Coden MCP-dokumentaatiossa ei anneta näitä tarkkoja lukuja, mutta siinä kuvataan sama viivästetyn lataamisen periaate.

Agent SDK:n dokumentaation mukaan jokainen haku lisää yhden ylimääräisen edestakaisen tiedonsiirtokierroksen. Dokumentaatiossa ei täsmennetä, mitä kyseinen kierros tarkalleen sisältää. Claude Coden MCP-dokumentaatiossa kuvataan myös ero virheiden raportoinnissa: ilman työkaluhakua Claude Code ei ilmoita mallille epäonnistuneista palvelinyhteyksistä. Kun haku on käytössä, malli saa tiedon siitä, mikä palvelin ei saanut yhteyttä ja mikä virhe oli kyseessä.

Claude Code ei aseta kiinteää rajaa yhden palvelimen työkalujen määrälle. Käytännössä rajan asettaa istunnon konteksti-ikkunan budjetti.

Työkalujen määrittäminen on yksi tekoälyagentin kontekstin hallintaan liittyvistä tehtävistä.

Milloin työkaluhaku on oletusarvoisesti pois käytöstä#

Mekanismi on oletusarvoisesti käytössä, mutta sen toiminta riippuu mallista, API-palvelinosoitteesta ja alustasta.

Malli. Työkaluhaku edellyttää mallia, joka tukee tool_reference-lohkoja: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 tai uudempi. Vanhemmissa malleissa Claude Code lataa työkalujen määritelmät etukäteen.

API-palvelinosoite. Claude Code poistaa työkalumahaun käytöstä, kun ANTHROPIC_BASE_URL-muuttuja osoittaa kolmannen osapuolen palvelimeen: useimmat välityspalvelimet eivät välitä erityisiä tool_reference-lohkoja eteenpäin. Näin käy, kun muodostat yhteyden Claudeen oman yhdyskäytäväsi tai välityspalvelimesi kautta Anthropic-osoitteeseen yhdistämisen sijaan. Käytöstä poistamisen syy on epätyypillinen ANTHROPIC_BASE_URL; tilauksen maksutapa ei itsessään aiheuta tätä. Voit ohittaa tämän toiminnan asettamalla ENABLE_TOOL_SEARCH-muuttujan erikseen. Jos välityspalvelin ei itse tue tool_reference-lohkoja, mekanismin pakottaminen käyttöön aiheuttaa pyyntövirheen. Tällöin se ei siirry takaisin määritelmien lataamiseen etukäteen.

Käyttöönottoalusta. Työkaluhaku ei toimi Azuren Microsoft Foundry -käyttöönotossa: palvelin hylkää pyynnön, eikä ENABLE_TOOL_SEARCH ohita tätä rajoitusta. Google Cloud Agent Platformissa mekanismi oli ennen Claude Code -versiota 2.1.221 pois käytöstä kaikissa malleissa, ellei ENABLE_TOOL_SEARCH=true-asetusta ollut määritetty erikseen. Kyseisestä versiosta alkaen se on oletusarvoisesti käytössä Opus/Sonnet/Haiku 4.5 -malleissa ja uudemmissa. Alustan vanhemmissa malleissa Claude Code lataa edelleen kaikki työkalut etukäteen, koska palvelininfrastruktuuri hylkää tarvittavan sisäisen otsakkeen.

ENABLE_TOOL_SEARCH-muuttujalla on viisi mahdollista asetusta:

• ei asetettu — oletustoiminta yllä mainituin poikkeuksin;
• true — mekanismi otetaan käyttöön sitä tukevissa malleissa, lukuun ottamatta kahta tapausta: Azure Foundry ja vanhemmat Agent Platform -mallit; välityspalvelimen kautta lähetetyt pyynnöt epäonnistuvat, jos välityspalvelin ei tue tool_reference-lohkoja;
• auto — Claude Code lataa työkalut etukäteen, kunnes niiden yhdistetyt määritelmät vievät alle 10 % konteksti-ikkunasta, ja siirtyy lykättyyn lataamiseen kynnysarvon täytyttyä;
• auto:N — sama periaate, mutta prosentuaalinen kynnysarvo määritetään käsin;
• false — mekanismi poistetaan kokonaan käytöstä ja kaikki työkalut ladataan etukäteen.

Lisäksi on CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS-muuttuja: jos se on asetettu, työkaluhaku pysyy pois käytöstä, eikä käyttäjän asettama ENABLE_TOOL_SEARCH muuta tätä. Poikkeuksena on tilanne, jossa organisaatio pitää työkalumahaun käytössä hallituilla asetuksilla, jotka ovat saatavilla Claude Code -versiosta 2.1.227 alkaen.

Mitä alwaysLoad tekee ja miten se vaikuttaa kontekstiin ja käynnistykseen#

Palvelimen määrityksissä oleva alwaysLoad: true -kenttä on käytettävissä kaikille palvelintyypeille. Sen avulla kaikki kyseisen palvelimen työkalut ladataan kontekstiin käynnistyksen yhteydessä ENABLE_TOOL_SEARCH-asetuksesta riippumatta. Agentin ei tarvitse etsiä niitä ennen käyttöä.

Työkalujen jatkuvalla lataamisella on kaksi seurausta. Jokainen etukäteen ladattu työkalu vie osan siitä kontekstista, joka muuten olisi käytettävissä itse tehtävään. Lisäksi istunnon käynnistys odottaa, että tämä palvelin muodostaa yhteyden, tavallisen viiden sekunnin aikakatkaisun puitteissa.

Poikkeuksena on etäpalvelin, jolla on kelvollinen välimuistimerkintä: se toimittaa työkalut välimuistista muodostamatta yhteyttä eikä viivästytä käynnistystä. Löytämisvälimuisti on oletusarvoisesti pois käytöstä, ellei sitä ole jo otettu käyttöön tilillä ominaisuuden asteittaisen käyttöönoton aikana. Voit ottaa sen käyttöön myös erikseen asetuksella MCP_DISCOVERY_CACHE=1. Nopean käynnistyksen poikkeus pätee, kun välimuisti on käytössä ja siinä on kelvollinen merkintä. alwaysLoad-asetuksen työkalut vievät silti pysyvästi tilaa kontekstista riippumatta siitä, olisiko agentti tarvinnut niitä hakua käyttäessään.

Jos kirjoitat omaa MCP-palvelinta: palvelimen ohjeet auttavat Claudea ymmärtämään, milloin sen pitäisi etsiä palvelimen työkaluja, aivan kuten Skills-ohjeet. Claude Code lyhentää oletusarvoisesti kunkin työkalun kuvauksen ja kunkin palvelimen ohjeet 2048 merkkiin, joten sijoita tärkeimmät tiedot alkuun.

Claude Coden laajennustavan valintaan vaikuttaa muukin kuin yhdistettyjen MCP-palvelimien määrä. Oppaissa Claude Code: kuinka monta laajennusta kannattaa pitää käytössä kerrallaan ja Mitä Claude Codessa kannattaa valita: Skills, Subagents, MCP vai Plugins tarkastellaan Skills-, Subagents-, MCP- ja Plugins-vaihtoehtoja eri tehtäviin. Katso tiettyjen MCP-palvelimien vaiheittaiset asennusohjeet oppaasta Claude Coden MCP-palvelimet: valmiita yhdistelmiä.

Mitä seuraavaksi#

Agent SDK:n dokumentaation mukaan alle noin 10 työkalun joukossa kaikkien määritelmät kannattaa yleensä ladata kerralla, jos ne mahtuvat vaivatta kontekstiin, sillä se on nopeampaa. Claude Coden oletustoiminnassa työkaluhaku on kuitenkin käytössä, kun muuttujaa ei ole asetettu eikä mikään yllä mainituista rajoituksista päde; MCP-työkalujen lataamista lykätään hakuun asti, lukuun ottamatta palvelimia, joilla on alwaysLoad.

Tässä tapauksessa voit asettaa ENABLE_TOOL_SEARCH=auto: määritelmät ladataan etukäteen, kunnes niiden yhteenlaskettu määrä on alle 10 % konteksti-ikkunasta, ja haku otetaan käyttöön kynnysarvon täytyttyä. Toinen vaihtoehto on ENABLE_TOOL_SEARCH=false, jos tiedät, ettei työkalujoukko kasva. Tällöin Claude Code lakkaa ilmoittamasta mallille palvelinyhteyksien epäonnistumisista, kuten yllä kuvattiin.

Muissa tapauksissa tarkista toimintaehdot uudelleen, kun ympäristö muuttuu:

• vaihda Sonnet/Haiku/Opus 4.5 -malliin tai uudempaan, jos istunnossa käytetään vanhempaa mallia;
• jos yhteys käyttää epätyypillistä ANTHROPIC_BASE_URL-osoitetta, aseta ENABLE_TOOL_SEARCH=true erikseen vain, kun välityspalvelin itse välittää tool_reference-lohkot eteenpäin;
• varmista, ettei käyttöönottopaikka ole poikkeusten luettelossa: Azure Foundry tai vanhemmat Google Cloud Agent Platform -mallit.

Kun ehdot täyttyvät eikä haku ole estetty asetuksissa, voit yhdistää tarvitsemasi MCP-palvelimet. Käytä alwaysLoad-asetusta vain palvelimille, joiden työkaluja tarvitaan istunnon jokaisella vuorolla; jätä muut ladattaviksi haun kautta.

Jos tarvitset pääsyn tekoälymalleihin Ailootin kautta, tutustu Ailootiin.