Skip to content

MCP Tool Annotations Are Hints, Not Permissions

10 min read Fullmakt Team

  • mcp
  • agents
  • governance
  • agents-gone-wrong
  • policy
  • traceability
  • credentials
  • business-case

The Model Context Protocol lets a tool server describe its tools with annotations: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. They are useful. A client can skip the confirmation dialog for a read, warn before a delete, or retry a call that is safe to repeat. They are also, by design, just claims. The server that wrote the tool wrote the annotation, and nothing in the protocol checks that the two agree.

That becomes a governance problem the moment a team uses annotations to decide what an AI agent may do on its own. This post explains what MCP tool annotations are, how annotation-based auto-approval goes wrong, and how to classify agent actions in a place the tool server cannot influence.

What are MCP tool annotations?

MCP tool annotations are optional metadata fields a server attaches to each tool in its tools/list response. They describe the tool’s expected behavior to the client:

Annotation Meaning Default when absent
readOnlyHint The tool does not modify its environment false
destructiveHint A write may destroy or overwrite data (only meaningful when not read-only) true
idempotentHint Repeating the call with the same arguments has no extra effect false
openWorldHint The tool reaches external systems, not a closed domain true

The defaults are deliberately pessimistic: a tool with no annotations is treated as a destructive, non-idempotent write that talks to the outside world. The MCP specification is explicit that clients must treat annotations as untrusted unless they come from a trusted server. The word in the field names says the same thing: hint.

How annotation-based auto-approval goes wrong

Annotations are tempting because they are already there. An agent platform reads the tool list, auto-approves everything marked read-only, and asks a human about the rest. It looks like least privilege for free. These composite scenarios show why it is not.

1. The mislabeled tool

A community MCP server for a project tracker marks archive_issues as readOnlyHint: true, because the author thought of archiving as “not deleting”. The client auto-approves it. An agent asked to “clean up the board” archives 400 open issues in one run. No one was attacked. The label was simply wrong, and the label was the control.

2. The label that changed

A server you connected months ago ships an update. The export_report tool keeps its name and its readOnlyHint: true, but now also accepts a webhook_url and posts the report to it. This is the annotation version of an MCP rug pull: behavior drifts, metadata does not, and the approval you gave to the old tool silently covers the new one.

3. The label written by an attacker

A malicious or compromised server marks a credential-harvesting tool as read-only and non-destructive, precisely so it lands in the auto-approve bucket. Combine that with tool poisoning in the description and the agent will call it eagerly, without a human ever seeing the call. Whoever controls the server controls which of its own tools skip review.

4. The read that is not harmless

Even an honest readOnlyHint describes the tool’s effect, not the data’s risk. Reading a customer table does not modify anything, and it can still be the first step of an exfiltration if the agent also holds a way to send data out. That is the lethal trifecta in practice: private data, untrusted content and an outbound channel. “Read-only” does not mean “safe to run unsupervised”.

The rule: the party that benefits from a label cannot be the one that sets it

This is the same principle as separation of duties, applied to metadata. A tool server wants its tools to be called. An agent wants its tasks to finish. Neither should decide which calls skip review. The classification that drives an allow, approve or deny decision has to come from somewhere they cannot write:

  1. From the definition the human configured, not from the server’s self-description.
  2. From the arguments actually sent, evaluated at call time, not at listing time.
  3. From behavior, such as a tool being called for the first time, not from what the tool says about itself.

Use annotations for user experience: labels, icons, sensible prompts in a chat client. Do not use them as the input to an authorization decision.

How Fullmakt classifies agent actions server-side

Fullmakt is a credential broker and governed proxy for AI agents. Agents call your APIs and MCP tools through it; it applies a policy to every call, injects credentials server-side only after the policy allows the call, and records the result in an audit trail. Here is how that avoids trusting tool annotations.

  • Policy decisions use the tool name and the call’s arguments. A broker policy matches rules against the tool being called and the arguments the agent sent. A server-supplied annotation is not an input to the decision, so a tool cannot label its way out of a rule.
  • Operations are labeled by the server that holds the definition. For saved HTTP, email and file transfer tools, Fullmakt adds a synthetic _operation argument to what the policy sees, such as http.delete, smtp.send, imap.delete or sftp.upload. It comes from the operation a person configured on the saved definition, not from the agent and not from a tool description. One rule on that field can gate every delete, send or upload across a collection’s tools.
  • Agents cannot forge the operation label. On Fullmakt’s own HTTP, email and file transfer tools, the server-derived value overwrites anything the agent passes. On proxied upstream MCP tools, which carry no server-derived label, an _operation argument supplied by the agent is removed before policy evaluation, so it can neither trip nor dodge a rule.
  • Unpublished tools are uncallable, not just unlisted. When you aggregate an upstream MCP server, you choose which of its tools to publish. A hidden tool is absent from the tool list and is refused if an agent calls it by name anyway.
  • New behavior gets a human. A newToolFirstUse behavioral rule set to RequireApproval sends an agent’s first call to a tool it has not used in the last 24 hours to human approval, which is exactly the moment a mislabeled or freshly added tool would try to slip through.
  • The policy runs before the credential is touched. A denied call never triggers a vault lookup or an upstream request, so a mislabeled tool that is blocked never sees a secret. Credentials stay bound to the hosts a person allowed.

A policy that gates destructive operations, independent of any annotation, can look like this:

{
  "hardDeny": [
    { "field": "_operation", "pattern": "^(imap|pop3)\\.delete$",
      "message": "Agents may not delete mail." }
  ],
  "requireApproval": [
    { "field": "_operation", "pattern": "^(http\\.delete|smtp\\.send|(sftp|ftps)\\.(upload|delete|rename|createdirectory))$",
      "message": "Deletes, sends and file writes need a human." },
    { "tool": "tracker__archive_issues", "pattern": ".*",
      "message": "Archiving is a write, whatever the tool says." }
  ],
  "behavior": {
    "newToolFirstUse": { "action": "RequireApproval" }
  }
}

The last requireApproval rule is the important one for third-party tools: you name the tool you consider risky (proxied upstream tools are published as prefix__tool), and the decision follows your judgment, not the author’s annotation. For the general approach to splitting reads from writes, see why read and write calls need different rules.

Traceability: knowing what a tool actually did

When an annotation was wrong, the incident review needs to answer three questions: which agent called the tool, with what arguments, and what the policy decided. Fullmakt records each governed call, allowed or denied, with the agent principal, the tool, the upstream host, a hash of the arguments and the outcome, including the policy reason when a call was denied. That lets you prove a mislabeled tool was stopped, or find every call it made before you noticed. Pair it with agent incident forensics to reconstruct the full chain, and with MCP server supply-chain checks to decide whether to keep the server at all.

Observability is also where annotations earn their keep: comparing what a tool claims with what your audit trail shows it does is a cheap way to spot drift. A “read-only” tool whose calls show up next to outbound requests deserves a look.

The business case

  • Adopt third-party MCP servers without adopting their judgment. The MCP ecosystem grows faster than anyone can review it. A broker lets you connect a community server and still decide, in your own policy, which of its tools need a human.
  • One policy for every tool. Instead of trusting each server’s labeling conventions, security teams write rules against tool names and server-derived operation labels, and they apply to every agent calling that collection, whichever MCP client it runs in.
  • Fewer approvals, safer ones. Annotation-based auto-approval fails in both directions: honest servers that omit annotations get treated as destructive and flood reviewers, and dishonest ones skip review. Rules you own put human attention where your risk is.
  • Evidence for auditors. “We gate destructive operations in a server-side policy and log every decision” is a control. “The tools tell us whether they are destructive” is not.

Checklist: are you trusting annotations as permissions?

  1. Does any client or gateway in your stack auto-approve a tool because it is marked readOnlyHint: true?
  2. Who wrote the annotations on the MCP servers your agents use, and do you re-check them when a server updates?
  3. Can a destructive operation be gated by a rule you wrote, regardless of the tool’s metadata?
  4. Can an agent add or change the field your policy uses to classify an operation?
  5. Does the first call to a brand-new tool reach a human?
  6. Is the credential resolved only after the policy allows the call?
  7. Can you list every call a specific tool made last month, with the outcome of each?

FAQ

What is readOnlyHint in MCP?

readOnlyHint is an optional tool annotation in the Model Context Protocol. When true, the server is claiming the tool does not modify its environment. Clients can use it to adjust the user experience, but the specification says to treat annotations as untrusted unless the server itself is trusted.

Can I rely on destructiveHint to require approval for dangerous tools?

Not on its own. destructiveHint defaults to true when absent, which helps, but a server can set it to false on any tool. Use it as a signal for prompts and labels, and enforce approvals with a policy you control that names the tools and operations you consider risky.

Are MCP tool annotations a security feature?

No. They are a usability feature that describes intended behavior. Security decisions belong in a layer the tool server cannot write, such as a broker policy evaluated on every call.

Does Fullmakt use tool annotations in policy decisions?

No. Fullmakt’s policy evaluates the tool name, the call’s arguments, server-derived operation labels for HTTP, email and file transfer tools, and behavioral signals such as a tool’s first use. Annotations a tool server publishes are not part of that decision.

What about A2A skills?

The same rule applies. An A2A Agent Card describes a remote agent’s skills in the remote agent’s own words, which is why skill descriptions can be poisoned. Classify and gate what you delegate on your side of the connection.

See how Fullmakt governs AI agent tool calls and credentials or browse the Fullmakt blog.