Claude Architect · Oppitunti

Työkalujen kuvaukset ohjaavat valintaa

Malli valitsee työkalut kuvausten, ei nimien, perusteella.

Oppitunti 1/413 vaihetta

Työkalujen kuvaukset ohjaavat valintaa on ilmainen Claude Architect-oppitunti CoddyKitissä. Tämä on oppitunti 1/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Claude Architect-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Malli lukee, se ei arvaa

Kun Claude päättää, mitä työkalua kutsutaan, se ei valitse työkalun nimen perusteella. Se lukee jokaisen työkalun kuvauksen ja päättelee, mikä niistä sopii tehtävään.

Tämä on työkalujen suunnittelun tärkein yksittäinen seikka: kuvaus on ensisijainen valintamekanismi. Työkalu, jonka nimi on process_refund mutta jonka kuvaus on epämääräinen, on vaikeampi valita oikein kuin selkeästi kuvattu työkalu, jolla on kömpelö nimi.

Jos haluatte luotettavaa toimintaa, käyttäkää vaivanne kuvausten kirjoittamiseen – älkää nokkelaan nimeämiseen.

Nimi ei ole spesifikaatio

Nimet ovat lyhyitä ja moniselitteisiä. Tarkastellaan kahta työkalua: search_orders ja lookup_order. Kumpi niistä hakee tilauksen tunnisteen perusteella? Kumpi suodattaa luettelon päivämäärän perusteella? Ette voi päätellä sitä, eikä mallikaan voi.

Varsinainen merkitys välittyy kuvauksesta:

Mihin työkalu on tarkoitettu (käyttötarkoitus).
Mitä se palauttaa.
Mitä syötteitä se odottaa, esimerkkeineen.
Sen reunatapaukset ja sovellettavuuden rajat.

Nimetkää työkalu järkevästi, mutta älkää koskaan luottako nimeen toiminnan erottelussa.

Hyvän kuvauksen rakenne

Hyvä työkalun kuvaus antaa kaiken tiedon, jota malli tarvitsee valitakseen työkalun ja kutsuakseen sitä oikein. Sisällytä:

Tarkoitus — yksi tehtävä, jonka työkalu suorittaa.
Palautettavat arvot — mitä palautetaan ja missä muodossa.
Syötemuodot esimerkkeineen — konkreettiset esimerkkiargumentit.
Reunatapaukset — tyhjät tulokset, löydettävyyden epäonnistuminen ja epäselvyys.
Soveltamisrajat — milloin työkalua EI pidä käyttää.

Rajausehto estää väärän reitityksen samankaltaisten työkalujen välillä.

lookup_order = {
    "name": "lookup_order",
    "description": (
        "Fetch a single order by its exact order_id. "
        "Returns status, items, total, and ship date. "
        "order_id format: 'ORD-' + 8 digits, e.g. 'ORD-10293847'. "
        "Returns an empty result (not an error) if no order matches. "
        "Use this ONLY when you already have a specific order_id; "
        "to find orders by customer or date, use search_orders instead."
    ),
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}

Epämääräiset kuvaukset aiheuttavat väärää reititystä

Yleisin virhe on liian suppea tai epäselvä kuvaus. Se on kokeissa yleinen virheellinen toimintamalli ja tavallinen väärä vastaus, kun kysytään, miksi työkalu valittiin väärin.

Katso, mitä tapahtuu suppeilla kuvauksilla:

get_data: "Hakee tietoja."
fetch_info: "Noutaa tietoja."

Kun tehtävänä on "etsiä asiakkaan viimeisin tilaus", malli ei pysty erottamaan näitä kahta toisistaan. Se saattaa kutsua väärää työkalua tai vaihdella niiden välillä. Päällekkäiset tai epäselvät kuvaukset aiheuttavat väärää reititystä — ratkaisu on täsmällisempi, päällekkäisyyksiä välttävä sanamuoto, ei työkalun uudelleennimeäminen.

Määritä työkalujen välille selkeät rajat

Kun kaksi työkalua voisi perustellusti sopia tilanteeseen, kummankin kuvauksen on ohjattava nimenomaisesti pois toisen luota. Näin poistetaan valintaa sekoittava päällekkäisyys.

Huomaa, kuinka kummassakin kuvauksessa mainitaan toinen työkalu ja kerrotaan, milloin sen käyttöön tulee siirtyä. Tämä vastavuoroinen rajaus pitää mallin oikeassa työkalussa.

tools = [
    {
        "name": "search_orders",
        "description": (
            "List orders matching a customer_id and/or date range. "
            "Returns an array of order summaries (id, status, total). "
            "Use to DISCOVER orders when you do not know the order_id. "
            "For full details of one known order, use lookup_order."
        ),
    },
    {
        "name": "lookup_order",
        "description": (
            "Fetch full details of ONE order by exact order_id. "
            "Use only when the order_id is already known. "
            "To find orders, use search_orders first."
        ),
    },
]

Dokumentoi reunatapaukset kuvauksessa

Reunatapaukset kuuluvat kuvaukseen, koska ne vaikuttavat mallin myöhempään päättelyyn eivätkä vain itse kutsuun.

Kaksi erottelua on tärkeintä:

Käyttöoikeusvirhe (järjestelmään ei saatu yhteyttä — uudelleenyritys saattaa olla aiheellinen) verrattuna kelvolliseen tyhjään tulokseen (osumia ei ole — älä yritä uudelleen, vaan ilmoita tulos).
Mitä tapahtuu epäselvälle syötteelle — esimerkiksi kun asiakastietoja löytyy useita.

Jos kuvauksessa sanotaan "palauttaa tyhjän tuloksen, kun tilausta ei löydy", malli ei käsittele tuloksettomuutta uudelleenyritystä vaativana virheenä. Jos siinä sanotaan "palauttaa useita osumia, kun nimi ei ole yksilöllinen", malli tietää pyytää lisää tunnistetietoja arvauksen sijaan.

Pidä työkalujen määrä pienenä

Liian suuri työkalujen määrä heikentää valintaa täydellisistäkin kuvauksista huolimatta. Valinta on päättelytehtävä, ja vaihtoehtojen lisääminen hajauttaa sitä.

4–5 työkalua agenttia kohden on luotettavan valinnan kannalta optimaalinen määrä.
Vähintään 18 työkalun kohdalla valinnan luotettavuus heikkenee huomattavasti.

Hyvät kuvaukset ja pieni työkalujoukko tukevat siis toisiaan: rajaa kunkin agentin työkalut sen roolin mukaan ja kuvaile nämä harvat työkalut täsmällisesti. Paisunutta työkalujoukkoa ei voi korjata pelkällä sanamuodolla.

Rajaa työkalut roolin mukaan

Kuvausten laatu ja vähimpien oikeuksien periaate ohjaavat samaan suuntaan. Tutkimukseen tarkoitettu aliagentti ei tarvitse hyvitystyökalua, eikä vain lukuoikeuden tarkistajalla pidä olla Write- tai Bash-työkalua.

Roolin mukainen rajaus tekee kaksi asiaa samanaikaisesti:

Se poistaa päällekkäiset ehdokkaat, jolloin jäljelle jäävät kuvaukset on helpompi erottaa toisistaan.
Se pitää kunkin agentin työkalumäärän lähellä optimaalista 4–5 työkalun määrää.

Harvemmat ja rooliin sopivat työkalut tarkoittavat selkeämpiä, päällekkäisyyksiä välttäviä kuvauksia — ja juuri tämä mahdollistaa tarkan valinnan.

support_agent = AgentDefinition(
    name="support",
    description="Resolves customer order and refund requests.",
    system_prompt="Verify identity, then resolve the request.",
    allowed_tools=[
        "get_customer",
        "lookup_order",
        "process_refund",
        "escalate_to_human",
    ],  # 4 role-scoped tools, each clearly described
)

Kuvaukset valitsevat; tool_choice rajoittaa

Kuvaukset ratkaisevat, mikä työkalu sopii tilanteeseen. tool_choice-parametri on erillinen säätö, joka rajoittaa sitä, kutsutaanko työkalua ja miten sitä kutsutaan:

"auto" — malli valitsee tekstin tai työkalun (kuvaukset ohjaavat edelleen valintaa).
"any" — mallin on kutsuttava JOTAKIN työkalua; tästä on hyötyä rakenteisen tulosteen varmistamisessa.
{"type":"tool","name":"X"} — pakottaa käyttämään tiettyä työkalua.

Työkalun pakottaminen ei korjaa huonoa kuvausta — se vain poistaa valinnan. Kun käytössä on "auto" tai "any", malli lukee edelleen kuvauksia valitakseen ehdokkaiden joukosta, joten sanamuodon on yhä oltava selkeä.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},  # model selects by reading descriptions
    messages=messages,
)

Missä työkalut loppuvat ja resurssit alkavat

MCP:ssä kaiken ei pidä olla työkalu. Palvelin tarjoaa kolme primitiiviä, ja oikean valinta pitää työkalujen kuvaukset keskittyneinä:

Työkalut — toimintoja, jotka tekevät jotakin (suorittavat hyvityksen tai kyselyn).
Resurssit — vain luku -muotoiset tiedot ja konteksti, kuten skeemat tai luettelot.
Kehotteet — uudelleenkäytettäviä malleja.

Kun vain luku -muotoinen skeema tai luettelo mallinnetaan resurssiksi työkalun sijaan, se poistuu kokonaan toimintojen valintajoukosta. Kuvauksissa kilpailee tällöin yksi epäselvä ehdokas vähemmän, mikä auttaa suoraan työkalun valinnassa.

Tee myös virheistä valittavia

Valinta ei pääty ensimmäiseen kutsuun — mallin on usein valittava seuraavaksi palautumiseen tarkoitettu palautustyökalu. Tämä valinta riippuu saadusta virheestä.

Yleinen virhe, kuten "Toiminto epäonnistui", ei anna mallille mitään, minkä perusteella reitittää. Rakenteinen MCP-virhe antaa:

isError: true ja errorCategory (transient / validation / business / permission).
isRetryable, message, attempted_query sekä mahdolliset partial_results-tulokset.

Näiden tietojen avulla malli voi päättää järkevästi: yrittää uudelleen tilapäisen virheen jälkeen, korjata kelpoisuusvirheen tai eskaloida liiketoiminta- tai käyttöoikeusvirheen sen sijaan, että se jäisi jumiin.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Order service timed out",
  "attempted_query": "lookup_order(order_id='ORD-10293847')",
  "partial_results": null
}

Pikatarkistus

Sovella työkalun valintaan vaikuttavia tekijöitä todelliseen väärän reitityksen virheeseen.

Vastaa interaktiivisessa oppitunnissa

Kertaus

Työkalun valinnan tärkeimmät opit:

Claude valitsee työkalut lukemalla niiden kuvaukset, ei nimiä.
Hyvä kuvaus kertoo tarkoituksen, palautettavat arvot, syötemuodot esimerkkeineen, reunatapaukset ja soveltamisrajat.
Päällekkäiset tai epäselvät kuvaukset aiheuttavat väärää reititystä; määritä selkeät rajat, jotka ohjaavat kunkin työkalun pois muiden luota.
Dokumentoi reunatapaukset kuvauksessa — erityisesti tyhjät tulokset verrattuna käyttöoikeusvirheisiin sekä epäselvät osumat.
Pidä agentilla 4–5 työkalua; vähintään 18 työkalun kohdalla valinta heikkenee. Rajaa työkalut roolin mukaan.
tool_choice (auto / any / pakotettu) rajoittaa kutsumista, mutta ei korvaa selkeää kuvausta.
Mallinna vain luku -muotoiset tiedot MCP:n resursseina ja palauta rakenteisia virheitä, jotta malli voi reitittää palautumisen.

Aloita maksutta

Opi Python tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 26
Oppitunnit: 104

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Työkalujen kuvaukset ohjaavat valintaa” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Työkalujen kuvaukset ohjaavat valintaa”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Työkalujen kuvaukset ohjaavat valintaa”?

Malli valitsee työkalut kuvausten, ei nimien, perusteella. Harjoittelet Claude Architect-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Claude Architect-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Claude Architect-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 1/4.

Kuinka kauan ”Työkalujen kuvaukset ohjaavat valintaa”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Claude Architect-oppitunnilla?

Kyllä. Jokainen Claude Architect-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

← Takaisin: Claude Architect