Tool Annotations Need a Policy Decision

Tool metadata gives a client concise preflight context before it presents a possible operation to a user.

A server may describe a tool as read-only, potentially destructive, idempotent for repeated calls with the same arguments—meaning later calls add no further environmental effect—or connected to an external environment. That information can help a client choose a warning, a confirmation posture, a retry policy, or a context-handling rule.

But a description is not an enforcement point. It is not proof that the server will behave as described, not proof that the request is appropriate for the user's task, and not a fresh grant of authority.

Tool annotations need a policy decision.

The protocol already draws the trust boundary

The current MCP Tools specification says that clients must treat tool annotations as untrusted for trust and safety purposes unless they come from trusted servers. That is a deliberately important distinction.

The MCP tool-annotations explainer describes common annotation fields as a risk vocabulary: whether a tool is read-only, destructive, idempotent, or reaches an open world. It also makes the limitation clear: annotations are hints. They can support user experience and policy inputs, but they are not enforcement and cannot make a model resilient to unsafe instructions by themselves.

The MCP 2026-07-28 specification overview keeps consent, user control, data privacy, tool safety, authorization flows, access controls, and data protections as separate implementation responsibilities. It explicitly notes that MCP cannot enforce those principles at the protocol layer.

This is not a reason to ignore the metadata. It is a reason to use it at the right layer.

• Layer: Server declaration — Question: What does this server say about the tool? — Example result: A behavioral hint attached to the tool definition.
• Layer: Source trust — Question: What reason does the client have to rely on this declaration? — Example result: Trusted, partially trusted, or informational only.
• Layer: Invocation interpretation — Question: What will this specific call attempt in this task? — Example result: A bounded description of the requested scope and possible effect.
• Layer: Policy decision — Question: Does current product and user policy allow this class of action now? — Example result: Allow, require review, narrow, defer, or deny.
• Layer: Enforcement — Question: What deterministic boundary constrains the actual operation? — Example result: A separate runtime, network, sandbox, or authorization control where applicable.
• Layer: Verification — Question: What evidence supports the outcome claim after the call? — Example result: A result receipt, independent check, or explicit uncertainty.

When these layers collapse into one boolean, a user can be shown a misleadingly simple promise: “safe.” Mature systems should make narrower claims.

The Tool Interpretation Record

A Tool Interpretation Record is a proposed per-invocation record. It does not replicate a tool definition or preserve private arguments. It records how a client translated metadata into a task-specific decision.

• Record element: Tool declaration reference — Question it answers: Which server and tool definition supplied the metadata? — Why it matters: Keeps the claim attached to its source and freshness boundary.
• Record element: Trust posture — Question it answers: Is the server trusted enough for the annotation to influence a safety decision? — Why it matters: Prevents untrusted self-description from bypassing a review.
• Record element: Declared behavior — Question it answers: Which annotations were present, absent, or conservatively defaulted? — Why it matters: Preserves useful metadata without treating it as fact.
• Record element: Requested scope — Question it answers: What does this invocation seek to read, change, send, or produce in the current task? — Why it matters: A read-like tool can still be inappropriate for the task or data boundary.
• Record element: Effect and exposure interpretation — Question it answers: What consequence or data-flow boundary could this particular call create? — Why it matters: Evaluates the action, not merely the tool label.
• Record element: Policy and authority binding — Question it answers: Which current rule, user decision, and expiry boundary justify proceeding? — Why it matters: Keeps annotations separate from consent and authorization.
• Record element: Required control point — Question it answers: Is confirmation, narrowing, a hold, or another deterministic control required? — Why it matters: Converts a label into a concrete client behavior.
• Record element: Outcome and verification disposition — Question it answers: What happened, what remains unverified, and what minimal summary is retained? — Why it matters: Stops a successful response shape from becoming an unsupported success claim.

The record makes a client explainable without revealing source code, raw prompts, or sensitive tool arguments.

Read-Only Is One Input to a Consequence Model

Consider a tool labeled as read-only. From a trusted server, that can reasonably influence a confirmation interface. It may reduce friction for a narrowly scoped inspection step.

It does not answer every relevant question:

• Is the request connected to the user's active task?
• Does the output cross a data boundary or contain untrusted instructions?
• Has the user limited this task to a particular workspace or account?
• Is the result current enough to support the next decision?
• Is a read-only query itself sensitive because of what it exposes?

The source label helps classify a possible operation. The invocation record supplies the contextual decision. Neither alone proves the full safety posture.

Idempotence and open-world reach are also conditional

The MCP blog explains that idempotence can inform retry behavior and open-world reach can inform how a client handles untrusted content. Both are useful examples of why static metadata needs a runtime interpretation.

An idempotence hint can support a narrow retry policy only when the client understands the actual request scope, its delivery status, and any relevant side effects. An open-world hint can help a client recognize that output may cross a trust boundary, but it cannot determine whether the current session also has access to sensitive context or another capability that creates a combined risk.

The same tool can be low consequence in one task and high consequence in another. Policy must evaluate the request in its session and task context.

Give metadata a concrete job

The MCP blog proposes a useful test for annotation design: what client behavior changes because this field exists? A metadata field that cannot affect a transparent client decision may only create the illusion of governance.

For clients, that suggests four practical rules:

1. Separate display from authorization. A title or behavior label can improve user comprehension even when it cannot safely reduce controls.
2. Treat source trust explicitly. A claim from an untrusted source can be shown as information, but should not silently waive confirmation or other policy.
3. Evaluate the invocation, not only the catalog entry. Arguments, task purpose, current authority, and exposure boundaries shape consequence.
4. Reserve hard guarantees for hard controls. If safety depends on an action being impossible, use a deterministic enforcement boundary rather than a descriptive field.

These rules keep annotations valuable. They are a compact vocabulary for decisions, not a substitute for the decision system.

Avoid false precision in user experience

An overconfident badge creates a risky interface outcome. It turns an incomplete hint into a claim that the user may reasonably trust more than the system can support.

Prefer language such as:

• “The server describes this as read-only; this client still checked its task and data policy.”
• “The tool may reach external systems, so output is treated as a trust-boundary input.”
• “The operation was allowed for this task under the current approval, subject to the stated verification step.”

That language is less magical, but more honest. It tells users what was declared, what the client independently decided, and what remains to be verified.

The real value is accountable interpretation

Annotations can reduce ambiguity, improve sensible defaults, and help a client surface risk before an action. They become genuinely useful when their downstream behavior is inspectable.

The goal is not to turn every tool call into a compliance form. It is to retain the one missing sentence: this client interpreted this metadata, from this source, for this request, under this policy, and took this action as a result.

That is a tool interpretation record. It leaves room for helpful metadata while preserving the policy decision where it belongs.

A Virillio Code Editorial Perspective

Virillio Code Editorial presents the Tool Interpretation Record as a product-neutral application framework. It does not describe a shipped, in-development, or planned Virillio Code capability.

Sources and further reading

• Tools — Model Context Protocol — The current specification defines tool metadata and optional behavioral annotations, requires clients to treat annotations as untrusted unless they come from trusted servers, and describes tool-list and invocation semantics.
• MCP 2026-07-28 Specification Overview — The current overview keeps consent, user control, privacy, tool safety, authorization, access controls, and data protections as separate implementation responsibilities that MCP cannot enforce by itself.
• Tool Annotations as Risk Vocabulary: What Hints Can and Can't Do — Model Context Protocol Blog — The official maintainers' explainer defines the four behavioral hints, cautious defaults, trust-dependent use, session-level combinations, and the distinction between hints and enforced contracts.

Editorial disclosure

This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.