Tools perform bounded work.
An MCP tool represents an operation the model may request through the client, such as searching a system, calculating a value, or creating a draft. A good tool has a narrow name, a typed input schema, predictable results, useful errors, and a permission boundary that does not depend on the model remembering a sentence in a prompt.
Split tools around meaningful approvals and failure paths. A search tool and a delete tool should not share one vague action just because both touch the same API. If a write has material consequences, return a preview or require an approval step before committing it.
- Name the business operation, not the underlying endpoint.
- Validate every input at the server boundary.
- Return evidence and status, not only a success sentence.
Resources provide context without pretending to be actions.
Resources represent information an application can read or attach to the model context. They are useful for documents, records, schemas, files, and other context that informs a decision but does not itself change a system. The resource owner still needs to decide freshness, visibility, caching, and access control.
A resource should make its identity and provenance legible. Tell the client what it is, where it came from, when it was last updated, and whether the result is complete. A large opaque context dump makes it harder for a user to review what influenced the next action.
Prompts make repeatable interactions discoverable.
Prompts are reusable templates for starting a known interaction. They can guide a user or application toward a useful sequence without being confused with a tool that changes data. The prompt should explain the required inputs and the expected review point, especially when it leads to a write-capable tool.
Keep prompts short enough to inspect and specific enough to be useful. A prompt that hides the relevant data sources, actions, or approval assumptions is a convenience layer over an unclear workflow.
Review the capability surface as a route.
For each item, ask who controls discovery, who controls invocation, who owns the data, and who can stop or reverse the result. Then test normal, missing-input, denied-access, upstream-failure, and out-of-scope cases.
The smallest useful surface is usually safer and easier to improve than a catalog of generic operations. Expose capabilities that help the user reach a measurable outcome, and make the evidence available for the person who owns the result.