Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Kuvaus ja sallitut työkalut

Oppitunti 5 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi valinnaista vipua, kaksi hyvin erilaista vaikutusta
  2. server_description: anna kontekstia mallille
  3. allowed_tools: rajaa laajuutta
  4. Miksi rajoittaa, vaikka kaikki toimisi?
  5. Saata nämä kaksi toimimaan yhdessä
  6. Keskeiset asiat

Kaksi valinnaista vipua, kaksi hyvin erilaista vaikutusta

URL-osoite ja nimi riittävät yhteyden muodostamiseen, mutta ne eivät kerro Grokille, miten palvelinta tulisi käyttää. Kaksi valinnaista parametria paikkaa tämän aukon ja täydentävät toisiaan: server_description selittää, mihin palvelin on tarkoitettu, kun taas allowed_tools – tai SDK:sta riippuen allowed_tool_names – päättää, mihin se saa koskea. Ensimmäinen ohjaa, toinen rajoittaa.

server_description: anna kontekstia mallille

Tämä parametri tarjoaa Grokille luonnollisen kielen kuvauksen palvelimen ominaisuuksista. Malli käyttää sitä päätöksenteossa: pitäisikö sen kysyä tältä palvelimelta, joltakin toiselta vai ei lainkaan?

mcp(
    server_url="https://api.example.com/mcp",
    server_label="docs",
    server_description="Tekninen dokumentaatiopalvelin. Mahdollistaa artikkelien haun, oppaiden tarkastelun ja koodiesimerkkien hakemisen sisäiselle API:lle."
)

Ilman tätä kuvausta Grokilla on käytössään vain yksittäisten työkalujen nimet ja kuvaukset. Se toimii, mutta malli päättelee ilman kokonaiskuvaa: se näkee kokoelman työkaluja ymmärtämättä, mitä ne muodostavat yhdessä. Hyvä kuvaus antaa sille kolme asiaa, joita mikään työkalun nimi ei voi välittää: milloin tämä palvelin on relevantti toisen sijaan, millaisia pyyntöjä sinne tulisi reitittää, ja – usein unohdettu mutta ratkaiseva seikka – mitä palvelin ei tee, mikä säästää turhilta, epäonnistuvilta kutsuilta.

Kirjoita kuvaus ikään kuin selittäisit palvelua projektiin liittyvälle kollegalle. Ole tarkka: “Tuotteen tekninen dokumentaatiotietokanta” on hyödyllinen, pelkkä “Dokumentaatio” ei. Nimeä todellisuudessa mahdolliset toiminnot, kuten “mahdollistaa tukipyyntöjen haun, lukemisen ja päivittämisen”. Jos laajuus on rajoitettu, sano se suoraan: “vain lukuoikeus, ei muokkauksia” säästää mallia epäonnistuneelta yritykseltä.

allowed_tools: rajaa laajuutta

Oletusarvoisesti Grokin yhdistäminen MCP-palvelimeen injectoi kaikki kyseisen palvelimen tarjoamat työkalut mallin kontekstiin ilman poikkeuksia. CRM-järjestelmässä tämä tarkoittaa, että kontaktien luominen, muokkaaminen ja poistaminen ovat yhtä lailla saatavilla kuin haku.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm")
# Grok näkee KAIKKI työkalut: create_contact, update_contact,
# delete_contact, search_contacts, export_data jne.

Parametri allowed_tool_names kääntää tämän toiminnan luomalla nimenomaisen valkoisen listan. Kaikki, mitä listalla ei ole, muuttuu mallille näkymättömäksi.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm",
    allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok näkee vain työkalut search_contacts ja get_contact_details

Miksi rajoittaa, vaikka kaikki toimisi?

Ensimmäinen syy on tietoturva, ja se noudattaa vähäisimpien oikeuksien periaatetta. Jos sovelluksesi tarvitsee vain lukuoikeutta, älä jätä muokkaus- tai poistotyökaluja mallin ulottuville. Onnistunut kehotusinjektio – pahantahtoinen ohje, joka on solutettu Grokin analysoimaan asiakirjaan – ei voi laukaista delete_contact-kutsua, jota ei ole koskaan paljastettu. Valkoinen lista muuttaa mahdollisen välikohtauksen merkityksettömäksi tapahtumaksi.

# Vain lukuoikeus julkiselle chatbotille
allowed_tool_names=["search_database", "get_record", "format_data"]

Toinen syy on suorituskyky. Jokainen paljastettu työkalu vie tilaa konteksti-ikkunasta, sillä sen nimi, kuvaus ja parametrien skeema täytyy mahtua sinne. Viisikymmentä työkalua julkaiseva MCP-palvelin kuluttaa huomattavan määrän tilaa jo ennen kuin käyttäjä on esittänyt kysymystään. Pudottamalla määrä viiteen todella hyödylliseen työkaluun vapautat tilan siihen, mikä on oleellista: itse keskusteluun.

Kolmas syy on tarkkuus. Mitä laajempi luettelo on, sitä enemmän malli epäröi samankaltaisten työkalujen välillä – ja kaksi työkalua, joilla on samankaltaiset kuvaukset, tuottavat epävakaita valintoja suorituskerrosta toiseen. Käyttötapauksesi ympärille tiivistetty luettelo tekee valinnasta huomattavasti luotettavamman.

Saata nämä kaksi toimimaan yhdessä

Tulos on todella siisti, kun yhdistät molemmat parametrit edellyttäen, että ne kertovat samaa tarinaa.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="crm",
    server_description="Vain lukuoikeudella toimiva CRM. Mahdollistaa kontaktien ja yritysten haun ja tarkastelun.",
    allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)

Tässä kuvaus ilmoittaa vain lukuoikeudesta ja valkoinen lista takaa sen teknisesti. Varo päinvastaista tilannetta, jota esiintyy useammin kuin luuletkaan: edellisestä versiosta periytyvä kuvaus, joka lupaa kirjoitusoikeuksia, jotka on nyt poistettu valkoiselta listalta. Malli yrittää kutsua, epäonnistuu, ja sinä käytät aikaa vianetsintään bugille, jota ei ole olemassa. Tarkista nämä kaksi parametria aina yhdessä, älä koskaan erikseen.

Keskeiset asiat

  • server_description auttaa Grokia ymmärtämään, milloin tätä MCP-palvelinta kannattaa käyttää
  • Ilman allowed_tools-parametria kaikki palvelimen työkalut injectoidaan kontekstiin
  • Työkalujen rajoittaminen vahvistaa tietoturvaa, suorituskykyä ja tarkkuutta
  • Yhdistä kuvaus ja rajoitus saavuttaaksesi optimaalisen hallinnan
  • Kirjoita kuvaus luonnollisen kielen selityksenä palvelimen ominaisuuksista