Glossary
MCP tool annotations
MCP tool annotations are hints on each tool that say whether it reads, writes, can be repeated or reaches other people.
Updated November 6, 2026
- Also called
readOnlyHint,destructiveHint,idempotentHint,openWorldHint
At OneLifeVibe
- Every OneLifeVibe tool is classed Read, Write or Sensitive write. readOnlyHint is true for read tools; idempotentHint is true unless the tool is a sensitive write; destructiveHint is true only for introworth_close_intent (a closed intent cannot be reopened); openWorldHint is true only for the sensitive write taskfamily_add_event, which posts in the family chat and notifies the family.
- No OneLifeVibe tool buys, subscribes or spends money.
Related terms
What it means
MCP tool annotations are hints a server attaches to a tool definition. They help a client or assistant reason about a tool before calling it: does it only read, does it change state, is repeating the call safe, and does it affect anything outside the server? The common annotations are readOnlyHint, destructiveHint, idempotentHint and openWorldHint. They are not the tool's input schema and they do not replace the tool name, description or validation.
readOnlyHint signals that the tool is intended to read without modifying state. destructiveHint signals an action that is hard or impossible to undo. idempotentHint signals that repeating the same call has the same effect as calling once. openWorldHint signals that the tool reaches beyond the server, for example by posting where other people can see it. Treat all four as hints, not as proof of what the server will do.
How it works
A server publishes annotations with each tool so clients can see them before a call. A client might use readOnlyHint to skip a confirmation step, destructiveHint to require one, idempotentHint to decide whether a retry is reasonable, and openWorldHint to warn that other people may be affected. The annotations do not change the request or response; the tool still takes its normal input and returns its normal output.
Use annotations to choose the right user experience and retry policy, then enforce the real rules on the server. A hint can be wrong or incomplete, so a write tool must still validate input and a client should still handle errors. Idempotency is about repeated calls, not about whether a single call can fail. Destructive is about reversibility, not about whether a tool writes.
How OneLifeVibe uses it
Every OneLifeVibe tool is classed Read, Write or Sensitive write. readOnlyHint is true for Read tools. idempotentHint is true unless the tool is a Sensitive write. destructiveHint is true only for introworth_close_intent, because a closed intent cannot be reopened. openWorldHint is true only for the Sensitive write taskfamily_add_event, which posts in the family chat and notifies the family.
That leaves a clear split for client behavior. Read tools can be called without a state-change warning. Write tools can change state but are safe to repeat according to idempotentHint. Sensitive writes deserve more care: taskfamily_add_event is the one tool that reaches other people, and introworth_close_intent is the one tool marked destructive. No OneLifeVibe tool buys, subscribes or spends money.
Common mistakes
The most common mistake is treating a hint as enforcement. readOnlyHint true does not mean the server cannot write; it means the tool is intended to read. destructiveHint false does not mean a call is harmless. openWorldHint false does not mean no one else can see the result.
Another mistake is blind retries. idempotentHint true makes a retry reasonable for most OneLifeVibe tools, but it is not true for Sensitive writes, so do not replay those without checking the result. Finally, do not confuse annotations with OAuth scopes or webhook signatures. Scopes limit what a token can do, and signatures prove a webhook came from the sender; annotations only describe tool behavior.
Questions
What does readOnlyHint true mean on an MCP tool?
It means the tool is intended to read without changing state. On OneLifeVibe, readOnlyHint is true for every tool classed Read.
Why is destructiveHint true only for introworth_close_intent?
Because that action cannot be undone: a closed intent cannot be reopened. Other OneLifeVibe tools do not set destructiveHint.
See it working. The OneLifeVibe connector and Platform API put these pieces together.
Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.