Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Ontwerp: Use Cases en Tools

Les 3 van 14 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Begin met verwachtingen, niet met de API
  2. De use case-inventaris
  3. Sluit uit, en documenteer het
  4. Van use cases naar tools
  5. Het contract van elke tool
  6. Beschrijvingen geschreven om gekozen te worden
  7. Veiligheidsannotaties
  8. Een plan dat dient als testplan
  9. Belangrijkste punten

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 en chatgpt-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:

VeldVraag
DoelWat probeert de persoon te bereiken?
VoorbeeldverzoekenHoe zouden zij dit formuleren, direct of indirect?
Verwacht resultaatWat zou de interactie succesvol maken?
Vereiste contextWelke informatie, accounttoegang of eerdere status is nodig?
MogelijkheidIs een vaardigheid voldoende, of is een MCP-tool vereist?
VeiligheidsgrensKan dit gegevens blootleggen, status wijzigen, geld uitgeven of een derde partij beïnvloeden?
BeslissingEerste 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_projects om projecten te vinden;
  • get_project om er één te onderzoeken;
  • create_project om er één aan te maken;
  • update_project om details aan te passen;
  • archive_project voor een ingrijpende statuswijziging.

Lees- en schrijfbewerkingen zijn gescheiden, zodat het model en de gebruiker consultatie kunnen onderscheiden van modificatie.

Het contract van elke tool

VeldDefinieer
NaamEen stabiele, op actie gerichte identifier
TitelEen beknopte, voor mensen leesbare actie
BeschrijvingHet doel van de gebruiker en de voorwaarden die de tool moeten activeren
Input-schemaVereiste en optionele parameters, typen, toegestane waarden, limieten
Output-schemaGestructureerde velden die het model kan inspecteren en hergebruiken
AutorisatieHet account, de rol of de toegang die de server moet verifiëren
NeveneffectenGegevens of externe status die de tool kan wijzigen
FoutenFouten 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:

  • readOnlyHint is alleen true als de tool geen enkele status kan wijzigen;
  • destructiveHint is true als de tool een onomkeerbaar of moeilijk terug te draaien resultaat kan produceren;
  • openWorldHint is true als 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