Tools are the actions and data that a plugin’s MCP server exposes to ChatGPT and Codex. Define them after you brainstorm use cases and before you implement the server.
Every tool should help complete a user goal. Do not mirror an internal API without considering how people will ask for and use the capability.
Map use cases to tools
For each supported use case:
- Write the outcome the user expects.
- List the information required to produce that outcome.
- Identify the reads, writes, or external actions the server must perform.
- Group operations that represent one coherent action.
- Split operations when they have different permissions, safety risks, or confirmation requirements.
For example, a project plugin might expose:
list_projectsto find projects.get_projectto inspect one project.create_projectto create a project.update_projectto change project details.archive_projectto perform a consequential state change.
Separate read and write behavior so the model and user can distinguish information retrieval from actions that change state.
Define each contract
Record the following for every proposed tool:
| Field | What to define |
|---|---|
| Name | A stable, action-oriented identifier. |
| Title | A concise human-readable action. |
| Description | The user goal and conditions that should trigger the tool. |
| Input schema | Required and optional parameters, types, allowed values, and limits. |
| Output schema | Structured fields the model can inspect and reuse. |
| Authorization | The account, role, or resource access the server must verify. |
| Side effects | Data or external state the tool can change. |
| Failure behavior | Errors the model can explain or recover from. |
Use explicit inputs. Do not depend on the model guessing identifiers, account scope, or other values that are required for correctness.
Return stable identifiers and enough structured information for follow-up calls. Keep secrets, access tokens, internal diagnostics, and unnecessary personal data out of results.
Write descriptions for selection
The model uses tool descriptions to decide when a tool fits a request. Describe the user intent, not the implementation.
Good descriptions:
- State what the tool does.
- Explain when to use it.
- Distinguish it from similar tools.
- Call out important limits or prerequisites.
Avoid descriptions that only restate the tool name or expose internal service terminology that users do not know.
Plan safety annotations
Assign annotations based on actual behavior. See the MCP
ToolAnnotations
schema
for the canonical definitions, defaults, and interactions between these hints:
readOnlyHintistrueonly when the tool cannot change state.destructiveHintistruewhen the tool can cause irreversible or difficult to reverse outcomes.openWorldHintistruewhen the tool can affect public or external systems.
Annotations do not replace server-side authorization, input validation, or confirmation for consequential actions.
Check coverage and boundaries
Compare the proposed tools with the complete use-case inventory:
- Confirm that every supported use case has a path to a useful result.
- Identify tools that do not serve a documented use case.
- Look for missing reads that users need before taking a write action.
- Verify that unsupported requests produce an understandable limitation instead of an unsafe approximation.
- Test whether two similar tools have overlapping descriptions that could confuse selection.
Keep the resulting tool plan as an implementation and evaluation checklist. Then build the MCP server and test each contract with representative, invalid, and unauthorized inputs.