Ontwerp: Use Cases en Tools
Op deze pagina
Les herschreven op 3 november 2026 op basis van OpenAI’s documentatiepagina’s Brainstorm plugin use cases en Define tools. De vorige les installeerde een niet-bestaand
@openai/apps-sdk-pakket enchatgpt-app.json-manifest; de installatie van de daadwerkelijke tools (officiële MCP SDK’s) vindt plaats in Les 4. Bronnen: Brainstorm plugin use cases · Define tools.
Begin met verwachtingen, niet met de API
Volgens de documentatie van OpenAI begint u met het bouwen van een plugin voordat u ook maar één regel code schrijft: door een lijst op te stellen van wat gebruikers ervan verwachten. De naam van de plugin, de beschrijving, vaardigheden, tools en het product waaraan deze gekoppeld is, wekken allemaal verwachtingen; uw implementatie moet hieraan voldoen, of een bewuste reden hebben om dit niet te doen.
Stel u iemand voor die uw plugin heeft geïnstalleerd zonder de documentatie te lezen. Wat zal hij of zij eraan vragen? Om dit te achterhalen, put u uit de taken die uw gebruikers al in uw product uitvoeren, supporttickets, zoekopdrachten, functieverzoeken, de vocabulaire die zij gebruiken, en workarounds die hen dwingen gegevens van het ene naar het andere hulpmiddel te kopiëren. Noteer directe verzoeken die de plugin bij naam noemen, en indirecte verzoeken die alleen het doel vermelden: een projectmanagementplugin moet zowel “Toon het Acme-lanceerbord” als “Wat houdt de lancering tegen?” op dezelfde manier afhandelen.
Beperk deze inventarisatie niet tot wat uw API al doet. Maak eerst een lijst van verwachtingen en vergelijk deze vervolgens met wat u veilig en betrouwbaar kunt bieden.
De use case-inventaris
Voor elke use case raadt OpenAI aan zeven vragen te beantwoorden:
| Veld | Vraag |
|---|---|
| Doel | Wat probeert de persoon te bereiken? |
| Voorbeeldverzoeken | Hoe zouden zij dit formuleren, direct of indirect? |
| Verwacht resultaat | Wat zou de interactie succesvol maken? |
| Vereiste context | Welke informatie, accounttoegang of eerdere status is nodig? |
| Mogelijkheid | Is een vaardigheid voldoende, of is een MCP-tool vereist? |
| Veiligheidsgrens | Kan dit gegevens blootleggen, status wijzigen, geld uitgeven of een derde partij beïnvloeden? |
| Beslissing | Eerste versie, later, of bewuste uitsluiting? |
Groepeer verzoeken die hetzelfde doel delen: “Lijst mijn open taken”, “Wat moet ik vandaag doen?” en “Toon achterstallig werk” behoren waarschijnlijk tot dezelfde use case voor taakreview, maar met verschillende filters.
Verifieer vervolgens de dekking. Elke geselecteerde use case moet een compleet pad hebben van verzoek tot resultaat; schrijfbewerkingen moeten autorisatie en bevestiging omvatten; en de plugin moet weten hoe hij moet aangeven wat hij niet doet, terwijl hij een nuttige volgende stap aanbiedt. Een plugin waarmee u projecten kunt maken, maar niet kunt lijstten, bekijken of bewerken, belooft meer dan hij levert: maak het af of verfijn de positionering.
Sluit uit, en documenteer het
U hoeft niet alles te implementeren, maar elke grote uitsluiting verdient een reden: onaanvaardbaar veiligheids- of privacyrisico, een API die het niet betrouwbaar kan ondersteunen, niet-verifieerbare machtigingen, misleidende resultaten door ontbrekende informatie, of een scope voor de eerste versie die duidelijk wordt vermeld in de plugin-listing. Leg deze beslissingen vast: ze informeren over limieten voor vaardigheden, tool-beschrijvingen, weigeringen, tests en de publieke listing-tekst.
Van use cases naar tools
Een tool moet een gebruikersdoel dienen. Kopieer uw interne API niet zomaar één-op-één. Schrijf voor elke geselecteerde use case het verwachte resultaat op, lijst de vereiste informatie op, identificeer lees-, schrijf- en externe acties, groepeer wat een coherente actie vormt—en scheid wat verschilt qua machtigingen, risico of behoefte aan bevestiging.
OpenAI’s voorbeeld voor een projecten-plugin:
list_projectsom projecten te vinden;get_projectom er één te onderzoeken;create_projectom er één aan te maken;update_projectom details aan te passen;archive_projectvoor een ingrijpende statuswijziging.
Lees- en schrijfbewerkingen zijn gescheiden, zodat het model en de gebruiker consultatie kunnen onderscheiden van modificatie.
Het contract van elke tool
| Veld | Definieer |
|---|---|
| Naam | Een stabiele, op actie gerichte identifier |
| Titel | Een beknopte, voor mensen leesbare actie |
| Beschrijving | Het doel van de gebruiker en de voorwaarden die de tool moeten activeren |
| Input-schema | Vereiste en optionele parameters, typen, toegestane waarden, limieten |
| Output-schema | Gestructureerde velden die het model kan inspecteren en hergebruiken |
| Autorisatie | Het account, de rol of de toegang die de server moet verifiëren |
| Neveneffecten | Gegevens of externe status die de tool kan wijzigen |
| Fouten | Fouten die het model kan uitleggen of herstellen |
Drie regels maken deze tabel compleet. Expliciete inputs: vertrouw er niet op dat het model een ID of accountscope raadt. Herbruikbare outputs: retourneer stabiele ID’s en voldoende informatie voor de volgende aanroep. Schone outputs: geen geheimen, toegangstokens, interne diagnostiek of onnodige persoonlijke gegevens.
Beschrijvingen geschreven om gekozen te worden
Het model selecteert tools op basis van hun beschrijving: beschrijf de intentie van de gebruiker, niet de implementatie. Een goede beschrijving vertelt wat de tool doet, wanneer deze gebruikt moet worden, hoe deze verschilt van naburige tools, en wat de limieten of vereisten zijn. Vermijd beschrijvingen die de tool-naam herhalen of interne jargon gebruiken die uw gebruikers niet kennen.
Veiligheidsannotaties
Elke tool draagt annotaties bij zich, ingesteld op basis van het daadwerkelijke gedrag:
readOnlyHintis alleentrueals de tool geen enkele status kan wijzigen;destructiveHintistrueals de tool een onomkeerbaar of moeilijk terug te draaien resultaat kan produceren;openWorldHintistrueals de tool toegang heeft tot het publieke internet of open externe entiteiten, zelfs read-only zoals een webzoekopdracht. Een privé, begrensde account of workspace is niet “open” alleen omdat deze elders wordt gehost.
Annotaties helpen ChatGPT en Codex het juiste bevestigingsniveau te kiezen, maar vervangen geen autorisatie aan de serverzijde, inputvalidatie of bevestiging voor belangrijke acties.
Een plan dat dient als testplan
Bewaar de inventaris en het tool-plan: ze worden uw checklist. Voeg directe, indirecte, rand- en buiten-scope verzoeken toe, en verifieer dat de voltooide plugin voor elk geval zich gedraagt zoals verwacht. Zoek ook naar tools die geen gedocumenteerde use case dienen, ontbrekende leesbewerkingen vóór schrijfbewerkingen, en beschrijvingen die te dicht bij elkaar liggen en het model kunnen verwarren.
Belangrijkste punten
- Begin met wat gebruikers zullen verwachten, en vergelijk dit vervolgens met wat u veilig kunt bieden
- Een inventaris van zeven vragen per use case, inclusief bewuste uitsluitingen
- Eén tool per coherente actie; lezen en schrijven gescheiden
- Eén contract per tool: naam, titel, beschrijving, schema’s, autorisatie, neveneffecten, fouten
- Annotaties (
readOnlyHint,destructiveHint,openWorldHint) volgen het daadwerkelijke gedrag en vervangen geen autorisatie