Reference guide. This article draws on primary documentation and editorial recommendations; no production measurements are reported.
Make the action understandable
A tool name should describe what it does. Its parameters should make required choices explicit, and its result should tell the caller what happened. Ambiguous interfaces shift work into prompts and make failures harder to inspect.
Describe a useful boundary
Prefer a tool that represents one coherent operation. Give inputs clear types, reject unsupported values, and document effects that extend beyond the current task. Separate reading information from changing it when those operations need different permissions.
Return evidence
A useful result includes the outcome and enough context to verify it: a resource identifier, a version, or a structured error. Avoid treating a successfully sent request as proof that a downstream operation completed. Design the failure path as deliberately as the happy path.
Read the architecture first
MCP describes a host-client-server architecture for connecting applications to capabilities and context. Use its primary documentation to understand the transport and lifecycle before inventing application conventions. The interface advice here is an editorial design approach, not a measured comparison.
Prepared with AI assistance. Sources are linked in the story. This reference guide describes an approach; it does not report a production deployment.
The conversation
MODERATED, ALWAYSA useful question, a different result, a missing detail. Start there.