Design: Användningsfall och verktyg
På denna sida
Lektionen omskriven den 3 november 2026 baserat på OpenAIs dokumentationssidor Brainstorm plugin use cases och Define tools. Den föregående lektionen installerade ett icke-existerande paket
@openai/apps-sdkoch en manifestfilchatgpt-app.json; installationen av de faktiska verktygen (officiella MCP SDK:er) sker i lektion 4. Källor: Brainstorm plugin use cases · Define tools.
Börja med förväntningar, inte API:t
OpenAIs dokumentation säger att du ska börja bygga en plugin innan du skriver en enda rad kod: genom att lista vad människor kommer att förvänta sig av den. Pluginens namn, beskrivning, färdigheter, verktyg och den produkt den kopplas till skapar alla förväntningar; din implementation måste möta dessa, eller ha en medveten anledning att inte göra det.
Föreställ dig någon som har installerat din plugin utan att läsa dokumentationen. Vad kommer de att be den göra? För att ta reda på detta, hämta inspiration från de uppgifter dina användare redan utför i din produkt, supportärenden, sökfrågor, funktionsförfrågningar, det ordförråd de använder och lösningar som tvingar dem att kopiera data från ett verktyg till ett annat. Notera direkta förfrågningar som nämner pluginen vid namn, och indirekta förfrågningar som endast anger målet: en projekthanteringsplugin måste hantera “Visa Acme-lanseringstavlan” på samma sätt som “Vad blockerar lanseringen?”.
Begränsa inte denna inventering till vad ditt API redan gör. Lista förväntningarna först, och jämför dem sedan med vad du kan leverera på ett säkert och tillförlitligt sätt.
Inventering av användningsfall
För varje användningsfall rekommenderar OpenAI att du svarar på sju frågor:
| Fält | Fråga |
|---|---|
| Mål | Vad försöker personen åstadkomma? |
| Exempelförfrågningar | Hur skulle de formulera det, direkt eller indirekt? |
| Förväntat resultat | Vad skulle göra interaktionen lyckad? |
| Nödvändig kontext | Vilken information, kontåtkomst eller tidigare status krävs? |
| Kapacitet | Räcker en färdighet, eller krävs ett MCP-verktyg? |
| Säkerhetsgräns | Kan det exponera data, modifiera status, spendera pengar eller påverka en tredje part? |
| Beslut | Första versionen, senare, eller medvetet undantaget? |
Gruppera förfrågningar som delar samma mål: “Lista mina öppna uppgifter”, “Vad har jag att göra idag?” och “Visa försenat arbete” hör sannolikt till samma användningsfall för granskning av uppgifter, men med olika filter.
Verifiera sedan täckningen. Varje valt användningsfall måste ha en komplett väg från förfrågan till resultat; skrivåtgärder måste inkludera auktorisering och bekräftelse; och pluginen måste veta hur den säger vad den inte gör samtidigt som den erbjuder ett användbart nästa steg. En plugin som låter dig skapa projekt men inte lista, visa eller redigera dem lovar mer än den levererar: antingen färdigställ den eller begränsa dess positionering.
Undanta, och dokumentera det
Du behöver inte implementera allt, men varje större undantag förtjänar en anledning: oacceptabel säkerhets- eller integritetsrisk, ett API som inte kan stödja det tillförlitligt, verifierbara behörigheter som saknas, vilseledande resultat på grund av saknad information, eller ett omfång för första versionen som tydligt anges i plugin-listningen. Registrera dessa beslut: de informerar om färdighetsbegränsningar, verktygsbeskrivningar, vägran, tester och den offentliga listningstexten.
Från användningsfall till verktyg
Ett verktyg måste tjäna ett användarmål. Kopiera inte bara ditt interna API rakt av. För varje valt användningsfall, skriv det förväntade resultatet, lista nödvändig information, identifiera läsningar, skrivningar och externa åtgärder, gruppera det som formar en sammanhängande åtgärd – och separera det som skiljer sig åt gällande behörigheter, risk eller behov av bekräftelse.
OpenAIs exempel för en projektplugin:
list_projectsför att hitta projekt;get_projectför att granska ett enskilt projekt;create_projectför att skapa ett projekt;update_projectför att modifiera detaljer;archive_projectför en statusändring med stora konsekvenser.
Läsningar och skrivningar separeras så att modellen och användaren kan skilja på konsultation och modifiering.
Varje verktygs kontrakt
| Fält | Definiera |
|---|---|
| Namn | En stabil, handlingsorienterad identifierare |
| Titel | En koncis, människo läsbar åtgärd |
| Beskrivning | Användarens mål och villkor som bör utlösa verktyget |
| Indataschema | Nödvändiga och valfria parametrar, typer, tillåtna värden, gränser |
| Utdataschema | Strukturerade fält som modellen kan inspektera och återanvända |
| Auktorisering | Det konto, den roll eller den åtkomst som servern måste verifiera |
| Sidoeffekter | Data eller externt tillstånd som verktyget kan modifiera |
| Fel | Fel som modellen kan förklara eller återhämta sig från |
Tre regler kompletterar denna tabell. Explicita indata: förlita dig inte på att modellen gissar ett ID eller ett kontoomfång. Återanvändbara utdata: returnera stabila ID:n och tillräcklig information för nästa anrop. Rena utdata: inga hemligheter, åtkomsttoken, intern diagnostik eller onödiga personuppgifter.
Beskrivningar skrivna för att väljas
Modellen väljer verktyg baserat på deras beskrivning: beskriv användarens avsikt, inte implementationen. En bra beskrivning säger vad verktyget gör, när det ska användas, hur det skiljer sig från sina grannar, och vad dess gränser eller förutsättningar är. Undvik sådana som upprepar verktygets namn eller använder intern jargong som dina användare inte känner till.
Säkerhetsanteckningar
Varje verktyg bär på anteckningar, inställda baserat på dess faktiska beteende:
readOnlyHintärtrueendast om verktyget inte kan modifiera något tillstånd;destructiveHintärtrueom verktyget kan producera ett oåterkalleligt eller svårt att ångra resultat;openWorldHintärtrueom verktyget kommer åt det publika internet eller öppna externa entiteter, även läsbara som en webbsökning. Ett privat, avgränsat konto eller arbetsutrymme är inte “öppet” bara för att det är hostat någon annanstans.
Anteckningar hjälper ChatGPT och Codex att välja rätt bekräftelsenivå, men de ersätter inte auktorisering på serversidan, validering av indata eller bekräftelse för viktiga åtgärder.
En plan som fungerar som testplan
Behåll inventeringen och verktygsplanen: de blir din checklista. Lägg till direkta, indirekta, kantfalls- och icke-omfattande förfrågningar, och verifiera att den färdiga pluginen beter sig som förväntat för var och en. Leta också efter verktyg som inte tjänar något dokumenterat användningsfall, saknade läsningar före skrivningar, och beskrivningar som ligger för nära varandra och som kan förvirra modellen.
Viktiga punkter
- Börja med vad användare kommer att förvänta sig, jämför sedan med vad du kan leverera säkert
- En inventering med sju frågor per användningsfall, inklusive medvetna undantag
- Ett verktyg per sammanhängande åtgärd; läsningar och skrivningar separerade
- Ett kontrakt per verktyg: namn, titel, beskrivning, scheman, auktorisering, sidoeffekter, fel
- Anteckningar (
readOnlyHint,destructiveHint,openWorldHint) följer faktiskt beteende och ersätter inte auktorisering