MCP Tool Annotations: Can Your Bot Actually Trust readOnlyHint?

The short answer

Treat MCP tool annotations as a UX signal, not an access control. They can shape whether your bot's host shows a confirmation dialog or lets a call through quietly, but they cannot stop a tool from doing something destructive if the server mislabels it. Your actual safety boundary has to live somewhere else: a client-side allowlist, a sandbox, or a human approval gate that does not depend on what the server claims about itself.

This matters for anyone wiring a bot to an MCP server they did not write. If you are building the server, annotate honestly because it costs nothing and helps every client that reads the hints. If you are building or configuring the client, decide now whether your approval logic reads these hints at all, and if it does, from which servers you'll trust them.

What the four hints actually say

A tool can include a display title and four optional effect hints: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. The schema supplies defaults when a hint is absent. That makes omission a cautious signal, not evidence that an operation is safe.

The default for readOnlyHint is false, so an unlabeled tool is not assumed to be read-only. For a tool that may write, destructiveHint defaults to true; the schema says this field is meaningful only when readOnlyHint is false. IdempotentHint defaults to false, so repeated calls are not assumed to have the same effect. OpenWorldHint defaults to true, which does not assume the tool stays within a closed set of data. Server authors should describe actual behavior accurately and re-evaluate hints when implementations change.

Sources: Schema Reference - Model Context Protocol.

Hints are not guarantees

The MCP schema calls these fields hints rather than guarantees. The protocol also cautions that tool descriptions and annotations may be untrustworthy unless they come from a trusted server. A host should obtain user consent before invoking tools. An annotation is therefore input to a host's policy, never proof of a tool's behavior.

Consider a server that marks a deletion tool read-only, whether by mistake or after compromise. A client that auto-approves every tool carrying that label could allow a permanent change without the intended review. Review the server's trust level and enforce your own restrictions around sensitive tools, even when its metadata looks reassuring.

The protocol defines the hints, but it cannot prove how any particular client uses them. Test approval behavior in the client and version you actually deploy, including omitted and contradictory metadata, before changing your policy.

Sources: Schema Reference - Model Context Protocol, Specification - Model Context Protocol.

A worked example: delete_user

Imagine an internal admin server with get_user, which retrieves a record, and delete_user, which permanently removes one. A server built with FastMCP can attach ToolAnnotations when declaring each tool. The author might mark get_user read-only and mark delete_user destructive. These are illustrative declarations; their truth depends on the server's implementation.

Suppose a host you control uses a policy that allows lookups from a reviewed first-party server without another prompt but always asks a human to approve delete_user. That is a host policy, not a behavior guaranteed by MCP. Because the schema only gives destructiveHint meaning for tools that are not read-only, contradictory labels should trigger review under this policy rather than a silent decision.

If the server later mislabels delete_user as read-only, its metadata alone cannot protect the records. A separate tool allowlist, restricted credentials and approval for permanent changes still apply. This example does not describe a shipped BotBento feature.

Sources: Tools - FastMCP.

What to check before you rely on annotations

Before letting annotations influence approvals, check four things. Verify that your specific client reads them. Decide which servers you trust to describe their tools accurately. Define a conservative policy for omitted or contradictory hints. Re-test when a server changes its tool list or implementation.

For the example above, the host can use a verified lookup hint to reduce unnecessary prompts while keeping deletion behind an independent approval gate. Your exact policy should reflect the tool's real permissions and the cost of a mistake, not only the labels in its metadata.

Correction note

Updated 2026-10-10: We removed an unverified claim about a specific client and replaced wording that too closely followed the protocol documentation. The operational guidance now distinguishes the MCP schema from the illustrative host policy.