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: Search the customer database.

Parem kirjeldus:

search_customers: Find customers by name, email, or company. Returns up to 10 matching customers with their basic info. Use this when you need to identify a customer the user is referring to. For exact lookups by ID, use get_customer_by_id instead.

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: depends on mode

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: search by name/email/company
get_customer: get details by ID
update_customer: update specific fields
delete_customer: archive a customer

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): returns customer + tickets + activity all in one

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): returns customer summaries with priority info
list_tickets(customer_id, status): returns tickets for a customer

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: Create a new invoice for a customer.
IMPORTANT: Pass an idempotency_key (a UUID you generate). If you retry this operation, use the same UUID to prevent duplicate invoices.

Parameters:
- amount: ...
- customer_id: ...
- idempotency_key: UUID to prevent duplicate creation on retry. Generate once per logical operation.

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: Archive a customer record. This is reversible within 30 days; after 30 days, the data is permanently deleted.

PRECONDITIONS:
- Customer must have no active subscriptions.
- Customer must have no open tickets.

If preconditions are not met, this tool returns an error indicating what to resolve first.

SIDE EFFECTS:
- All customer's contacts are also archived.
- Customer is removed from active reports.
- An audit log entry is created.

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)
// where change_string is like "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.

Read tools (safe, idempotent):
- search_customers
- get_customer_by_id
- list_tickets
- list_orders

Compute tools (no state changes):
- summarize_account_activity
- analyze_funnel
- calculate_lifetime_value

Write tools (state changes, need idempotency):
- create_customer
- update_customer_email
- create_ticket
- send_email

Destructive tools (require careful authorization):
- 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:

Tool categories available:
- READ tools (safe to call): search_customers, get_customer_by_id, ...
- COMPUTE tools (no side effects): summarize_account_activity, ...
- WRITE tools (side effects, include idempotency_key): create_customer, ...
- DESTRUCTIVE tools (require human confirmation): delete_customer, ...

Before calling a WRITE or DESTRUCTIVE tool, confirm with the user.

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.