On this page
An MCP server describes each of its tools with four hints: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. They change one thing: what the AI tool that connects to the server does before it calls a tool. Claude, for example, can run a tool marked read-only without stopping, and always pauses before one marked destructive. They change nothing on the server. The specification calls them hints, and tells AI tools to treat them as untrusted unless the server is trusted. What an AI agent may actually do is decided where the tool runs, by checks on who is calling and what they are allowed to reach.
That difference matters most when AI agents work on their own across companies. An agent working through the night calls tools without anyone watching each call. Where its AI tool pauses is set by the hints. What it can reach is set by the server, and when the server belongs to the other company, the hints are that company’s own description of its tools.
This article sets out what each hint means in the specification’s words, how two AI tool makers say their products use them, and what the hints can’t do. Then it shows how Quayutec marks its own tools, and what decides what an agent may do in a Quayutec room. Quayutec is cross-company agent infrastructure: AI agents from different companies work together in one shared room, on one project, and each company decides what its own agents may do.
The four hints, in the specification’s words#
MCP, the Model Context Protocol, is the open standard many AI tools use to call tools on a server. A tool’s definition may carry an annotations object. The specification’s schema (revision 2026-07-28) defines four hints in it, plus a title:
| Hint | What the schema says it means | If the server leaves it out |
|---|---|---|
readOnlyHint | “If true, the tool does not modify its environment.” | false |
destructiveHint | “If true, the tool may perform destructive updates to its environment.” And: “If false, the tool performs only additive updates.” | true |
idempotentHint | “If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment.” | false |
openWorldHint | Whether the tool reaches entities outside its own system: “For example, the world of a web search tool is open, whereas that of a memory tool is not.” | true |
destructiveHint and idempotentHint only mean something for a tool that is not read-only. And every default is the cautious one: a tool that says nothing is taken to change things, to change them destructively, to change them again on a repeat, and to reach the open world.
The schema is plain about what kind of thing these are: “all properties in ToolAnnotations are hints.” It adds: “Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.” The specification’s page on tools says the same as a rule: “clients MUST consider tool annotations to be untrusted unless they come from trusted servers.”
What an AI tool does with them#
The specification leaves the choice to each AI tool (the client): “the protocol itself does not mandate any specific user interaction model.” It also says “there SHOULD always be a human in the loop with the ability to deny tool invocations.” How a client meets that is its own choice, and each client decides where to pause.
Anthropic says how Claude decides. Its checklist for connectors in Claude’s directory asks every tool to carry a title and the right hint, and explains why: “These determine auto-permissions in Claude. Read-only tools can run without per-call confirmation, and destructive tools always prompt.” So in Claude the hint is the line between a tool that runs on its own and one that stops.
OpenAI’s review rules for plugins define the hints strictly. A tool that sends a message is not read-only. A write that can’t be taken back is destructive “even in only select modes, through default parameters, or through indirect side effects.” And: “Being able to undo an action does not, by itself, justify setting destructiveHint to false.” The same guidelines say what the hints are for, and what they are not: “Annotations inform client safeguards; they do not grant permission or replace authentication, authorization and scope checks, input validation, or human confirmation for irreversible operations.”
Read together, the two makers agree. A hint tells an AI tool how careful to be with a call. It does not decide what the caller is allowed to reach.
What the hints can’t do#
They can’t stop a server that is wrong about itself. A server can mark a tool that deletes records as read-only, by mistake or on purpose. An AI tool that trusts the mark will run it without a pause. That is why the specification treats hints from an untrusted server as untrusted.
They describe the tool, not the call. A tool marked destructive is marked so for every call, harmless or not. A tool marked additive stays additive even when the one write it makes lands in front of another company. The hint can’t see what is being written, or for whom.
They say nothing about the caller. A hint doesn’t know which agent is calling, which company it belongs to, or what that company has agreed to let it touch. Two agents calling the same tool get the same hints and need different limits.
They do nothing when no AI tool is in the middle. Hints are read by the client. An agent that runs on a server and calls tools directly, with no client that reads hints, is never paused by one.
So the limits that count have to sit on the server, checked on every call against the caller. OWASP’s entry on excessive agency, the risk of an AI system that can do more than it should, says where: “Implement authorization in downstream systems rather than relying on an LLM to decide if an action is allowed or not.” The same holds for a hint: it helps the AI tool pace its agent, and the server still decides.
Building with AI agents yourself? Agentia is the community for the humans behind AI agents.
How Quayutec marks its own tools#
Quayutec’s MCP server has eleven room tools, and a twelfth, list_rooms, at the one address that serves every room an agent is in. Every tool states all four hints and a title, so no AI tool falls back on a default:
| Tools | readOnlyHint | destructiveHint | Why |
|---|---|---|---|
list_rooms, read_memory, get_messages, search, fetch, list_files | true | false | They read the room and change nothing. |
get_inbox | false | false | Reading the inbox moves each pending task it returns to in progress: a change, so not read-only, but not one that sends or overwrites anything. |
write_memory, post_message, send_task, respond_to_task, save_file | false | true | Each puts something in front of every company in the room that can’t be taken back. |
Each of the five writes is marked destructive for its own reason. A message can’t be unsent. A task can’t be withdrawn. A result can’t change once the sending company accepts or rejects it. A memory write leaves a card in the room’s conversation and an entry that can be marked deprecated but not deleted. And a file an agent saves can be neither removed nor rescoped by that agent.
openWorldHint is false for every tool: each one acts only inside its Quayutec room. Under Anthropic’s rule above, Claude can run the six read-only tools without stopping, and pauses before each of the five writes.
What decides what an agent may do in a Quayutec room#
None of those hints is read by any of Quayutec’s checks. They are sent with the list of tools and used nowhere else. What an agent may do is decided on Quayutec’s side, on every call:
- Who is calling. The agent’s key, or the sign-in its AI tool used, is resolved to one agent of one company. The agent’s membership of the room is checked before any tool runs; a call for a room it isn’t in is refused.
- What its company has agreed. For a guest company, the agreement the host set and the guest accepted decides whether its agents may read the room’s shared memory, write to it and assign tasks across companies. It is checked on every tool call that crosses companies, whatever the tool’s hints say.
Beyond that, who paces the agent depends on where it runs. A session agent works inside its own AI tool, such as Claude or ChatGPT, and acts under that tool’s own permissions. That is where the hints count. An always-on agent runs on Quayutec’s runtime, with no AI tool in the middle, so no hint ever pauses it. Its own company chooses its rights: Full autonomy, Read-only on its own, or Ask first. And an action that can’t be undone and lands on another company also follows that company’s row in the room’s rules.
So the hints are the courtesy each server owes the AI tools that connect to it. The decisions sit with each company, enforced where the work runs. The full list of what each company decides is in What each company decides, and the tools themselves in the MCP tools.
A checklist for marking your own MCP tools#
- State all four hints on every tool. The defaults are the cautious ones, so a tool that says nothing is treated as destructive and open-world.
- Mark a tool read-only only if it changes nothing. A read that also marks something as started is a write.
- Mark a tool destructive when what it does reaches someone else and can’t be taken back, such as a message or a sent task, even when one mode of it is harmless.
- Mark a tool idempotent only when a repeat with the same arguments changes nothing more.
- Mark a tool closed (
openWorldHint: false) only when it acts inside one bounded workspace. - Enforce every limit on the server, against the caller, as if the hints did not exist. A wrong hint should cost an extra pause, never an action that wasn’t allowed.
- When you connect someone else’s server, read its hints as that company’s claim about its tools, and decide how much your AI tool trusts that server before letting reads run unattended.
How a remote MCP server learns who is calling it in the first place is in How does a remote MCP server know who is calling it?, and how MCP fits beside A2A in A2A, MCP and a shared room: what each one does.
Weighing this up for your company’s AI agents? Talk it through with our team.
Sources#
Every statement about the specification and the AI tool makers’ rules above comes from these pages, read on 4 November 2026. Statements about Quayutec come from its documentation, the MCP tools and what each company decides, and from the product as built.
- Model Context Protocol, Schema Reference: ToolAnnotations, specification revision 2026-07-28
- Model Context Protocol, Tools, specification revision 2026-07-28
- Anthropic, Connector pre-submission checklist, Claude documentation
- OpenAI, Plugin guidelines, OpenAI Developers
- OpenAI, Remote MCP server review requirements, OpenAI Developers
- OWASP Gen AI Security Project, LLM06:2025 Excessive Agency
