Design: Use Cases and Tools

Lesson rewritten on November 3, 2026 based on OpenAI’s Brainstorm plugin use cases and Define tools documentation pages. The previous lesson installed a non-existent @openai/apps-sdk package and chatgpt-app.json manifest; installation of the actual tools (official MCP SDKs) occurs in Lesson 4. Sources: Brainstorm plugin use cases · Define tools.

Start with expectations, not the API

OpenAI’s documentation says to start building a plugin before writing a single line of code: by listing what people will expect from it. The plugin’s name, description, skills, tools, and the product it attaches to all create expectations; your implementation must meet them, or have a deliberate reason not to.

Imagine someone who has installed your plugin without reading its documentation. What will they ask it to do? To find out, draw from the tasks your users already accomplish in your product, support tickets, search queries, feature requests, the vocabulary they use, and workarounds that force them to copy data from one tool to another. Note direct requests that name the plugin, and indirect requests that state only the goal: a project management plugin must handle “Show the Acme launch board” the same as “What’s blocking the launch?”

Don’t limit this inventory to what your API already does. List expectations first, then compare them to what you can provide safely and reliably.

The use case inventory

For each use case, OpenAI recommends answering seven questions:

Group requests that share a goal: “List my open tasks,” “What do I have to do today?” and “Show overdue work” likely belong to the same task review use case, with different filters.

Then verify coverage. Every selected use case must have a complete path from request to result; writes must include authorization and confirmation; and the plugin must know how to say what it doesn’t do while offering a useful next step. A plugin that lets you create projects but not list, view, or edit them promises more than it delivers: either complete it or narrow its positioning.

Exclude, and document it

You don’t have to implement everything, but every major exclusion deserves a reason: unacceptable security or privacy risk, an API that can’t support it reliably, unverifiable permissions, misleading results due to missing information, or a first-version scope clearly stated in the plugin listing. Record these decisions: they inform skill limits, tool descriptions, refusals, tests, and the public listing text.

From use cases to tools

A tool must serve a user goal. Don’t just copy your internal API as-is. For each selected use case, write the expected outcome, list required information, identify reads, writes, and external actions, group what forms a coherent action—and separate what differs by permissions, risk, or need for confirmation.

OpenAI’s example for a projects plugin:

• list_projects to find projects;
• get_project to examine one;
• create_project to create one;
• update_project to modify details;
• archive_project for a high-consequence state change.

Reads and writes are separated so the model and user can distinguish consultation from modification.

Each tool’s contract

Three rules complete this table. Explicit inputs: don’t rely on the model to guess an ID or account scope. Reusable outputs: return stable IDs and enough information for the next call. Clean outputs: no secrets, access tokens, internal diagnostics, or unnecessary personal data.

Descriptions written to be chosen

The model selects tools based on their description: describe the user’s intent, not the implementation. A good description says what the tool does, when to use it, how it differs from its neighbors, and what its limits or prerequisites are. Avoid those that repeat the tool name or use internal jargon your users don’t know.

Safety annotations

Each tool carries annotations, set based on its actual behavior:

• readOnlyHint is true only if the tool cannot modify any state;
• destructiveHint is true if the tool can produce an irreversible or hard-to-undo result;
• openWorldHint is true if the tool accesses the public internet or open external entities, even read-only like a web search. A private, bounded account or workspace isn’t “open” just because it’s hosted elsewhere.

Annotations help ChatGPT and Codex choose the right confirmation level, but they don’t replace server-side authorization, input validation, or confirmation for important actions.

A plan that serves as a test plan

Keep the inventory and tool plan: they become your checklist. Add direct, indirect, edge, and out-of-scope requests, and verify the finished plugin behaves as expected for each. Also look for tools that serve no documented use case, missing reads before writes, and descriptions too close together that might confuse the model.

Key takeaways

• Start with what users will expect, then compare to what you can provide safely
• A seven-question inventory per use case, including intentional exclusions
• One tool per coherent action; reads and writes separated
• One contract per tool: name, title, description, schemas, authorization, side effects, failures
• Annotations (readOnlyHint, destructiveHint, openWorldHint) follow actual behavior and don’t replace authorization