Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Deskrizzjoni u Għodod Permessi

Lezzjoni 5 / 12 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Żewġ lievi fakultattivi, żewġ effetti differenti ħafna
  2. server_description: agħti kuntest lill-mudell
  3. allowed_tools: dejjaq l-ambitu
  4. Għaliex tirrestrinġi, anke meta kollox jaħdem
  5. Ġiegħel iż-żewġ jaħdmu flimkien
  6. Punti Ewlenin

Żewġ lievi fakultattivi, żewġ effetti differenti ħafna

L-URL u t-tikketta biżżejjed biex jistabbilixxu l-konnessjoni, iżda ma jgħidux lil Grok kif juża s-server. Żewġ parametri fakultattivi jimlew din il-lakuna u jikkomplementaw lil xulxin: server_description jispjega għal xiex iservi s-server, filwaqt li allowed_tools—jew allowed_tool_names skont l-SDK—jiddeċiedi x’jista’ jmiss. L-ewwel jiggwida, it-tieni jillimita.

server_description: agħti kuntest lill-mudell

Dan il-parametru jipprovdi lil Grok deskrizzjoni f’lingwa naturali tal-kapaċitajiet tas-server. Il-mudell jużaha biex jagħmel arbitraġġ: għandu jistaqsi lil dan is-server, lil ieħor, jew lill-ebda wieħed?

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."
)

Mingħajr din id-deskrizzjoni, Grok ikollu biss l-ismijiet individwali u d-deskrizzjonijiet tal-għodod esposti. Taħdem, iżda l-mudell jirraġuna mingħajr stampa kbira: jara ġabra ta’ għodod mingħajr ma jaf x’jiffurmaw kollettivament. Deskrizzjoni tajba tagħtih tliet affarijiet li l-ebda isem ta’ għodda ma jista’ jwassal: meta dan is-server ikun rilevanti minflok ieħor, it-tip ta’ talbiet li għandhom jintbagħtu hemmhekk, u—spiss injorat, spiss deċiżiv—x’ma jagħmilx is-server, li jevita sejħiet destined li jfallu.

Ikteb din id-deskrizzjoni daqslikieku kellek tispjega s-servizz lil kollega li qed jingħaqad mal-proġett. Kun speċifiku: “Bażi tad-data tad-dokumentazzjoni teknika tal-prodott” hija utli fejn “Dokumentazzjoni” mhix. Semmi l-azzjonijiet attwalment possibbli, bħal “jippermettilek tfittex, taqra, u taġġorna tikketts.” U jekk l-ambitu huwa ristrett, iddikjarah b’mod ċar: “aċċess biss għall-qari, l-ebda modifika” tiffranka lill-mudell minn tentattiv fallut.

allowed_tools: dejjaq l-ambitu

B’mod default, il-konnessjoni ta’ Grok ma’ server MCP tinjetta l-għodod kollha li dak is-server jesponi fil-kuntest tal-mudell, mingħajr eċċezzjoni. Fuq CRM, dan ifisser li l-ħolqien, il-modifika u t-tħassir ta’ kuntatti huma aċċessibbli daqs it-tfittxija.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm")
# Grok sees ALL tools: create_contact, update_contact,
# delete_contact, search_contacts, export_data, etc.

Il-parametru allowed_tool_names jibdel dan l-imġiba billi jistabbilixxi lista bajda espliċita. Kull xejn li ma jkunx fuqha jsir inviżibbli għall-mudell.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm",
    allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok sees only search_contacts and get_contact_details

Għaliex tirrestrinġi, anke meta kollox jaħdem

L-ewwel raġuni hija s-sigurtà, u ssegwi l-prinċipju tal-inqas privileġġ. Jekk l-applikazzjoni tiegħek teħtieġ biss il-qari, ma tħallix għodod ta’ modifika jew tħassir fil-portata tal-mudell. Injezzjoni ta’ prompt ta’ suċċess—istruzzjoni malizzjuża mdaħħla f’dokument li janalizza Grok—ma tistax ttriggerja delete_contact li qatt ma ġie espost. Il-lista bajda tbiddel inċident potenzjali f’non-avveniment.

# Read-only for a public chatbot
allowed_tool_names=["search_database", "get_record", "format_data"]

It-tieni raġuni hija l-prestazzjoni. Kull għodda esposta tieħu spazju fit-tieqa tal-kuntest, peress li l-isem, id-deskrizzjoni u l-iskema tal-parametri tagħha għandhom joqogħdu hemmhekk. Server MCP li jippubblika ħamsin għodda jikkonsma volum konsiderevoli qabel ma l-utent ikun saqsa l-mistoqsija tiegħu. Billi tonqos għal ħames għodod verament utli, terġa’ tikseb dak l-ispazju għal dak li jimpotta: il-konversazzjoni nnifisha.

It-tielet raġuni hija l-preċiżjoni. Aktar ma jkun estensiv il-katalgu, aktar il-mudell jiddubita bejn għodod simili—u żewġ għodod b’deskrizzjonijiet simili jipproduċu għażliet instabbli minn eżekuzzjoni għal oħra. Katalgu mdejjaq madwar il-każ ta’ użu tiegħek jagħmel l-għażla ferm aktar affidabbli.

Ġiegħel iż-żewġ jaħdmu flimkien

Ir-riżultat isir verament nadif meta tgħaqqad iż-żewġ parametri, sakemm jgħidu l-istess storja.

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"]
)

Hawnhekk, id-deskrizzjoni tħabbar aċċess biss għall-qari u l-lista bajda tiggarantixxih teknikament. Oqgħod attent għas-sitwazzjoni opposta, li tiġri aktar spiss milli taħseb: deskrizzjoni wirtuta minn verżjoni preċedenti li twiegħed kapaċitajiet ta’ kitba issa mneħħija mil-lista bajda. Il-mudell se jipprova s-sejħa, ifalli, u int se tonfoq ħin tfittex bug li ma jeżistix. Irrevedi dejjem dawn iż-żewġ parametri flimkien, qatt mhux separatament.

Punti Ewlenin

  • server_description jgħin lil Grok jifhem meta għandu juża dan is-server MCP
  • Mingħajr allowed_tools, l-għodod kollha tas-server jiġu injettati fil-kuntest
  • Ir-restrizzjoni tal-għodod issaħħaħ is-sigurtà, il-prestazzjoni u l-preċiżjoni
  • Għaqqad id-deskrizzjoni mar-restrizzjoni għal kontroll ottimali
  • Ikteb id-deskrizzjoni bħala spjegazzjoni f’lingwa naturali tal-kapaċitajiet tas-server