Näin suunnittelet MCP-työkaluja, joita LLM:t käyttävät oikein

Olet rakentanut MCP-palvelimen ja työkalut toimivat. Yhdistät LLM-agentin ja huomaat sen sivuuttavan työkaluja, kutsuvan niitä oudoilla parametreilla, sekoittavan sopivat työkalut ja ketjuttavan niitä kummallisesti.

Tämä on ero olemassa olevien työkalujen ja LLM:n oikein käyttämien työkalujen välillä. Siihen tuhlautuu suuri osa MCP-palvelimiin tehdystä työstä. Yritykset rakentavat tehokkaita kyvykkyyksiä, tarjoavat ne työkaluina ja näkevät LLM:ien käyttävän niitä tehottomasti.

Hyödyllinen näkökulma on käsitellä työkalusuunnittelua UX-suunnitteluna, jossa LLM on käyttäjä. Työkalukuvaus on käyttöliittymä, skeema lomake ja virheilmoitukset palaute. Kun ne ovat kunnossa, LLM toimii tehokkaasti. Muuten kehittynyt taustajärjestelmäsi jää agentille näkymättömäksi.

Tämä artikkeli käsittelee periaatteet toimivien ja toimimattomien ratkaisujen konkreettisilla esimerkeillä.

Periaate 1: työkalun nimi välittää tarkoituksen

Työkalun nimi on ensimmäinen asia, jonka LLM näkee. Sen pitäisi kuvata toimintaverbillä, mitä työkalu tekee.

Huono:

• customers (substantiivi, ei toimintoa)
• process_customer (epämääräinen)
• do_x (merkityksetön)

Parempi:

• search_customers (selkeä toiminto)
• get_customer_by_id (täsmällinen toiminto)
• update_customer_email (täsmällinen muutos)

Miksi tällä on merkitystä: LLM etsii työkaluluettelosta olennaista työkalua. Kuvaava nimi auttaa löytämään sen nopeasti. Epämääräinen nimi pakottaa lukemaan kuvauksen tarkasti, mitä malli ei aina tee.

Hyödyllinen malli on käyttää vakiintuneita verbietuliitteitä.

• list_*, search_* ja get_* lukemiseen.
• create_*, update_* ja delete_* kirjoittamiseen.
• analyze_* ja summarize_* laskentaan.

Palvelimen yhdenmukaisuus auttaa LLM:ää muodostamaan toimintamalleja.

Periaate 2: kuvaukset ovat kehotteita

Työkalukuvaus on palvelimen tärkein teksti. Sen avulla LLM päättää, käytetäänkö työkalua ja miten.

Huono kuvaus:

search_customers: Search the customer database.

Parempi kuvaus:

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.

Parempi versio:

• Kuvaa syötteet eli nimen, sähköpostin tai yrityksen.
• Kuvaa tuotoksen eli enintään 10 osuvaa asiakasta perustietoineen.
• Kertoo käyttötilanteen eli käyttäjän tarkoittaman asiakkaan tunnistamisen.
• Kertoo, milloin sitä ei käytetä, vaan valitaan tarkkaan tunnistehakuun get_customer_by_id.

”Milloin ei käytetä” on kriittinen tieto. Muuten LLM saattaa valita search_customers-työkalun, vaikka get_customer_by_id sopisi paremmin.

Periaate 3: parametrikuvauksilla on merkitystä

Jokainen parametri tarvitsee kuvauksen. Pelkkä nimi ei riitä.

Huono:

{
  customer_id: string,
  fields: string[]
}

Parempi:

{
  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."
}

Kuvaukset:

• Kertovat LLM:lle, miten arvo hankitaan.
• Määrittävät tarvittaessa sallitut arvot.
• Ilmoittavat oletusarvot.

Periaate 4: virheet ohjaavat palautumista

Virheilmoitus ohjaa LLM:n seuraavaa toimintoa. Epämääräiset virheet johtavat agentin sekaannukseen.

Huono virhe:

{ "error": "Invalid input" }

Parempi virhe:

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

LLM tietää nyt:

• Mikä epäonnistui eli sähköpostikentän validointi.
• Miten se korjataan eli käyttämällä kelvollista sähköpostimuotoa.
• Mitä tehdään seuraavaksi eli pyydetään käyttäjältä kelvollinen osoite.

Ensimmäisen virheen jälkeen agentti voi toistaa saman kutsun, luovuttaa tai keksiä kelvollisen syötteen. Toinen johtaa hallittuun käyttäjävuorovaikutukseen.

Periaate 5: tuotos ohjaa seuraavaa toimintoa

Työkalun tuotos määrittää LLM:n seuraavan toiminnon. Tuotossuunnittelu vaikuttaa agentin toimintaan.

Huono hakutuotos:

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

Parempi tuotos:

{
  "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."
}

Parempi tuotos:

• Käyttää luettavia kenttänimiä.
• Sisältää metakontekstin (total_found).
• Sisältää luonnollisen kielen summary-kentän, joka auttaa LLM:ää muotoilemaan seuraavan vastauksen.

Yhteenvetokenttä antaa LLM:lle lisävihjeen tuloksen tulkinnasta.

Periaate 6: yksi työkalu, yksi asia

Useita asioita tekevät työkalut hämmentävät LLM:ää. Sen täytyy päättää sekä työkalun käytöstä että toimintatilasta.

Hämmentävä:

manage_customer:
  - mode: "search" | "get" | "update" | "delete"
  - params: depends on mode

LLM valitsee usein väärän tilan. Myös parametriskeema monimutkaistuu, koska se vaihtelee tilan mukaan.

Parempi: erilliset työkalut.

search_customers: search by name/email/company
get_customer: get details by ID
update_customer: update specific fields
delete_customer: archive a customer

Jokainen työkalu on yksiselitteinen ja skeema yksinkertainen. LLM valitsee tarkoitukseen sopivan työkalun.

Työkaluja tulee enemmän, mutta kukin on selkeämpi. LLM käsittelee 10 selkeää työkalua paremmin kuin 3 monitoimityökalua.

Periaate 7: rajoita syötteitä

Rajaa syötevaihtoehdot mahdollisuuksien mukaan. Enum-arvot ja validointi ehkäisevät hallusinaatioita.

Väljä:

{
  status: string  // could be anything
}

Rajoitettu:

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

Skeematason rajoite estää rajoitetussa generoinnissa LLM:ää tuottamasta virheellisiä arvoja.

Sama koskee toimintojen, vakavuuksien, tyyppien ja muiden tunnettujen arvojoukkojen enum-arvoja.

Käytä päivämäärille ISO 8601 -muotoa ja ilmoita se kuvauksessa (”Date in ISO 8601 format, e.g., 2026-05-15”). Muuten LLM tuottaa satunnaisia muotoja.

Periaate 8: oletusarvot vähentävät hallusinaatioita

Tee järkevällä oletusarvolla varustetuista parametreista valinnaisia ja sovella oletus palvelimella.

Huono:

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

LLM joutuu valitsemaan kaikki arvot ja voi valita väärin.

Parempi:

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

LLM määrittää vain kyselyn kannalta merkitykselliset parametrit. Vähemmän parametreja jättää vähemmän tilaa sekaannukselle.

Dokumentoi oletukset: ”Limit: number of results to return. Default 10, max 50.”

Periaate 9: yhdisteltävyydellä on merkitystä

Työkalujen pitäisi yhdistyä työnkuluiksi, joita LLM voi rakentaa. Oikea tarkkuustaso helpottaa monimutkaisia tehtäviä.

Esimerkkitehtävä: ”Kerro 3 arvokkaimman asiakkaamme kaikista avoimista ongelmista.”

Huono työkalujoukko:

get_customer_summary(customer_id): returns customer + tickets + activity all in one

Työkalu palauttaa yhden asiakkaan kaiken tiedon, joten ”top 3” -suodatus ei onnistu helposti. LLM:n pitää ensin tunnistaa tärkeimmät asiakkaat ja kutsua työkalua 3 kertaa.

Parempi työkalujoukko:

list_customers(sort_by="value", limit=N): returns customer summaries with priority info
list_tickets(customer_id, status): returns tickets for a customer

LLM voi listata tärkeimmät asiakkaat ja sitten kunkin avoimet tukipyynnöt. Yhdistelmä on luonteva.

Ajattele usean työkalun työnkulkuja. Hyvin yhdistyviä työkaluja käytetään; huonosti yhdistyviä ei usein käytetä.

Periaate 10: idempotenssista viestitään

Mainitse kirjoitustyökalun kuvauksessa idempotenssivaatimukset:

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.

LLM tietää luoda UUID:n ja käyttää samaa uudelleenyrityksessä.

Ilman ohjetta se voi jättää avaimen pois tai luoda jokaiseen yritykseen uuden UUID:n, mikä kumoaa tarkoituksen.

Periaate 11: mainitse esi- ja jälkiehdot

Kerro työkalun ennakkoehdoista ja merkittävistä sivuvaikutuksista:

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 tietää, mitä tarkistaa ennen kutsua ja mitä odottaa sen jälkeen. Se voi suunnitella monivaiheisen työnkulun oikein, esimerkiksi sulkea ensin tukipyynnöt ja poistaa vasta sitten.

Periaate 12: käytä epäselvissä tapauksissa esimerkkejä

Monimutkaisen työkalun kuvaukseen lisätty esimerkki auttaa:

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

Esimerkit opettavat LLM:lle rakenteen skeemaa tehokkaammin.

Periaate 13: älä paljasta sisäistä toteutusta

LLM:n ei tarvitse tuntea tietokantarakennetta tai sisäisiä tunnisteita. Tarjoa selkeä käsitemalli.

Huono:

get_user_by_pk(pk: number)

LLM:n pitäisi tuntea tietokannan pääavaimen käsite.

Parempi:

get_user(user_id: string)

Piilota tietokantakäsite. LLM käyttää merkityksellistä user_id-tunnistetta.

Älä tarjoa vanhentuneita kenttiä, sisäisiä lippuja, virheenselvitysparametreja tai muita toteutukseen käyttäjäkäsitteen sijaan liittyviä asioita.

Periaate 14: vältä maagisia merkkijonoja

Komentojen tai koodien kaltaiset merkkijonot ovat virhealttiita.

Huono:

modify_record(record_id: string, change_string: string)
// where change_string is like "field1=value1;field2=value2"

LLM joutuu koodaamaan muutokset tiettyyn merkkijonomuotoon ja tekee virheitä.

Parempi:

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

Objektina annettavissa rakenteisissa päivityksissä LLM voi käyttää kenttiä suoraan.

Periaate 15: testaa todellisilla LLM-malleilla

Ihmisen mielestä selkeä työkalukuvaus voi hämmentää LLM:ää. Vain testaamalla saat tietää.

Hyödyllinen työnkulku:

1. Rakenna työkalu.
2. Anna LLM-agentin yrittää useita realistisia tehtäviä vain työkaluillasi.
3. Tarkkaile epäonnistumisia.
4. Muokkaa kuvauksia havaintojen perusteella.
5. Toista.

Havaittavia malleja:

• LLM käyttää väärää työkalua → nimi tai kuvaus on epäselvä.
• LLM antaa vääriä parametriarvoja → parametrikuvaus tai skeema kaipaa korjausta.
• LLM luovuttaa virheen jälkeen → virheilmoitusta pitää parantaa.
• LLM ei kokeile hyödyllistä työkalua → työkalun esilletuonti tai nimi on huono.

Jokainen ongelma viittaa täsmälliseen korjaukseen.

Diagnostiikka: huonosti suunniteltujen työkalujen merkit

Seuraavat mallit kertovat suunnitteluongelmista:

LLM käyttää usein väärää työkalua. Se kutsuu search_customers, vaikka oikea olisi get_customer_by_id. Korjaus: selvennä työkalujen käyttötilanteet.

LLM kutsuu monta työkalua yhtä asiaa varten. Se käyttää 5 kutsua asiaan, jonka pitäisi vaatia 1. Korjaus: harkitse korkeamman tason yhdistelmätyökalua tai karkeampaa tarkkuustasoa.

LLM luovuttaa virheen jälkeen. Se yrittää kerran ja kertoo käyttäjälle, ettei voi auttaa. Korjaus: lisää seuraavaa vaihetta ehdottava virheilmoitus.

LLM hallusinoi parametriarvoja. Se keksii user_id-tunnisteita, päivämääriä tai muita tunnisteita. Korjaus: kerro arvojen hankintatapa, lisää rajoitteita sekä havaitseva ja selittävä virheenkäsittely.

LLM toistaa saman epäonnistuneen kutsun. Sama virhe toistuu. Korjaus: kerro virheilmoituksessa täsmällisesti, mikä on väärin.

LLM ei käytä tehokasta työkalua. Erinomaista työkalua ei koskaan kutsuta. Korjaus: paranna löydettävyyttä selkeällä nimellä, kuvauksella ja ”käytä tätä, kun…” -ohjeella.

Työkalutaksonomia

Hyödyllinen harjoitus on järjestää työkalut taksonomiaan.

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

Taksonomia auttaa:

• Soveltamaan oikeita suojauksia, kuten idempotenssia ja tuhoavien toimien vahvistusta.
• Dokumentoimaan luokat LLM:n järjestelmäkehotteessa.
• Havaitsemaan puuttuvat työkalut.

Hyödyllinen lisä järjestelmäkehotteeseen:

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.

Tämä ohjaa LLM:n työkalukäyttöä koko työnkulun tasolla, ei vain yksittäisissä kutsuissa.

Esimerkkejä tavallisista parannuksista

Ennen- ja jälkeen-esimerkit konkretisoivat periaatteet:

Esimerkki 1: hakutyökalu

Ennen:

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

Jälkeen:

{
  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."
    }
  }
}

Esimerkki 2: toimintotyökalu

Ennen:

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

Jälkeen:

{
  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."
    }
  }
}

Jälkeen-versiot ohjaavat LLM:ää paljon tehokkaammin. Ne vaikuttavat monisanaisilta mutta ovat sen arvoisia.

Yhteenveto

LLM-työkalujen suunnittelu on oma tieteenalansa. Periaatteet eivät ole itsestään selviä, vaan edellyttävät LLM:n käsittelemistä käyttäjänä ja käyttöliittymän suunnittelua sen mukaisesti.

Olennaiset mallit:

• Toimintaverbeihin perustuvat nimet.
• Monipuoliset kuvaukset siitä, mitä, milloin ja milloin ei.
• Parametrikohtaiset kuvaukset esimerkkeineen ja rajoitteineen.
• Rakenteiset, toimintakelpoiset virheilmoitukset.
• Seuraavaa toimintoa ohjaavat tuotokset.
• Yksi käsite työkalua kohti.
• Järkevät oletusarvot.
• Yhdisteltävä tarkkuustaso.
• Selkeästi kuvattu idempotenssi.
• Dokumentoidut esi- ja jälkiehdot.
• Esimerkit monimutkaisille työkaluille.
• Piilotettu sisäinen toteutus.
• Testaus todellisilla LLM-malleilla.

Useimmat MCP-palvelimet eivät epäonnistu vaikean protokollan vaan LLM:ää huomioimattoman työkalusuunnittelun vuoksi. Oikein suunniteltu palvelin on tehokas; väärin suunniteltu tekee kehittyneestä taustajärjestelmästä hukkaan heitetyn investoinnin.

Käsittele LLM:ää käyttäjänä ja suunnittele sen mukaisesti. Investointi maksaa itsensä moninkertaisesti takaisin työkalujen parempana käyttönä.