Een academische analyse van 856 tools over 103 MCP-servers laat zien dat 97,1% van de tool-descriptions minstens één "smell" bevat: onvermelde beperkingen, ontbrekende gebruiksrichtlijnen, ondoorzichtige parameters. Dat is geen randgeval. Dat is de baseline.
In De Zes Niveaus van MCP-Servers beschreef ik hoe elk volwassenheidsniveau eruitziet. Hier is wat de sprong van Niveau 1 naar Niveau 4 daadwerkelijk vraagt.
Een tool-description is geen zin
Het best-practice voorstel van de MCP-specificatie zelf beschouwt dit als een goede beschrijving: "Read the contents of multiple files simultaneously. More efficient than reading files individually." Dat is het plafond waar de community op mikt.
Na het bouwen van 52 tools over zeven productieservers kwam ik bij een andere standaard uit. Een tool-description is een operationele handleiding, gestructureerd in blokken, elk toegevoegd omdat de agent zonder faalde.
De acht blokken
| Blok | Doel | Zonder... |
|---|---|---|
| RETURNS | Agent weet welke velden terugkomen | Kan niet bepalen of deze tool de benodigde data heeft |
| WHEN TO USE | Agent weet wanneer deze tool past | Kiest verkeerde tool of mist deze |
| WHEN NOT TO USE | Voorkomt verkeerde toolselectie | Probeert deze tool voor queries die elders thuishoren |
| QUERY STRATEGY | Leert summary-first, dan inzoomen | Haalt volledige records op als een samenvatting volstaat |
| INTERPRETATION | Cross-field regels, type-naar-veld mappings | Geeft ruwe getallen zonder conclusies |
| RELATED TOOLS | Agent chaint queries via join-keys | Stopt na eerste tool-call |
| FEEDBACK | Agent rapporteert frictie | Problemen blijven onopgemerkt, descriptions verbeteren nooit |
| ALERTS | Agent toont server-gegenereerde waarschuwingen | Negeert domeinspecifieke waarschuwingen in het antwoord |
Deze blokken zijn niet theoretisch. Elk werd toegevoegd als reactie op een specifiek faalpatroon in productie. De agent koos de verkeerde tool, voeg WHEN NOT TO USE toe. De agent haalde 2.000 records op in plaats van een samenvatting, voeg QUERY STRATEGY toe. De agent negeerde dat een statuscode iets heel anders betekende voor een ander recordtype, voeg INTERPRETATION toe.
Wat daadwerkelijk werkt als metadatakanaal
Niet alles wat je schrijft bereikt de agent. Na testen in Claude Desktop, Claude Code en Cursor werd een duidelijke hiërarchie zichtbaar:
Tier 1: Werkt altijd (~95% van de waarde). Tool-descriptions en input-/outputschema .describe()-annotaties. De agent leest deze bij elke aanroep. Hier moet alle domeinkennis leven.
Tier 2: Werkt soms. Server-instructies, cross-tool gedragsregels geïnjecteerd bij sessiestart. Sommige clients injecteren ze, andere niet. Bruikbaar voor globale regels, geen vervanging voor per-tool descriptions.
Tier 3: Werkt niet in de praktijk. MCP Resources en meta-tools voor referentie-lookups. Ik heb beide gebouwd, gedeployed en getest. Agents hebben ze nooit opgevraagd in welke geteste client dan ook. Beide zijn verwijderd.
Het kernpunt: alles wat de agent nodig heeft moet in de tool-description en het input-/outputschema leven. Dat is het enige betrouwbare leveringskanaal, vooralsnog.
Voor en na
Het verschil in de praktijk. Een gebouwprofiel-tool, dezelfde API, dezelfde data:
Niveau 1: "Zoek gebouwinformatie op via postcode en huisnummer." Twee ongetypeerde parameters. Geen velddocumentatie. De agent raadt wat een energielabel betekent, of het bouwjaar betrouwbaar is, en welk postcodeformaat de API accepteert.
Niveau 4: Gestructureerde WHEN TO USE / WHEN NOT TO USE-blokken. Een QUERY STRATEGY die de agent waarschuwt dat adressen van slimme-meter-registraties niet dezelfde zijn als fysieke gebouwadressen. Een INTERPRETATION-blok dat drie verschillende energiecertificeringsstandaarden uitlegt: NTA 8800 geeft kWh/m2, Nader Voorschrift geeft MJ totaal gebouwenergie. Zonder dat blok vergelijkt de agent ze alsof het dezelfde eenheid is en geeft zelfverzekerd verkeerd advies. Inputschema met regex-validatie. Outputvelden met .describe()-annotaties die null-patronen, cross-tool join-keys en welk oppervlakteveld voor welke benchmark documenteren.
Dezelfde tool. Andere categorie. De Niveau 1-versie ontsluit een API. De Niveau 4-versie leert de agent hoe een domeinexpert over deze data denkt.
Een open-source extract van deze tool, met de metadatapatronen intact, is beschikbaar op github.com/DaveGold/mcp-building-profile-nl.
Voor het volledige vijffasenpatroon achter het bouwen van deze descriptions, inclusief hoe AI de domeinkennis ontdekt die ze vult, download het practitioner report.