# Tool-descriptions schrijven: de prompt je agent nooit leest [Naar de inhoud](#lm-inhoud)Netwerk/NL[EN](/en/)[Hubhub.llmnet.nlModellen vergelijken op taak, taal, kosten en licentie.](https://hub.llmnet.nl/)[Communitycommunity.llmnet.nlPrompttechnieken, patronen en systeemprompts.](https://community.llmnet.nl/)[APIapi.llmnet.nlLLM's robuust in software: rate limits, routing, structured output.](https://api.llmnet.nl/)[Consultancyconsultancy.llmnet.nlAI invoeren in een organisatie, van pilot tot productie.](https://consultancy.llmnet.nl/)[Nieuwsnieuws.llmnet.nlOntwikkelingen in AI, geduid voor Nederland.](https://nieuws.llmnet.nl/)[Benchmarkbenchmark.llmnet.nlZelf meten wat AI-kwaliteit is, voor jouw taken.](https://benchmark.llmnet.nl/)[Vacaturesvacatures.llmnet.nlAI-rollen, salarissen en carrièrepaden in Nederland.](https://vacatures.llmnet.nl/)[Lerenleren.llmnet.nlAI-concepten in gewoon Nederlands, van beginner tot bouwer.](https://leren.llmnet.nl/)[Gidsgids.llmnet.nlAI privé draaien op eigen Mac, pc, NAS of thuisserver.](https://gids.llmnet.nl/)[Directorydirectory.llmnet.nlHet AI-ecosysteem in kaart: tools, modellen, bedrijven.](https://directory.llmnet.nl/)[Radarradar.llmnet.nlSignalen uit X, onderzoek en communities voor indie developers.](https://radar.llmnet.nl/)[llmnet.nl — hoofdsite](https://llmnet.nl/)[](https://x.com/intent/post?url=https%3A%2F%2Fcommunity.llmnet.nl%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&text=Tool-descriptions%20schrijven%3A%20de%20prompt%20je%20agent%20nooit%20leest)[](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcommunity.llmnet.nl%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest)[](https://www.reddit.com/submit?url=https%3A%2F%2Fcommunity.llmnet.nl%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&title=Tool-descriptions%20schrijven%3A%20de%20prompt%20je%20agent%20nooit%20leest)[](#)[](https://x.com/intent/post?url=https%3A%2F%2Fcommunity.llmnet.nl%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&text=Tool-descriptions%20schrijven%3A%20de%20prompt%20je%20agent%20nooit%20leest)[](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcommunity.llmnet.nl%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest)[](https://www.reddit.com/submit?url=https%3A%2F%2Fcommunity.llmnet.nl%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&title=Tool-descriptions%20schrijven%3A%20de%20prompt%20je%20agent%20nooit%20leest)[](#) # Tool-descriptions schrijven: de prompt je agent nooit leest Door Ivo Donker — samengesteld met AI-ondersteuning · 7 augustus 2026 ```python?code_reference&code_event_index=1 import sys # Let's draft a complete HTML article in python to ensure exact formatting, word count, link constraints, and requirements. article_html = """Wanneer een Large Language Model (LLM) beslist om een externe tool aan te roepen, kijkt het niet naar de onderliggende Python-code, de REST-API-implementatie of de interne logica van de functie. Het model ziet uitsluitend de JSON-schema-definitie en de bijbehorende tekstuele beschrijving (de description). In agentische systemen blijkt een gebrekkige tool-description veruit de meest voorkomende oorzaak van mislukte toolcalls, verkeerde argumentwaarden of ongewenste side effects. Zonder een heldere en duidelijke beschrijving tast de agent in het duister. Dit artikel behandelt het systematisch schrijven van effectieve tool-descriptions, de balans tussen tokenbudget en precisie, en hoe je deze beschrijvingen test en onderhoudt als volwaardige code-artefacten. ## 1. Waarom de description de cruciale schakel is In een traditionele softwarearchitectuur roept een ontwikkelaar een functie direct aan via een expliciete signatuur en typedefinitie. Bij agent-gebaseerde systemen fungeert het taalmodel als de dynamic router. De agent beslist op basis van de gebruikerscontext en de lijst met beschikbare tools welke actie ondernomen moet worden. Aangezien de code achter de schermen onzichtbaar is voor het model, vormt de description de enige interface tussen de intentie van de agent en de uitvoering van de code. Wanneer een tool-description vage of onvolledige informatie bevat, ontstaan er drie specifieke faalpatronen: - Verkeerde toolselectie: De agent kiest de verkeerde tool voor een taak, of negeert de tool juist wanneer deze wél nodig is. - Ongeldige of foutieve argumenten: Het model gokt het formaat van parameters, zoals het meegeven van een datum als UNIX-timestamp in plaats van een ISO-8601 string, of het weglaten van verplichte eenheden. - Onverwachte bijwerkingen: De agent roept een kostbare of onomkeerbare schrijfactie aan zonder dat het model beseft dat de bewerking permanente wijzigingen aanbrengt. In het artikel over [prompt-patronen voor agents](https://community.llmnet.nl/prompt-patronen-voor-agents) behandelen we de algemene aanroeppatronen van tools, maar de kwaliteit van de individuele tool-description bepaalt uiteindelijk of die patronen in de praktijk standhouden. ## 2. De drie kerntaken van een tool-description Een goed geformuleerde description vervult drie afgebakende taken binnen de context van een agentic loop: ### a. Beslissen of de tool relevant is Het model moet binnen een fractie van een seconde beoordelen of een specifieke tool aansluit bij de huidige tussenstap. De beschrijving moet daarom in de eerste zin direct duidelijk maken wat de primaire functie is en, net zo belangrijk, wanneer de tool uitdrukkelijk niet gebruikt mag worden. Dit voorkomt dat tools met overlappende functionaliteit met elkaar concurreren. ### b. Argumenten correct invullen Hoewel JSON-schema's datatypes afdwingen (zoals string of integer), schieten standaardschema's vaak tekort voor semantische restricties. De description moet uitleggen wat de exacte betekenis van een parameter is, welk bereik toegestaan is, en in welke eenheid waarden worden verwacht (bijvoorbeeld seconden versus milliseconden, of EUR versus EUR-cents). ### c. Fouten en bijwerkingen vermijden Een agent moet vooraf weten wat de consequenties zijn van de toolcall. Is de actie alleen-lezen of worden er gegevens overschreven? Kan de aanroep falen bij een netwerkstoring, en wat betekent een lege return-waarde? Door eventuele randvoorwaarden en foutscenario's op te nemen, kan de agent na een mislukte aanroep beter herstellen. Tijdens het [agentic loops debuggen](https://community.llmnet.nl/agentic-loops-debuggen) herleiden we uiteenlopende faalpatronen tot onduidelijke randvoorwaarden in de description van de aangeroepen functies. ## 3. Anatomie van een effectieve tool-description Een gestructureerde tool-description bestaat uit vaste onderdelen. Het hanteren van een consistente opbouw helpt niet alleen het taalmodel om patronen te herkennen, maar vereenvoudigt ook de review door teamleden. ### Naamgeving van de tool De naam van de tool maakt formeel deel uit van het schema en dient als eerste filter voor het model. Gebruik een unieke combinatie van een werkwoord en een object (bijvoorbeeld get_user_profile of cancel_subscription). Vermijd algemene of dubbelzinnige namen zoals process_data of do_action. ### Wanneer wel en wanneer niet te gebruiken Begin de tekstuele beschrijving met het hoofddoel van de tool. Voeg daaraan toe in welke situaties de tool expliciet niet geschikt is. Als er een alternatieve tool bestaat voor een verwante taak, noem die naam dan expliciet. ### Parameter-specificaties Beschrijf per parameter niet alleen de naam, maar licht de semantiek toe: - Betekenis: Wat stelt het argument voor? - Eenheid en formaat: Denk aan YYYY-MM-DD voor datums of ISO-3166-1 alpha-2 voor landcodes. - Bereik en restricties: Minimale en maximale waarden, of toegestane opties als een opsomming niet direct in het JSON-schema past. - Optioneel vs. Verplicht: Wat is het gedrag als de waarde wordt weggelaten, en wat is de standaardwaarde (default)? ### Return values en side effects Geef aan wat de tool teruggeeft bij succes en wat de verwachte structuur van de respons is. Vermeld ook eventuele side effects: maakt de tool kosten op een externe API, duurt het uitvoeren lang, of stuurt het een e-mail naar een eindgebruiker? ### Edge cases en foutafhandeling Leg uit hoe de tool reageert op ongeldige invoer of ontbrekende gegevens. Als een zoekopdracht nul resultaten oplevert, geef dan aan of de tool een lege lijst retourneert of een foutmelding genereert. ## 4. De grenzen van de context: tokenbudget en modelgrootte Het schrijven van een tool-description is een balanceeract tussen volledigheid en efficiëntie. Elke tool-description die je toevoegt aan de API-aanroep consumeert tokens in de systeemcontext. Bij systemen met tientallen tools kan de gecombineerde omvang van de schema's duizenden tokens beslaan. Dit brengt kosten met zich mee en kan de verwerkingssnelheid (latency) nadelig beïnvloeden. Een veelgebruikte vuistregel in productie is een budget van 50 tot 150 woorden per tool-description. Voor eenvoudige verzoek-respons-tools is 50 woorden ruimschoots voldoende. Complexe tools met veel parameters of kritieke bijwerkingen kunnen tot 150 of 200 woorden vereisen. Het type model dat je inzet heeft directe invloed op hoe de description geformuleerd moet worden: - Grote modellen (bijv. 70B+ parameters of commerciële vlaggenschepen): Deze modellen hebben een sterke getrainde vaardigheid in implicit reasoning. Ze begrijpen contextuele hints en kunnen uit minimale beschrijvingen de juiste argumenten afleiden. Zie voor details over de technische verzending van verzoeken de documentatie over [function calling](https://api.llmnet.nl/function-calling) op de API-omgeving. - Kleine modellen (bijv. 3B tot 8B parameters in een homelab-setup): Kleinere modellen interpreteren tekst veel letterlijker en raken sneller in de war door vage formuleringen of overbodige randvoorwaarden. Voor kleinere modellen zijn korte, expliciete instructies en duidelijke 'Wanneer NIET te gebruiken'-clausules noodzakelijk om hallucinaties te voorkomen. Meer achtergrond hierover vind je in de gids over [prompting voor kleinere modellen](https://community.llmnet.nl/prompting-voor-kleinere-modellen). Houd bij het ontwerpen van je agentic architectuur bovendien rekening met het totale tokengebruik van alle geregistreerde toolset-schema's bij elkaar. Mocht de context te vol raken, overweeg dan dynamische tool-filtering of routing via een overkoepelende graph-structuur. ## 5. Veelvoorkomende fouten in de praktijk In de praktijk zien we regelmatig terugkerende fouten in tool-descriptions die eenvoudig te vermijden zijn: ### 1. Dubbelzinnige of overlappende toolnamen Als twee tools een vergelijkbare naam hebben, zoals fetch_user en get_user_details, kan het model niet betrouwbaar kiezen. Zorg voor duidelijke scheiding van verantwoordelijken of voeg beide functionaliteiten samen tot één robuuste functie. ### 2. Ontbrekende eenheden of indelingen Een parameter genaamd timeout zonder toelichting leidt gegarandeerd tot problemen. Bepaalde modellen vullen 30 in en bedoelen seconden, terwijl de onderliggende API milliseconden verwacht. Vermeld eenheden altijd expliciet in de description van de parameter. ### 3. Te lange lappen tekst Het toevoegen van volledige handleidingen of achtergrondverhalen in de description vervuilt de contextwindow en leid de aandacht af van de essentiële argumentstructuur. Beperk je tot de functionele kern. ### 4. Beloftes die de code niet waarmaakt Een beschrijving die claimt dat de tool "alle historische klantgegevens doorzoekt", terwijl de Python-code achter de tool slechts de laatste 30 dagen ophaalt, veroorzaakt foutieve aannames bij het model. De description en de daadwerkelijke code-implementatie moeten 100% synchroon blijven. ### 5. Verzwijgen van foutscenario's Als een tool bij een ontbrekende waarde een HTTP 404 retourneert, moet de description vermelden wat dit betekent. Anders kan het model aannemen dat het gehele systeem is uitgevallen, in plaats van simpelweg te concluderen dat de opgevraagde entiteit niet bestaat. ## 6. Testen van tool-descriptions Omdat tool-descriptions feitelijk prompts zijn die door de API worden verzonden, moeten ze met dezelfde zorgvuldigheid worden getest als je applicatiecode. Het testen van een description omvat drie fasen: ### Schema-validatie Controleer vooraf of het gegenereerde JSON-schema valide is en correct parseert conform de OpenAPI- of JSON Schema-specificatie. Maak hiervoor gebruik van de online [tool JSON Schema validator](https://benchmark.llmnet.nl/tool-json-schema-validator) om syntactische fouten uit te sluiten voordat je het schema in productie neemt. ### Distractie- en selectietesten Plaats de te testen tool in een lijst met 10 tot 20 andere geregistreerde tools. Voer prompts in die specifiek bedoeld zijn voor de doel-tool, evenals prompts die er dicht tegenaan zitten maar door een ándere tool moeten worden afgehandeld. Hiermee controleer je of de 'Wanneer NIET te gebruiken'-instructies naar behoren functioneren. ### Self-test via een test-harness Laat het model in een geautomatiseerde testomgeving de tool-keuze maken op basis van een set van 50 tot 100 realistisch geformuleerde gebruikersvragen. Bepaal via een evaluatiestap of het model de juiste tool kiest en de parameters in het juiste formaat invult. Door dit proces te automatiseren ontdek je regressies direct na een aanpassing aan de beschrijving. ## 7. Itereren en beheren: treat descriptions as code Een tool-description is geen statische tekst die je eenmalig schrijft en vervolgens vergeet. Naarmate je applicatie groeit en het gebruik van de agent varieert, zullen er randgevallen aan het licht komen. - Versiebeheer: Sla tool-schema's en descriptions op in dezelfde versiebeheermodule (zoals Git) als de onderliggende code. Een wijziging in een Python-functiesignatuur moet verplicht gepaard gaan met een commit die het JSON-schema en de description bijwerkt. Bekijk de aanbevelingen voor [prompt-versiebeheer](https://community.llmnet.nl/prompt-versiebeheer) voor praktische workflows. - Peer reviews: Laat een collega-ontwikkelaar de description lezen zonder de onderliggende code te tonen. Als de collega niet exact kan afleiden wat de functie doet en welke argumenten vereist zijn, zal het taalmodel daar hoogstwaarschijnlijk ook moeite mee hebben. Lees meer over dit proces in het artikel over [prompts reviewen in een team](https://community.llmnet.nl/prompts-reviewen-in-team). - Kwaliteitsmetingen: Monitor in productie het percentage mislukte toolcalls en ongeldige JSON-responses. Bepaal met behulp van [LLM-as-a-judge](https://benchmark.llmnet.nl/llm-as-a-judge) evaluaties of de foutoorzaak ligt bij de opbouw van de prompt of bij een onduidelijke tool-description. ## 8. Kopieerbaar artefact: Template, Checklist & Voorbeelden Gebruik de onderstaande structuur als leidraad bij het ontwerpen en controleren van je eigen tool-descriptions. ================================================================================ 1. TOOL DESCRIPTION TEMPLATE (JSON SCHEMA ANNOTATIE) ================================================================================ { "name": "[actie]_[entiteit]", "description": "[Eén heldere zin die de primaire functie beschrijft]. Gebruik deze tool wanneer [specifieke use-case]. Gebruik deze tool UITDRUKKELIJK NIET voor [alternatieve use-case, verwijst naar alternatieve_tool_naam]. Let op: [belangrijke bijwerking, kosten of restrictie].", "parameters": { "type": "object", "properties": { "param_naam": { "type": "string", "description": "[Betekenis van de parameter]. Indeling: [bijv. YYYY-MM-DD of ISO-code]. Bereik/Opties: [toegestane waarden]. Default: [standaardwaarde indien optioneel]." } }, "required": ["param_naam"] } } ================================================================================ 2. CHECKLIST VOOR TOOL-DESCRIPTIONS ================================================================================ [ ] Unieke en heldere naam (werkwoord + object)? [ ] Hoofddoel beschreven in de eerste zin? [ ] Expliciet vermeld wanneer de tool NIET gebruikt mag worden? [ ] Alle parameters voorzien van betekenis, formaat en eventuele eenheden? [ ] Duidelijk onderscheid gemaakt tussen verplichte en optionele parameters? [ ] Bijwerkingen (kosten, schrijfoperaties, latentie) vermeld? [ ] Foutgedrag en afhandeling van lege resultaten kort toegelicht? [ ] Lengte binnen het afgesproken tokenbudget (50-150 woorden)? [ ] JSON Schema gevalideerd tegen de specificatie? ================================================================================ 3. CONCREET VOORBEELD: SLECHT VS. GOED ================================================================================ --- SLECHT VOORBEELD --- { "name": "get_data", "description": "Haalt gegevens op uit het systeem over klanten.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "De zoekopdracht of ID." }, "time": { "type": "string", "description": "De tijd." } }, "required": ["query"] } } -- Ruimte voor fouten: Wat voor ID? Welk formaat heeft 'time'? Wat gebeurt er als er niets gevonden wordt? Is 'get_data' voor alle gegevens? --- GOED VOORBEELD --- { "name": "search_customer_orders", "description": "Zoekt historische bestellingen van een specifieke klant op basis van klant-ID of ordernummer. Gebruik deze tool wanneer een gebruiker vraagt om bestelstatus, factuurhistorie of artikelen uit een eerdere order. Gebruik deze tool NIET voor het opvragen van algemene productinformatie (gebruik daarvoor 'search_catalog') of het aanmaken van nieuwe bestellingen. Retourneert een lijst van maximaal 50 order-objecten. Bij geen resultaten wordt een lege lijst [] geretourneerd.", "parameters": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Het unieke klant-ID opgebouwd uit 'CUST-' gevolgd door 6 cijfers (bijv. CUST-123456)." }, "start_date": { "type": "string", "description": "Optionele begindatum voor het filteren van orders. Indeling volgens ISO-8601: 'YYYY-MM-DD'. Als deze wordt weggelaten, wordt gezocht vanaf 12 maanden geleden." }, "include_cancelled": { "type": "boolean", "description": "Geeft aan of geannuleerde bestellingen ook in het overzicht moeten worden opgenomen. Standaardwaarde is false." } }, "required": ["customer_id"] } } ## 9. Van tool-description naar agentic graph Het schrijven van een strakke tool-description is de basis voor een stabiele agentic workflow. Zonder heldere beschrijvingen faalt zelfs het meest geavanceerde taalmodel in het correct aanroepen van functies. Wanneer je individuele tool-descriptions op orde zijn, kun je deze combineren in complexere patronen en loops. In de architectuur van [van prompt naar graph engineering](https://community.llmnet.nl/van-prompt-naar-graph-engineering) zie je hoe geïsoleerde toolcalls samenkomen in robuuste, meervoudige beslissingsbomen en geautomatiseerde netwerken. Nederlandstalig kennisnetwerk over AI en LLM's. Onafhankelijk, praktisch en met bronvermelding. Meer op llmnet.nl: [Hub](https://hub.llmnet.nl/) · [Community](https://community.llmnet.nl/) · [Consultancy](https://consultancy.llmnet.nl/) · [Nieuws](https://nieuws.llmnet.nl/) · [Benchmark](https://benchmark.llmnet.nl/) · [Vacatures](https://vacatures.llmnet.nl/) · [Leren](https://leren.llmnet.nl/) · [Gids](https://gids.llmnet.nl/) · [Directory](https://directory.llmnet.nl/) · [Radar](https://radar.llmnet.nl/) © 2026 llmnet.nl · Ivo DonkerKennisnetwerk over AI & LLM's