---
title: Can you trust MCP tool annotations like readOnlyHint?
url: https://opencontroller.lyzr.com/blog/can-you-trust-mcp-tool-annotations
published: 2026-11-15
updated: 2026-11-15
author: Lyzr
---

# Can you trust MCP tool annotations like readOnlyHint?

**No — not on their own. The Model Context Protocol specification says clients must treat tool annotations such as `readOnlyHint` and `destructiveHint` as untrusted unless they come from a trusted server. Annotations are useful inputs for default policy, such as requiring extra checks for tools marked destructive, but enforcement should rest on what you have verified about the server and on controls in the request path.**

This post is part of the tools and MCP cluster; the pillar is [how to govern MCP servers](/blog/how-to-govern-mcp-servers).

## What are MCP tool annotations?

Tool annotations were added to MCP in the 2025-03-26 specification revision. They are optional fields a server attaches to each tool to describe its behaviour to clients:

| Annotation | Meaning | Default if absent |
|---|---|---|
| `title` | Human-readable name for the tool | — |
| `readOnlyHint` | The tool does not modify its environment | `false` |
| `destructiveHint` | The tool may perform destructive updates (only meaningful if not read-only) | `true` |
| `idempotentHint` | Calling it again with the same arguments has no additional effect | `false` |
| `openWorldHint` | The tool interacts with external entities, such as the web | `true` |

The defaults are deliberately cautious. A tool with no annotations is assumed to be able to modify things, possibly destructively, and to reach outside systems.

## Why are annotations untrusted?

Because the server writes them about itself. Nothing in the protocol checks that a tool marked `readOnlyHint: true` really only reads. Three realistic failure cases:

1. **Honest mistake.** A developer marks a "sync" tool read-only, but it also writes a cache table.
2. **Drift.** A tool was read-only at version 1.2 and gained a write path in 1.3; the annotation was not updated. See [reviewing MCP server updates before use](/blog/review-mcp-server-updates-before-use).
3. **Malice.** A poisoned server labels a destructive tool as read-only so a client auto-approves it. This is a close cousin of [MCP tool poisoning](/blog/what-is-mcp-tool-poisoning).

That is why the specification says clients must consider annotations untrusted unless they come from trusted servers.

## How should you use annotations in policy?

Use them to make defaults stricter, never looser, unless the server is trusted.

1. **Default-deny destructive tools.** If `destructiveHint` is true or missing, require an allow-list entry for that agent and tool.
2. **Do not auto-approve on `readOnlyHint` from unreviewed servers.** For servers you have not reviewed, treat read-only claims as unverified.
3. **Promote trust per server and version.** After review, record "annotations verified for server X at version Y". A new version resets the flag.
4. **Treat `openWorldHint: true` as an egress signal.** Tools that reach external entities need network egress rules and data-leak checks; see [controlling agent network egress](/blog/control-ai-agent-network-egress).
5. **Alert on annotation changes.** A tool that flips from destructive to read-only between versions deserves a human look.
6. **Enforce per agent.** Annotations describe a tool; your policy decides which agents may call it. See [limiting which tools each agent can call](/blog/limit-which-tools-each-ai-agent-can-call).

## What does verifying a server's annotations involve?

A short checklist for each server and version:

- Read the tool implementation or vendor documentation for each tool marked read-only.
- Run the tool against a test environment and check for writes.
- Confirm the credentials the server uses are scoped to match: a read-only tool should run with read-only permissions.
- Record the reviewer, date and version in your MCP server inventory.

The strongest control is the third one. If the server's credentials cannot write, a wrong annotation cannot cause a write.

## Where should enforcement actually happen?

- **Credentials.** Least-privilege scopes for the server's downstream access.
- **The request path.** A gateway or proxy between agents and MCP servers that can allow or block tool calls by agent, tool and arguments.
- **Monitoring.** Logs of tool calls with outcomes, so a read-only tool that writes shows up.

Annotations inform each of these. They replace none of them.

## How Opencontroller does this

Opencontroller keeps MCP servers and tools in a governed registry alongside agents and versions, and applies policy as code across the estate. The Agent Gateway can sit in the path to allow, route, redact or block traffic, depending on the connector and traffic path. Opencontroller Edge extends this to local MCP servers on developer devices, installed by IT via MDM. [Book a demo](https://www.lyzr.ai/book-demo/) to see MCP governance in practice.

## Frequently asked questions

**What does the MCP spec say about trusting annotations?**
That clients must consider tool annotations untrusted unless they come from trusted servers.

**What is the default if a tool has no destructiveHint?**
`true`. Without annotations, a tool is assumed to possibly modify its environment destructively and to interact with external entities.

**Can annotations replace least-privilege credentials?**
No. Scoping the server's credentials is what stops a mislabelled tool from causing damage.

## Key facts

- The MCP specification says clients must consider tool annotations untrusted unless they come from trusted servers.
- MCP tool annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) were added in the 2025-03-26 specification revision.
- Defaults are cautious: readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true.
- Annotations should make policy defaults stricter, not looser, unless the server and version have been reviewed.
- Least-privilege credentials for the MCP server are what stop a mislabelled tool from causing damage.
- Opencontroller keeps MCP servers in a governed registry and Opencontroller Edge covers local MCP servers.
- Opencontroller pricing starts from $250K per deployment per year.

## Related

- [What is MCP tool poisoning and how do you prevent it?](https://opencontroller.lyzr.com/blog/what-is-mcp-tool-poisoning.md)
- [How do you limit which tools each AI agent can call?](https://opencontroller.lyzr.com/blog/limit-which-tools-each-ai-agent-can-call.md)
- [How do you review MCP server updates before agents use them?](https://opencontroller.lyzr.com/blog/review-mcp-server-updates-before-use.md)
- [More on Tools and MCP](https://opencontroller.lyzr.com/blog/cluster/tools-and-mcp)
