A tool is a contract, not a promise.

A vocabulary for intent

An MCP server exposes tools so a client can discover which operations are available and how to call them. Alongside input schemas and descriptions, a tool may provide annotations: small pieces of metadata that describe the expected nature of an operation. They help a client choose a sensible interaction pattern, but they do not create a security boundary.

The MCP specification defines four boolean hints: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. They describe whether a tool appears to modify state, whether those modifications are destructive, whether repeated calls should have the same effect, and whether the tool reaches beyond a closed environment. Each hint has a default if it is omitted. These are statements by a tool provider, not independently verified capabilities.

For a documentation service, this distinction matters. A query that reads a public reference page is a different action from installing a package, writing to a repository, or publishing a deployment. A client ought to make that difference legible to the user.

Read-only is a claim about behavior

Consider a documentation retrieval endpoint. It may be safe to invoke without an approval dialog because its stated purpose is to find and return indexed information. A read-only annotation can help a trusted client express that intent. Yet the annotation alone cannot prove the implementation never writes, sends messages, or contacts unexpected services.

The official MCP guidance is explicit that annotations should be regarded as untrusted unless they come from a trusted server. Even a well-labelled result can contain arbitrary text from the open web. Tool output is evidence to evaluate, not instructions to execute.

• Confirm that the server identity and endpoint are the ones you intended to connect.
• Inspect the tool description, argument schema and advertised access before approving a new integration.
• Treat retrieved pages, repository files and other external text as untrusted content.
• Keep consequential write or destructive operations behind separate authorization and confirmation.

The four hints in practice

readOnlyHint addresses whether the operation is intended to avoid changing the environment. destructiveHint is relevant when an operation does change something and that change may destroy or overwrite state. idempotentHint answers whether repeating an operation with the same input is intended to be harmless in its observable effects. openWorldHint distinguishes tools that interact with open-ended external entities from those restricted to a closed domain.

These properties are independent. A tool can be read-only and still read sensitive information. A non-destructive write can still be undesirable. An idempotent request may still be expensive or leak data. The annotations are useful preflight signals, but they cannot replace application-level permission checks, network restrictions or review of tool responses.

A trustworthy documentation workflow

Docsy's retrieval workflow is intentionally small: identify the library, choose a version, retrieve the passage, then follow the source URL. That sequence reduces ambiguity without pretending that a retrieved answer is an authority on its own. The final check remains the primary documentation and the version your application actually uses.

A reliable coding assistant should separate these layers: what the MCP server advertises, what the tool truly returns, and what action the user has authorized. The protocol describes the channel. Product trust is built through implementation, provenance and clear user control.