MCP tööriistade kujundamine, mida LLM-id tegelikult õigesti kasutavad

Sa oled MCP serveri ehitanud. Tööriistad töötavad. Sa ühendad LLM agendi külge. Vaatled selle toimimist ja märkad: see ignoreerib su tööriistu, kutsub neid imelike parameetritega, läheb segadusse, millist tööriista kasutada, aheldab neid kummalistes järjekordades.

See on lõhe “tööriistade, mis eksisteerivad” ja “tööriistade, mida LLM-id õigesti kasutavad” vahel. Sellesse läheb enamik MCP serveri vaeva raisku. Ettevõtted ehitavad võimsaid võimekusi, paljastavad need tööriistadena ja vaatavad, kuidas LLM-id ei suuda neid tõhusalt kasutada.

Aitab ümbersõnastamine: kohtle tööriistakujundust nagu UX-disaini, kus LLM on sinu kasutaja. Tööriista kirjeldus on UI. Skeem on vorm. Veateated on tagasiside. Saa need õigeks ja LLM-id töötavad tõhusalt. Saa need valeks ja sinu keerukas taustsüsteem on agendile nähtamatu.

See artikkel käsitleb põhimõtteid koos konkreetsete näidetega sellest, mis töötab ja mis mitte.

Põhimõte 1: Tööriista nimed kommunikeerivad eesmärki

Tööriista nimi on esimene asi, mida LLM näeb. See peaks kirjeldama, mida tööriist teeb, tegevuse mõistes.

Halvad:

• customers (nimisõna, pole tegevust)
• process_customer (ähmane)
• do_x (mõttetu)

Paremad:

• search_customers (selge tegevus)
• get_customer_by_id (konkreetne operatsioon)
• update_customer_email (konkreetne muudatus)

Miks see loeb: LLM-id skaneerivad tööriistade loendeid, otsides asjakohaseid. Kirjeldav nimi laseb neil õige tööriista kiiresti leida. Ähmane nimi sunnib neid kirjeldust hoolikalt lugema (mida nad mõnikord ei tee).

Kasulik muster: standardsed tegusõnaeesliited.

• list_*, search_*, get_* lugemiste jaoks.
• create_*, update_*, delete_* kirjutamiste jaoks.
• analyze_*, summarize_* arvutuste jaoks.

Järjepidevus üle sinu serveri aitab LLM-il ehitada mentaalseid mudeleid.

Põhimõte 2: Kirjeldused on promptid

Tööriista kirjeldus on sinu serveri kõige olulisem tekst. See on see, mida LLM kasutab otsustamaks, kas ja kuidas tööriista kasutada.

Halb kirjeldus:

search_customers: Otsi klientide andmebaasist.

Parem kirjeldus:

search_customers: Leia kliente nime, e-posti või ettevõtte järgi. Tagastab kuni 10 sobivat klienti koos põhiteabega. Kasuta seda, kui pead tuvastama kliendi, kellele kasutaja viitab. Täpseks otsinguks ID järgi kasuta hoopis get_customer_by_id.

Pane tähele, mida parem versioon teeb:

• Kirjeldab sisendeid (“nime, e-posti või ettevõtte järgi”).
• Kirjeldab väljundeid (“kuni 10 sobivat klienti koos põhiteabega”).
• Näitab, millal kasutada (“kui pead identifitseerima kliendi, kellele kasutaja viitab”).
• Näitab, millal mitte kasutada (“Täpseks ID järgi otsimiseks kasuta hoopis get_customer_by_id-d”).

“Millal mitte kasutada” osa on kriitiline. Ilma selleta võib LLM kutsuda search_customers-i, kui get_customer_by_id oleks sobivam.

Põhimõte 3: Parameetrite kirjeldused loevad

Iga parameeter vajab kirjeldust. Ära toetu ainult parameetri nimele.

Halb:

{
  customer_id: string,
  fields: string[]
}

Parem:

{
  customer_id: string,  // "The customer's unique identifier. Get this from search_customers or from explicit user input."
  fields: string[]      // "Specific fields to return. Available: name, email, phone, tier, created_at, last_active. If not specified, returns name and email."
}

Kirjeldused:

• Ütlevad LLM-ile, kuidas väärtus saada.
• Määravad lubatud väärtused, kui kohaldatavad.
• Näitavad vaikeväärtusi.

Põhimõte 4: Vead juhivad taastumist

Kui tööriist annab vea, juhib veateade LLM-i järgmist tegevust. Ähmased vead viivad segastele agentidele.

Halb viga:

{ "error": "Invalid input" }

Parem viga:

{
  "error": "validation_error",
  "message": "The email '...' is not in valid format. It must be like 'name@example.com'.",
  "field": "email",
  "suggestion": "Ask the user for a valid email address."
}

LLM teab nüüd:

• Mis läks valesti (valideerimisviga e-posti väljal).
• Kuidas parandada (kasuta korrektset e-posti formaati).
• Mida edasi teha (küsi kasutajalt).

Võrdle agendi käitumist kahe veaga. Esimese korral võib see sama kõnet uuesti proovida (raisus), alla anda (halb UX) või kehtiva sisendi välja mõelda. Teine viib puhta kasutajasuhtluseni.

Põhimõte 5: Väljund kujundab järgmise tegevuse

Tööriista väljund määrab, mida LLM järgmiseks teeb. Väljundi kujundus mõjutab agendi käitumist.

Halb väljund otsingule:

[
  {"id": "c1", "n": "John", "e": "john@..."},
  {"id": "c2", "n": "Jane", "e": "jane@..."}
]

Parem väljund:

{
  "customers": [
    {"id": "c1", "name": "John Smith", "email": "john@example.com", "tier": "pro"},
    {"id": "c2", "name": "Jane Doe", "email": "jane@example.com", "tier": "free"}
  ],
  "total_found": 2,
  "summary": "Found 2 customers matching 'john'. Note that one is named 'Jane Doe' but has 'john' in their email."
}

Parem väljund:

• Kasutab loetavaid väljanimesid.
• Sisaldab metakonteksti (total_found).
• Sisaldab loomuliku keele summary välja, mis aitab LLM-il vormida, mida edasi öelda.

summary väli on võimas — see on nagu LLM-ile “muide” vihje andmine, kuidas tulemust tõlgendada.

Põhimõte 6: Üks tööriist, üks asi

Tööriistad, mis teevad mitut asja, ajavad LLM-id segadusse. LLM peab otsustama nii selle, kas tööriista kasutada, KUI KA selle, millist režiimi kasutada.

Segadust tekitav:

manage_customer:
  - mode: "search" | "get" | "update" | "delete"
  - params: sõltub režiimist

LLM peab režiimi valima. Nad valivad sageli valesti. Veel hullem, parameetriskeem on keeruline, sest see varieerub režiimi järgi.

Parem: eraldi tööriistad.

search_customers: otsi nime/e-posti/ettevõtte järgi
get_customer: hangi detailid ID järgi
update_customer: uuenda konkreetseid välju
delete_customer: arhiveeri klient

Iga tööriist on üheselt mõistetav. LLM valib ühe kavatsuse põhjal. Skeemid on lihtsad.

See tähendab rohkem tööriistu, aga iga on selgem. LLM saab 10 selge tööriistaga paremini hakkama kui 3 mitmerežiimilise tööriistaga.

Põhimõte 7: Piira sisendeid

Kus võimalik, piira sisendi võimalusi. Loetelud ja valideerimine takistavad LLM-i hallutsineerimist.

Lõdv:

{
  status: string  // could be anything
}

Piiratud:

{
  status: "active" | "trial" | "churned" | "suspended"
}

Piirang on jõustatud skeemi tasandil (piiratud genereerimine takistab LLM-il kehtetuid väärtusi tootmast).

Sama kehtib operatsioonide loetelude, raskusastmete, tüüpide kohta — kõik, millel on teadaolev kehtivate väärtuste komplekt.

Kuupäevadeks kasuta ISO 8601 formaati ja täpsusta seda kirjelduses (“Kuupäev ISO 8601 formaadis, nt 2026-05-15”). Ilma selleta toodavad LLM-id kuupäevi suvalises formaadis.

Põhimõte 8: Vaikeväärtused vähendavad hallutsineerimist

Kui parameetritel on mõistlikud vaikeväärtused, tee need valikuliseks koos serveris rakendatava vaikeväärtusega.

Halb:

{
  query: string,
  limit: number,  // LLM has to provide some value
  include_archived: boolean,
  sort_by: string
}

LLM peab kõigile neile väärtusi valima. Need võivad olla valed.

Parem:

{
  query: string,
  limit: number = 10,            // sensible default
  include_archived: boolean = false,  // safe default
  sort_by: "relevance" | "name" | "created_at" = "relevance"  // most common
}

LLM täpsustab ainult parameetreid, mis on konkreetse päringu jaoks olulised. Vähem parameetreid tähendab vähem ruumi segadusele.

Dokumenteeri vaikeväärtusi kirjeldustes: “Limit: tagastatavate tulemuste arv. Vaikimisi 10, max 50.”

Põhimõte 9: Komponeeritavus loeb

Tööriistad peaksid komponeeruma tööprotsessideks, mida LLM oskab koostada. Õige granulaarsus muudab keerulised ülesanded lihtsaks.

Mõtle ülesandele: “Räägi mulle kõigi meie kolme tähtsama kliendi avatud probleemidest.”

Halb tööriistakomplekt:

get_customer_summary(customer_id): tagastab kliendi + piletid + tegevuse korraga

LLM ei saa “kolme tähtsama” filtrit lihtsalt teha — see tööriist tagastab korraga ühe kliendi kohta kõik. Ülesande tegemiseks peab LLM kõigepealt teadma, kes on tähtsamad kliendid, siis seda tööriista kolm korda kutsuma.

Parem tööriistakomplekt:

list_customers(sort_by="value", limit=N): tagastab klientide kokkuvõtted prioriteediinfoga
list_tickets(customer_id, status): tagastab kliendi piletid

LLM saab komponeerida: loetle tähtsaimad kliendid, siis igaühele loetle avatud probleemid. Komponeerimine on loomulik.

Põhimõte: mõtle mitme-tööriista tööprotsessidele. Tööriistad, mis hästi komponeeruvad, on kasutatavad; need, mis ei komponeeru, sageli ei ole.

Põhimõte 10: Idempotentsus on kommunikeeritud

Kirjutamistööriistadel maini kirjelduses idempotentsuse nõudeid:

create_invoice: Loo kliendile uus arve.
IMPORTANT: Edasta idempotency_key (genereeritud UUID). Kui proovid operatsiooni uuesti, kasuta sama UUID-d, et vältida duplikaatarveid.

Parameetrid:
- amount: ...
- customer_id: ...
- idempotency_key: UUID duplikaatide loomise vältimiseks uuesti proovimisel. Genereeri üks kord loogilise operatsiooni kohta.

Nüüd teab LLM, et tuleb genereerida UUID ja kasutada sama, kui uuesti proovib.

Ilma selle juhiseta võib LLM kas võtme vahele jätta (pole idempotentsust) või iga uuesti-proovi jaoks uue UUID-i genereerida (kaotab mõtte).

Põhimõte 11: Maini eel-/järeltingimusi

Tööriistadele, millel on eeltingimused või olulised kõrvalmõjud, ütle seda:

delete_customer: Arhiveeri kliendi kirje. See on 30 päeva jooksul pöördumatu; pärast 30 päeva kustutatakse andmed jäädavalt.

EELTINGIMUSED:
- Kliendil ei tohi olla aktiivseid tellimusi.
- Kliendil ei tohi olla avatud pileteid.

Kui eeltingimused pole täidetud, tagastab see tööriist vea, mis näitab, mida esmalt lahendada.

KÕRVALMÕJUD:
- Kõik kliendi kontaktid arhiveeritakse samuti.
- Klient eemaldatakse aktiivsetest aruannetest.
- Luuakse auditilogi kirje.

LLM teab nüüd, mida enne kutsumist kontrollida ja mida pärast oodata. Ta saab mitmesammulisi tööprotsesse õigesti planeerida (“kõigepealt sulge nende piletid, siis kustuta”).

Põhimõte 12: Kahtluse korral näited

Keerulistele tööriistadele aitab näite lisamine kirjeldusse:

analyze_funnel: Analyze a conversion funnel from event data.

Parameters:
- start_date: ISO 8601 date
- end_date: ISO 8601 date
- steps: array of step definitions, each {event_name: string, filters?: object}

Example:
{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "steps": [
    {"event_name": "signup"},
    {"event_name": "first_login"},
    {"event_name": "first_action", "filters": {"action_type": "create_project"}},
    {"event_name": "subscription_started"}
  ]
}

Näited õpetavad LLM-ile struktuuri paremini kui ainult skeemid.

Põhimõte 13: Ära paljasta sisemust

LLM ei pea teadma sinu andmebaasi struktuuri ega sisemisi ID-sid. Esita puhas mõisteline mudel.

Halb:

get_user_by_pk(pk: number)

LLM peab teadma “primaarvõtit” — andmebaasi mõistet.

Parem:

get_user(user_id: string)

Peida andmebaasi mõiste. LLM kasutab user_id-d, mis on tähenduslik mõiste.

Samamoodi: ära paljasta kasutuselt kõrvaldatud välju, sisemisi lippe, silumisparameetreid ega midagi muud, mis on sinu teostuse, mitte kasutajale suunatud mõiste kohta.

Põhimõte 14: Väldi maagilisi stringe

Mõned tööriistad nõuavad stringe, mis näevad välja nagu käsud või koodid. Need on veaaltid.

Halb:

modify_record(record_id: string, change_string: string)
// kus change_string on kujul "field1=value1;field2=value2"

LLM peab muudatused konkreetsesse stringiformaati kodeerima. Nad teevad vigu.

Parem:

update_record(record_id: string, updates: { field1?: any; field2?: any; ... })

Struktureeritud muudatused objektina. LLM saab iga välja otse kasutada.

Põhimõte 15: Testi päris LLM-idega

Tööriistade kirjeldused võivad inimestele hästi lugeda, aga LLM-id segadusse ajada. Ainus viis teada saada on testida.

Kasulik tööprotsess:

1. Ehita tööriist.
2. Lase LLM agendil proovida mitut realistlikku ülesannet, kasutades ainult sinu tööriistu.
3. Vaatle läbikukkumisi.
4. Kohanda kirjeldusi läbikukkumiste põhjal.
5. Korda.

Mustrid, mida leiad:

• LLM kasutab valet tööriista → tööriista nimi või kirjeldus on ebaselge.
• LLM annab vale parameetri väärtusi → parameetri kirjeldus või skeem vajab tööd.
• LLM annab pärast vigu alla → veateated vajavad parandamist.
• LLM ei proovi tööriista, mis aitaks → tööriist pole esile toodud või hästi nimetatud.

Iga probleem viitab konkreetsele parandusele.

Diagnostika: märgid, et sinu tööriistad ei ole hästi kujundatud

Mõned mustrid, mis viitavad tööriistakujunduse probleemidele:

LLM kasutab sageli vale tööriista. Näed, et ta kutsub search_customers-i, kuigi oleks pidanud kutsuma get_customer_by_id-d. Parandus: täpsusta, milline tööriist millise olukorra jaoks.

LLM kutsub palju tööriistu ühe asja tegemiseks. Ta aheldab 5 tööriistakõnet, et saavutada, mis peaks olema 1. Parandus: võib-olla on vaja kõrgema taseme komposiit-tööriista või on granulaarsus liiga peen.

LLM annab pärast vigu alla. Proovib korra, saab vea, siis ütleb kasutajale, et ei oska aidata. Parandus: paremad veateated, mis soovitavad järgmisi samme.

LLM hallutsineerib parameetri väärtusi. Mõtleb välja user_id-sid, kuupäevi, ID-sid. Parandus: täpsusta, kuidas saada kehtivaid väärtusi; lisa piiranguid; lisa vigade käsitlemine, mis püüab ja selgitab probleemi.

LLM kordab sama ebaõnnestunud kõnet. Sama viga, korduvalt. Parandus: veateade ei ütle LLM-ile konkreetselt, mis viga on.

LLM ei kasuta võimsat tööriista. Sa ehitasid suurepärase tööriista; LLM ei kutsu seda kunagi. Parandus: paranda avastamist (selgem nimi, parem kirjeldus, “kasuta seda, kui…” juhis).

Tööriistade taksonoomia

Kasulik harjutus: organiseeri tööriistad taksonoomiasse.

Lugemistööriistad (ohutud, idempotentsed):
- search_customers
- get_customer_by_id
- list_tickets
- list_orders

Arvutustööriistad (olekut ei muuda):
- summarize_account_activity
- analyze_funnel
- calculate_lifetime_value

Kirjutustööriistad (oleku muudatused, vaja idempotentsust):
- create_customer
- update_customer_email
- create_ticket
- send_email

Hävitavad tööriistad (vajavad hoolikat autoriseerimist):
- delete_customer
- cancel_subscription
- archive_record

Taksonoomia aitab sul:

• Rakendada sobivaid kaitsemeetmeid (idempotentsus, kinnitus hävitavate jaoks).
• Dokumenteerida kategooriaid LLM-i süsteemipromptides.
• Püüda kinni puuduvad tööriistad (kui kategooria on tühi, kas vajad?).

Kasulik süsteemiprompti täiendus:

Saadaval tööriistakategooriad:
- LUGEMISTÖÖRIISTAD (ohutu kutsuda): search_customers, get_customer_by_id, ...
- ARVUTUSTÖÖRIISTAD (kõrvalmõjusid pole): summarize_account_activity, ...
- KIRJUTUSTÖÖRIISTAD (kõrvalmõjud, lisa idempotency_key): create_customer, ...
- HÄVITAVAD TÖÖRIISTAD (vajavad inimkinnitust): delete_customer, ...

Enne KIRJUTAMISE või HÄVITAMISE tööriista kutsumist kinnita kasutajaga.

See kujundab, kuidas LLM kasutab tööriistu tööprotsessi tasandil, mitte ainult kõne-haaval.

Näiteid levinud parandustest

Et põhimõtted konkreetseks teha, enne-ja-pärast näited:

Näide 1: Otsingu tööriist

Enne:

// search documents
{
  name: "documents",
  description: "Search documents",
  inputSchema: { query: "string" }
}

Pärast:

{
  name: "search_documents",
  description: `Search internal documents (knowledge base, wiki pages, policies).
  Returns matching documents with title, excerpt, and link. Use when the user asks about company policies, procedures, or internal documentation. Returns up to 10 most relevant matches by semantic similarity.`,
  inputSchema: {
    query: {
      type: "string",
      description: "Search query. Be specific. Good: 'remote work policy 2026'. Bad: 'documents about work'."
    },
    document_type: {
      type: "string",
      enum: ["policy", "procedure", "guide", "faq", "any"],
      default: "any",
      description: "Filter to a specific type of document."
    },
    limit: {
      type: "number",
      default: 5,
      maximum: 10,
      description: "Number of results."
    }
  }
}

Näide 2: Tegevuse tööriist

Enne:

{
  name: "send_email",
  description: "Send an email",
  inputSchema: {
    to: "string",
    subject: "string",
    body: "string"
  }
}

Pärast:

{
  name: "draft_email_to_customer",
  description: `Draft an email to a customer based on a recent interaction. The email is saved as a draft for human review before sending — it is NOT sent automatically. The user must approve drafts in their inbox.

  Use when:
  - You've identified an action requiring follow-up with the customer.
  - You have a specific reason and content for the email.

  Do NOT use:
  - To send marketing or promotional content.
  - Without explicit user request.
  - To respond to refund or cancellation requests (escalate to human instead).`,
  inputSchema: {
    customer_id: {
      type: "string",
      description: "Customer ID from search_customers or get_customer."
    },
    subject: {
      type: "string",
      description: "Email subject, 4-8 words, specific. Avoid generic subjects like 'Following up'."
    },
    body: {
      type: "string",
      description: "Email body, plain text. 3-5 sentences. Personal, specific, not template-y."
    },
    tone: {
      type: "string",
      enum: ["professional", "friendly", "apologetic", "urgent"],
      default: "professional",
      description: "Tone of the email."
    },
    idempotency_key: {
      type: "string",
      description: "UUID for this draft. Use the same UUID if retrying to avoid duplicates."
    }
  }
}

“Pärast” versioonid juhivad LLM-i tunduvalt tõhusamalt. Need tunduvad paljusõnalised; need on seda väärt.

Kokkuvõte

Tööriistakujundus LLM-idele on oma distsipliin. Põhimõtted ei ole intuitiivsed; need nõuavad LLM-i kui kasutaja vaatamist ja liidese vastavat kujundamist.

Mustrid, mis loevad:

• Tegusõnaga nimed.
• Rikkalikud kirjeldused, mis selgitavad mida, millal ja mitte-millal.
• Parameetripõhised kirjeldused näidete ja piirangutega.
• Struktureeritud, teostatavad veateated.
• Väljundi kujud, mis juhivad järgmist tegevust.
• Üks tööriist mõiste kohta.
• Mõistlikud vaikeväärtused.
• Komponeeritav granulaarsus.
• Selgelt välja toodud idempotentsus.
• Dokumenteeritud eel-/järeltingimused.
• Näited keerulistele tööriistadele.
• Peidetud sisemus.
• Päris LLM-idega testimine.

Enamik MCP servereid ei kukku läbi sellepärast, et protokoll on raske, vaid sellepärast, et tööriistu pole LLM-i silmas pidades kujundatud. Saa tööriistakujundus õigeks ja sinu serverist saab tõhus vahend; saa see valeks ja sinu keerukas taustsüsteem läheb raisku.

Kohtle LLM-i kui kasutajat. Kujunda vastavalt. Investeering tasub mitmekordselt selles, kui hästi sinu tööriistu päriselt kasutatakse.