Salt la conținutul principal
Română— Alege o limbă
Meniu

Descriere și instrumente permise

Lecția 5 din 12 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Două pârghii opționale, două efecte foarte diferite
  2. server_description: oferiți context modelului
  3. allowed_tools: restrângeți domeniul de aplicare
  4. De ce să restricționați, chiar dacă totul funcționează
  5. Faceți ca cele două să lucreze împreună
  6. Puncte cheie

Două pârghii opționale, două efecte foarte diferite

URL-ul și eticheta sunt suficiente pentru a stabili conexiunea, dar nu îi spun lui Grok cum să utilizeze serverul. Doi parametri opționali completează acest gol și se completează reciproc: server_description explică scopul serverului, în timp ce allowed_tools—sau allowed_tool_names în funcție de SDK—decide ce are voie să atingă. Primul ghidează, al doilea constrânge.

server_description: oferiți context modelului

Acest parametru oferă lui Grok o descriere în limbaj natural a capacităților serverului. Modelul o folosește pentru a arbitra: ar trebui să interogheze acest server, pe un altul sau niciunul?

mcp(
    server_url="https://api.example.com/mcp",
    server_label="docs",
    server_description="Server de documentație tehnică. Permite căutarea articolelor, consultarea ghidurilor și obținerea de exemple de cod pentru API-ul intern."
)

Fără această descriere, Grok are la dispoziție doar numele și descrierile individuale ale instrumentelor expuse. Funcționează, dar modelul raționează fără o imagine de ansamblu: vede o colecție de instrumente fără a ști ce formează ele colectiv. O descriere bună îi oferă trei lucruri pe care niciun nume de instrument nu le poate transmite: când este relevant acest server și nu altul, tipul de cereri care trebuie direcționate acolo și—adesea neglijat, dar decisiv—ce nu face serverul, evitând astfel apeluri sortite eșecului.

Scrieți această descriere ca și cum ați explica serviciul unui coleg care se alătură proiectului. Fiți specific: „Baza de date cu documentație tehnică a produsului“ este util, spre deosebire de simplul „Documentație“. Enumerați acțiunile efectiv posibile, cum ar fi „permite căutarea, citirea și actualizarea tichetelor“. Iar dacă domeniul de aplicare este restricționat, precizați acest lucru clar: „acces doar în citire, fără modificări“ va scuti modelul de o încercare eșuată.

allowed_tools: restrângeți domeniul de aplicare

În mod implicit, conectarea lui Grok la un server MCP injectează toate instrumentele pe care acel server le expune în contextul modelului, fără excepție. În cazul unui CRM, aceasta înseamnă că crearea, modificarea și ștergerea contactelor sunt accesibile la fel ca și căutarea.

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

Parametrul allowed_tool_names inversează acest comportament prin stabilirea unei liste albe explicite. Orice nu se află pe aceasta devine invizibil pentru model.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm",
    allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok vede doar search_contacts și get_contact_details

De ce să restricționați, chiar dacă totul funcționează

Primul motiv este securitatea, iar acesta urmează principiul privilegiului minim. Dacă aplicația dumneavoastră are nevoie doar de citire, nu lăsați instrumentele de modificare sau ștergere la îndemâna modelului. O injecție de prompt reușită—o instrucțiune malițioasă strecurată într-un document analizat de Grok—nu poate declanșa un delete_contact care nu a fost niciodată expus. Lista albă transformă un potențial incident într-un non-eveniment.

# Doar citire pentru un chatbot public
allowed_tool_names=["search_database", "get_record", "format_data"]

Al doilea motiv este performanța. Fiecare instrument expus ocupă spațiu în fereastra de context, deoarece numele, descrierea și schema de parametri ale acestuia trebuie să încapă acolo. Un server MCP care publică cincizeci de instrumente consumă un volum considerabil înainte ca utilizatorul să fi pus măcar întrebarea. Reducând numărul la cinci instrumente cu adevărat utile, recuperați acel spațiu pentru ceea ce contează: conversația în sine.

Al treilea motiv este precizia. Cu cât catalogul este mai extins, cu atât modelul ezită mai mult între instrumente similare—iar două instrumente cu descrieri similare produc alegeri instabile de la o execuție la alta. Un catalog strâns în jurul cazului dumneavoastră de utilizare face selecția semnificativ mai fiabilă.

Faceți ca cele două să lucreze împreună

Rezultatul devine cu adevărat curat atunci când combinați ambii parametri, cu condiția ca aceștia să spună aceeași poveste.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="crm",
    server_description="CRM doar în citire. Căutați și vizualizați contacte și companii.",
    allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)

Aici, descrierea anunță accesul doar în citire, iar lista albă garantează acest lucru din punct de vedere tehnic. Feriți-vă de situația opusă, care se întâmplă mai des decât credeți: o descriere moștenită dintr-o versiune anterioară care promite capacități de scriere, acum eliminate din lista albă. Modelul va încerca apelul, va eșua, iar dumneavoastră veți pierde timp căutând un bug care nu există. Revizuiți întotdeauna acești doi parametri împreună, niciodată separat.

Puncte cheie

  • server_description ajută Grok să înțeleagă când să utilizeze acest server MCP
  • Fără allowed_tools, toate instrumentele serverului sunt injectate în context
  • Restricționarea instrumentelor consolidează securitatea, performanța și precizia
  • Combinați descrierea și restricția pentru un control optim
  • Scrieți descrierea ca o explicație în limbaj natural a capacităților serverului