Kirjeldus ja lubatud tööriistad
Sellel lehel
Kaks vabatahtlikku hooba, kaks väga erinevat mõju
URL ja silt (label) piisavad ühenduse loomiseks, kuid need ei ütle Grokile, kuidas serverit kasutada. Kaks vabatahtlikku parameetrit täidavad selle lünka ja täiendavad teineteist: server_description selgitab, milleks server mõeldud on, samas kui allowed_tools – või allowed_tool_names olenevalt SDK-st – otsustab, mida serveril puudutada lubatakse. Esimene suunab, teine piirab.
server_description: anna mudelile kontekst
See parameeter annab Grokile serveri võimete loomuliku keele kirjelduse. Mudel kasutab seda otsuse tegemisel: kas küsida sellelt serverilt, mõnelt teiselt või mitte üheltki?
mcp(
server_url="https://api.example.com/mcp",
server_label="docs",
server_description="Technical documentation server. Lets you search articles, consult guides, and get code examples for the internal API."
)
Ilma selle kirjelduseta on Grokil vaid avaldatud tööriistade üksikud nimed ja kirjeldused. See toimib, kuid mudel arutleb ilma suuremat pilti nägemata: ta näeb tööriistade kogumit, teadmata, mida need koos moodustavad. Hea kirjeldus annab talle kolm asja, mida ükski tööriista nimi edasi anda ei suuda: millal on see server asjakohasem kui teine, millist tüüpi päringuid sinna suunata, ja – sageli tähelepanuta jäetud, kuid otsustav – mida server ei tee, mis hoiab ära ebaõnnestunud kutseid.
Kirjuta see kirjeldus nii, nagu selgitaksid teenust projektiga liituvale kolleegile. Ole konkreetne: „Toote tehnilise dokumentatsiooni andmebaas“ on kasulik, kus „Dokumentatsioon“ seda ei ole. Nimeta tegelikult võimalikke tegevusi, nagu „võimaldab otsida, lugeda ja uuendada pileteid“. Ja kui ulatus on piiratud, ütle see selgelt: „ainult lugemisõigus, muudatusi ei tehta“ hoiab mudeli ebaõnnestunud katse eest.
allowed_tools: kitsenda ulatust
Vaikimisi süstib Groki ühendamine MCP serveriga kõik selle serveri avaldatud tööriistad mudeli konteksti, eranditeta. CRM-i puhul tähendab see, et kontaktide loomine, muutmine ja kustutamine on sama ligipääsetavad kui otsing.
mcp(server_url="https://api.example.com/mcp",
server_label="crm")
# Grok näeb KÕIKI tööriistu: create_contact, update_contact,
# delete_contact, search_contacts, export_data jne.
Parameeter allowed_tool_names pöörab selle käitumise ümber, kehtestades selge valge nimekirja. Kõik, mida seal ei ole, muutub mudelile nähtamatuks.
mcp(server_url="https://api.example.com/mcp",
server_label="crm",
allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok näeb ainult search_contacts ja get_contact_details
Miks piirata, isegi kui kõik toimib
Esimene põhjus on turvalisus ja see järgib vähimate õiguste printsiipi. Kui sinu rakendus vajab ainult lugemist, ära jäta muutmise või kustutamise tööriistu mudeli ulatusse. Edukas sisendi süstimine (prompt injection) – pahatahtlik juhend, mis on peidetud Groki analüüsitavasse dokumenti – ei saa käivitada delete_contact käsku, mida kunagi avaldatud ei ole. Valge nimekiri muudab potentsiaalse intsidenti mittesündmuseks.
# Ainult lugemisõigus avaliku vestlusroboti jaoks
allowed_tool_names=["search_database", "get_record", "format_data"]
Teine põhjus on jõudlus. Iga avaldatud tööriist võtab ruumi kontekstiaknas, kuna sinna peavad mahtuma selle nimi, kirjeldus ja parameetrite skeem. Viiskümmend tööriista avaldav MCP server tarbib enne kasutaja küsimuse esitamist juba märkimisväärse mahu. Vähendades need viiele tõeliselt kasulikule tööriistale, vabastad selle ruumi selle jaoks, mis loeb: vestluse enda jaoks.
Kolmas põhjus on täpsus. Mida ulatuslikum on kataloog, seda rohkem mudel kõhkleb sarnaste tööriistade vahel – ja kaks sarnase kirjeldusega tööriista tekitavad ühest täitmisest teise ebastabiilseid valikuid. Sinu kasutusjuhtumi ümber kitsendatud kataloog muudab valiku oluliselt usaldusväärsemaks.
Pane need kaks koos tööle
Tulemus muutub tõeliselt puhtaks, kui kombineerid mõlemat parameetrit, eeldusel, et need räägivad sama lugu.
mcp(
server_url="https://api.example.com/mcp",
server_label="crm",
server_description="Read-only CRM. Search and view contacts and companies.",
allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)
Siin teatab kirjeldus ainult lugemisõigusest ja valge nimekiri garanteerib seda tehniliselt. Hoia end vastupidise olukorra eest, mis juhtub sagedamini, kui arvad: eelmisest versioonist päritud kirjeldus, mis lubab kirjutamisvõimalusi, mis on nüüd valgest nimekirjast eemaldatud. Mudel püüab kutset sooritada, ebaõnnestub ja sina kulutad aega vea otsimisele, mida tegelikult ei eksisteeri. Vaata need kaks parameetrit alati koos üle, mitte kunagi eraldi.
Peamised punktid
server_descriptionaitab Grokil mõista, millal seda MCP serverit kasutada- Ilma
allowed_tools-ita süstitakse kõik serveri tööriistad konteksti - Tööriistade piiramine tugevdab turvalisust, jõudlust ja täpsust
- Kombineeri kirjeldus ja piirang optimaalseks kontrolliks
- Kirjuta kirjeldus kui serveri võimete loomuliku keele selgitus