Milyen hosszú legyen egy eszközleírás?

Az Anthropic eszközönként legalább három-négy mondatot javasol, összetett eszköznél többet: mit csinál az eszköz, mikor kell használni és mikor nem, mit jelent az egyes paraméter, és mik a korlátai. Egy egysoros leírás, például „Lekéri egy ticker árfolyamát”, találgatásra kényszeríti a modellt.

Hány eszközt bír el egy ágens?

Az OpenAI azt javasolja, hogy egy forduló elején 20-nál kevesebb függvény legyen elérhető. Az Anthropic szerint a Claude eszközválasztása 30–50 eszköz felett romlik, és 10 vagy több eszköznél, illetve 10 000 tokennél nagyobb definícióknál tool searchöt ajánl. E felett igény szerint töltsd be az eszközöket, ne mind előre.

Kivételként dobjam az eszközhibát, vagy adjam vissza a modellnek?

A végrehajtási hibákat add vissza a modellnek eszközeredményként, a Claude API-nál is_error true, MCP-ben isError true jelzéssel, hogy javítani tudja magát. Az MCP-specifikáció a JSON-RPC protokollhibákat az ismeretlen eszközökre és a hibás formátumú kérésekre tartja fenn, ezekből a modellek ritkábban tudnak helyreállni.

Jobb, ha minden API-végponthoz külön eszköz van?

Általában nem. Az Anthropic nem javasolja, hogy minden végpontot becsomagolj, inkább a többlépéses munkát vond össze egy eszközbe, az OpenAI pedig azt mondja, hogy a mindig egymás után hívott függvényeket egyesítsd. Kevesebb, de képesebb eszköz kevesebb választási hibát okoz és kontextust is spórol.

Megbízhatok az MCP-eszközannotációkban, például a read-only jelzésben?

Alapból nem. Az MCP-specifikáció szerint a kliensnek megbízhatatlannak kell tekintenie az eszközannotációkat, hacsak nem megbízható szervertől származnak. Megjelenítéshez és tippként használd őket, de a jogosultságokat, a megerősítéseket és a rate limiteket a saját kódodban érvényesítsd.

Eszközök tervezése AI-ágenseknek

Amikor egy ágens rosszul viselkedik, az első ösztön a rendszerprompt átírása. A probléma gyakran egy réteggel lejjebb van, az eszközökben: egy név, amely kétfélét is jelenthet, egy leírás, amely sosem mondja meg, mikor ne használd, egy user nevű paraméter, amely bármit elfogad, egy keresés, amely 40 000 token JSON-t ad vissza, vagy egy hiba, amely csak annyit mond: „failed”. A modell mindezt minden fordulóban elolvassa, és csak annyira lehet jó, amennyire az, amit olvas.

Ez az útmutató összegyűjti, mit mond az Anthropic, az OpenAI és az MCP-specifikáció az eszköztervezésről, és konkrét szabályokká alakítja: milyen eszközöket építs, hogyan nevezd el és írd le őket, hogyan formáld a sémát, hogy nehéz legyen hibázni, mit adj vissza, hogyan jelezd a hibát, hogy a modell helyreálljon, és mit tegyél, ha az eszközlista néhány tucat fölé nő. A példák olyan B2B-webshop- és back-office-ágensekből származnak, amilyeneket építek.

Az eszközdefiníciók promptok

A Claude API-nál a tools paraméterből rendszerprompt lesz: az API az eszközdefiníciókból, az eszközkonfigurációból és a saját rendszerpromptodból egy speciális promptot állít össze. A nevek, a leírások és a paraméterleírások tehát a szó legszorosabb értelmében utasítások. Az Anthropic dokumentációja a rendkívül részletes leírást „messze a legfontosabb tényezőnek” nevezi az eszközök teljesítményében, a 2024. decemberi Building effective agents esszé pedig arról számol be, hogy a csapat a SWE-bench-ágensénél több időt töltött az eszközök optimalizálásával, mint a teljes promptéval.

Ugyanez az esszé nevet is ad a szakmának: az ágens–számítógép interfészt (ACI) ugyanolyan gondosan kell megtervezni, mint egy emberi felületet, és bele kell helyezkedni a modell helyzetébe. Az OpenAI változata a gyakornokteszt: használná-e helyesen a függvényt valaki, aki csak azt látja, amit a modell? Ha a válaszhoz beszélgetni kellene veled, a definíció hiányos.

Feladatokra építs eszközt, ne végpontokra

A leggyakoribb hiba, hogy minden REST-végponthoz külön eszközt generálunk. Az Anthropic 2025. szeptemberi, eszközírásról szóló cikke kertelés nélkül kimondja, hogy több eszköz nem mindig vezet jobb eredményre, és példaként egy schedule_event eszközt hoz, amely megkeresi a szabad időpontot és lefoglalja a megbeszélést, ahelyett hogy az ágensnek külön list_users, list_events és create_event eszközt kellene egymás után hívnia. Az OpenAI a másik oldalról mondja ugyanezt: a mindig egymás után hívott függvényeket vond össze, és egy forduló elején 20-nál kevesebb függvény legyen elérhető.

Végpontra szabott	Feladatra szabott	Miért segít
`get_customer`, `list_orders`, `get_order_lines`	`get_customer_context(customer_id)`	Egy hívás visszaadja, ami egy supportkérdés megválaszolásához kell
`list_products` + client-side filtering	`search_products(query, filters, limit)`	A szűrés a kódban történik, nem a kontextusablakban
`create_pr`, `review_pr`, `merge_pr`	`pull_request(action, ...)`	Az Anthropic javaslata: a rokon műveleteket egy action paraméter mögé gyűjtsd
`read_logs` (full dump)	`search_logs(query, since, context_lines)`	A releváns sorokat adja vissza környezettel, nem mindent

Az összevonásnak határa van: egyetlen do_anything(json) eszköz minden döntést egy argumentumba rejt, és lehetetlenné teszi a jogosultságkezelést. Én a kockázat mentén vágok. Az olvasás lehet tág; az írás, a fizetés és minden visszafordíthatatlan művelet saját, szűk sémájú eszközt kap, hogy egy jóváhagyási kapu, ahogy a human in the loop AI-ágenseknél cikkben leírtam, pontosan rájuk célozhasson.

Nevek és névterek

Amint egy ágens több szolgáltatás eszközeit látja, a nevek ütköznek: search a CRM-ből, search a wikiből, search a webshopból. Mindkét Anthropic-forrás szolgáltatás és erőforrás szerinti előtagot javasol, például github_list_prs vagy slack_send_message, az eszközírásról szóló cikk pedig hozzáteszi, hogy az előtagos és utótagos sémák mérhetően más eredményt adnak, ezért teszteld a sajátodat. A technikai korlátok bőkezűek: a Claude API a ^[a-zA-Z0-9_-]{1,128}$ mintának megfelelő neveket fogadja el, az MCP-specifikáció szerint pedig a nevek 1–128 karakteresek, kis- és nagybetűérzékenyek, szerverenként egyediek legyenek, és betűkből, számjegyekből, aláhúzásból, kötőjelből és pontból álljanak.

A paraméternevek ugyanilyen gondosságot érdemelnek. Az Anthropic példája apró, de mindenhová érdemes átvenni: user nevű paraméter helyett user_id. Webshopban ebből sku, article_number vagy product_id lesz; azt válaszd, amit a felhasználóid mondanak, és a formátumot írd le a paraméter leírásában.

Leírások, amelyek alapján a modell cselekedni tud

Az Anthropic ellenőrzőlistája egy leíráshoz: mit csinál az eszköz, mikor kell és mikor nem szabad használni, mit jelent az egyes paraméter és hogyan változtatja a viselkedést, valamint a fontos megkötések, például hogy mit nem ad vissza az eszköz. Eszközönként legalább három-négy mondatot kér. Az eszközírásról szóló cikk egy új kolléga betanításaként írja le: tedd kimondottá a kimondatlan tudást, a lekérdezési formátumokat, a szakzsargont és az erőforrások kapcsolatait is.

{
  "name": "shop_search_products",
  "description": "Searches the B2B catalogue by keyword, part number or attribute and returns up to `limit` matching products with name, SKU, price for the current customer and stock status. Use it when the user asks about products, availability or alternatives. Do not use it for order history (use shop_get_orders) or for prices of other customers. Exact part numbers such as 'ART-10001' match only when passed in `sku`, not in `query`. Results are sorted by relevance; if there are more, the response contains `next_cursor`.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Free-text search in German or English, e.g. 'Edelstahl Schraube M8'" },
      "sku": { "type": "string", "description": "Exact SKU, e.g. 'ART-10001'. Overrides query." },
      "in_stock_only": { "type": "boolean", "description": "Only return products available now. Default false." },
      "limit": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Default 10." },
      "response_format": { "type": "string", "enum": ["concise", "detailed"], "description": "concise: name, SKU, price, stock. detailed: adds attributes and documents." }
    },
    "additionalProperties": false
  },
  "input_examples": [ { "query": "Edelstahl Schraube M8", "in_stock_only": true }, { "sku": "ART-10001" } ]
}

Összetett bemenetekhez a Claude API elfogadja az input_examples mezőt: példabemenetek tömbjét, amelyeknek meg kell felelniük a sémának, különben a kérés 400-zal elbukik. Egyszerű példánként nagyjából 20–50, beágyazott objektumoknál 100–200 tokenbe kerülnek. Az OpenAI egy megfontolandó figyelmeztetést tesz hozzá: a példák a hagyományos modelleknek segítenek, a gondolkodó modelleknél viszont ronthatják a teljesítményt, ezért mérj, mielőtt megtartod őket.

Sémák, amelyek megnehezítik a hibázást

A Building effective agents a gyártásból kölcsönöz egy fogalmat: poka-yoke az eszközöknek, vagyis úgy módosítani az argumentumokat, hogy nehezebb legyen hibázni. A példa konkrét. A SWE-bench-ágens könyvtárváltás után rendre elrontotta a relatív fájlútvonalakat, ezért a csapat úgy módosította az eszközt, hogy abszolút útvonalat követeljen, és a modell ezután hibátlanul használta. Ugyanez az ötlet más formákban:

Enum szabad szöveg helyett. Az OpenAI ellenpéldája a toggle_light(on: bool, off: bool), amely érvénytelen állapotokat is enged; egyetlen state enum nem.
Ne kérd azt, amit a kód tud. Ha a munkamenet már ismeri az ügyfelet és a rendelést, a kódban add hozzá. OpenAI: ne töltesd ki a modellel azokat az argumentumokat, amelyeket már tudsz.
Kapcsold be a strict mode-ot. Az OpenAI azt javasolja, hogy mindig legyen bekapcsolva; additionalProperties: false kell hozzá, és minden property a required listában, az opcionális mezők nullable típussal. A Claude API-nál a strict: true garantálja, hogy a bemenet megfeleljen a sémának.
Magyarázatot kérj, ne gondolatmenetet. Az Anthropic figyelmeztet, hogy egy olyan paraméter, amely a modell lépésenkénti gondolkodását kéri, elutasítást válthat ki; helyette rövid magyarázatot vagy bizonyítékot kérj.

A szigorú séma a formát garantálja, nem az igazságot. Egy érvényes cikkszámformátum is jelölhet nem létező terméket, ezért a szervernek validálnia kell, és használható hibát kell visszaadnia. A sémakényszerítés garanciáit és hézagait a strukturált kimenetek JSON Schemával cikk írja le.

Válaszok: sok jel, kevés token

Bármit ad vissza egy eszköz, az a kontextusablakba kerül, és ott marad a futás végéig. Az Anthropic tanácsa, hogy csak nagy jelértékű információt adj vissza, és azt találták, hogy a tetszőleges alfanumerikus UUID-k értelmes nevekre cserélése javította a pontosságot visszakeresési feladatokban. Egy response_format enumot is javasolnak, hogy az ágens választhasson: a Slack-példában a részletes válasz 206, a tömör 72 tokent használt, nagyjából a harmadát. Mindenhez, ami nagy lehet, tegyél lapozást, tartománykiválasztást, szűrést vagy csonkítást észszerű alapértékekkel; összehasonlításként a Claude Code alapból 25 000 tokenben korlátozza az eszközválaszokat.

Minden doboz olyan pont, ahol az eszköz tervezője, nem a modell dönti el, mennyire valószínű, hogy a következő lépés jól sikerül.

A nagy eredmények a kontextusromlás hosszan futó ágenseknél fő okai is. Egy eszköz, amely kurzort és az első tíz találatot adja vissza, most olcsóbb, és ötven fordulóval később is élesebben tartja az ágenst.

A hibaüzenet utasítás

Egy eszközhiba a következő prompt, amelyet a modell elolvas, ezért úgy is írd meg. A Claude API a végrehajtási hibát normál tool_result-ként szállítja is_error: true jelzéssel, és az Anthropic tippje konkrét: általános „failed” helyett mondd meg, mi romlott el és mit próbáljon legközelebb, például „Rate limit exceeded. Retry after 60 seconds.” Érvénytelen hívásnál, például hiányzó paraméternél, a Claude kétszer-háromszor újrapróbálja javításokkal, mielőtt bocsánatot kérne a felhasználótól, így egy pontos üzenet általában megmenti a futást.

// Bad: the model learns nothing
{ "type": "tool_result", "tool_use_id": "toolu_01", "is_error": true, "content": "Error 422" }

// Good: what failed, why, and the next valid move
{ "type": "tool_result", "tool_use_id": "toolu_01", "is_error": true,
  "content": "No product with sku 'ART-1001'. SKUs have 5 digits after 'ART-'. Closest matches: ART-10010 (Edelstahl Schraube M8), ART-10011 (M10). Call shop_search_products with sku set to one of these, or with query if the user gave a description." }

Az MCP formálisan is meghúzza ugyanezt a határt. A specifikáció elválasztja a protokollhibákat, vagyis a szabványos JSON-RPC hibákat ismeretlen eszközre, hibás formátumú kérésre és szerverhibára, az eszköz-végrehajtási hibáktól, amelyeket az eredményen belül isError: true jelez: API-hibák, bemenet-validálási hibák, például rossz formátumú dátum, és üzleti logikai hibák. A kliensnek a végrehajtási hibákat tovább kell adnia a modellnek, hogy önmagát javíthassa; a protokollhibákból ritkábban lesz helyreállás.

Amikor nő az eszközlista

Néhány MCP-szerver bekötésével gyorsan száz eszköz gyűlik össze. Az Anthropic számszerűsíti a költséget: egy GitHubot, Slacket, Sentryt, Grafanát és Splunkot használó tipikus beállítás bármilyen munka előtt körülbelül 55 000 token definíciót fogyaszthat, és a Claude eszközválasztó képessége 30–50 elérhető eszköz felett romlik. A tool search eszköz mindkettőre választ ad. Minden definíciót elküldesz, a legtöbbet defer_loading: true jelzéssel, a Claude pedig regexszel vagy BM25-tel keres a nevekben, leírásokban és argumentumnevekben, és csak a találatokat tölti be, jellemzően hármat-ötöt, ami az Anthropic szerint több mint 85 százalékkal csökkenti a definíciós tokeneket.

Mikor válts: az Anthropic 10 vagy több eszköznél, 10 000 token feletti definícióknál vagy több MCP-szervernél javasolja a tool searchöt; 10 alatti, mindig használt eszközöket töltsd be normálisan.
A gyakoriak maradjanak betöltve: a három-öt leggyakrabban használt eszközt ne halaszd.
Írj a keresőnek: az egységes előtagokkal egy lekérdezés egy egész szolgáltatást eltalál; a leírásokban a felhasználók szavait használd.
A cache ép marad: a halasztott eszközök nincsenek a prompt előtagjában, így egy eszköz felfedezése nem érvényteleníti a prompt cache-t.

Az MCP-szerverek, CLI-k és skillek közötti tágabb választást kódolóágenseknél az AGENTS.md, skillek, MCP vagy CLI cikk tárgyalja.

Az eszközök támadási felületet jelentenek

Az eszközeredmények gyakran olyan tartalmat hoznak, amely felett nincs kontrollod: weboldalak, beérkező e-mailek, feltöltések, harmadik féltől származó API-k. Az Anthropic dokumentációja szerint ezt a tartalmat megbízhatatlannak kell tekinteni, mert a modellnek szóló utasításokat rejthet, és tool_result blokkokban kell tartani, nem a rendszerpromptban vagy sima felhasználói szövegben. Az MCP-specifikáció hozzáteszi, hogy a kliensnek megbízhatatlannak kell tekintenie az eszközannotációkat, hacsak nem megbízható szervertől jönnek, hogy a szervernek minden bemenetet validálnia, a hozzáférést szabályoznia, a hívásokat korlátoznia és a kimeneteket tisztítania kell, és hogy egy embernek meg kell tudnia tagadni az eszközhívásokat.

A gyakorlatban: a jogosultság az eszköz implementációjába kerüljön, ne a leírásába; írási műveletekhez kérj megerősítést; és soha ne kombináld terv nélkül egy ágensben a privát adatot, a megbízhatatlan tartalmat és egy kimenő csatornát. A mintákat a halálos hármas és hat tervezési minta cikk, a szerveroldali ellenőrzéseket az MCP biztonsági ellenőrzőlista tartalmazza.

Értékeld ki az eszközöket, aztán iterálj

Az Anthropic eszközírásról szóló cikkének leghasznosabb része a folyamat: építs gyors prototípust, írj valósághű értékelési feladatokat, amelyekhez sok eszközhívás kellhet, futtasd le őket, és olvasd el az átiratokat. A feladat sikere mellett kövesd az összes eszközhívást, a tokeneket, a futásidőt és az eszközhibákat, és tarts félre egy tesztkészletet, hogy ne a saját tesztjeidre hangold túl a leírásokat. A felesleges hívások hiányzó lapozásra vagy szűrőre utalnak; az ismétlődő érvénytelen argumentumok homályos leírásra vagy olyan sémára, amely engedi a hibát.

Hogy magukat a futásokat, a trajektóriákat és az eredményeket hogyan pontozd, arról az AI-ágensek értékelése szól. Az eszközök körüli ciklus működéséhez kezdd az ágensciklus magyarázatával.

Eszközök tervezése AI-ágenseknek: nevek, leírások, sémák és hibaüzenetek

A lényeg röviden