SEP: optional advisory policy hints for MCP tools (effect, idempotency, sensitivity)

[dgenio]

Preamble

• Title: Optional Advisory Policy Hints for MCP Tools
• Authors: @dgenio
• Status: draft
• Type: Feature
• Created: 2026-05-19
• Related: SEP-1075: Security Annotations for MCP Tool Definitions #1075 (dormant — formal lattice-based security annotations), [SPEC] Annotations for MCP Requests and Responses (security/privacy) #711 (annotations for requests/responses)

Abstract

This proposal suggests documenting a lightweight, optional metadata convention that lets MCP servers expose advisory policy hints about their tools — such as effect type, idempotency, confirmation preference, and result sensitivity — so that clients, gateways, and proxies can make safer routing decisions without parsing natural-language descriptions.

Motivation

As MCP clients become more autonomous and tool catalogs grow, downstream systems increasingly need to answer questions before calling a tool:

• Is this tool read-only or does it mutate external state?
• Is it safe to call automatically, or should it require user approval?
• Is the call idempotent (safe to retry)?
• Does the result contain sensitive content that should be redacted before re-entering model context?

Today, each client infers these properties from tool names and descriptions, or invents its own metadata convention. This leads to inconsistent behavior across implementations.

Relationship to SEP-1075

SEP-1075 proposed a formal lattice-based security model (read_confidentiality, write_confidentiality, integrity) aimed at enforcing information-flow policies. That proposal was marked dormant due to concerns about complexity and fit with existing enterprise classification frameworks.

This proposal is intentionally different:

SEP-1075	This proposal
Enforcement-oriented	Advisory-only
Lattice-based formal model	Simple hints
Requires policy engine	Useful without enforcement infrastructure
Organization-specific labels	Common vocabulary for interoperability
Tool-level classification	Per-tool operational characteristics

The two are complementary: this proposal covers "what does calling this tool do?" while 1075 covered "what security clearance is needed?"

Specification

Tools MAY include advisory metadata in the _meta field of their tool definition (or via a future annotations extension). All fields are optional. Clients MUST NOT assume hints are present.

Proposed hints

Key	Type	Values	Description
effect	string	"read", "write", "delete", "external"	Primary side-effect of the tool
idempotent	boolean		Whether repeated calls with same input produce same result
requiresConfirmation	boolean		Server's preference for user confirmation before execution
resultSensitivity	string	"public", "internal", "confidential", "restricted"	Sensitivity of the tool's output content

Example

{
  "name": "delete_user",
  "description": "Permanently delete a user account",
  "inputSchema": { ... },
  "_meta": {
    "mcp.dev/effect": "delete",
    "mcp.dev/idempotent": false,
    "mcp.dev/requiresConfirmation": true,
    "mcp.dev/resultSensitivity": "internal"
  }
}

Semantics

• Advisory only: Hints do not replace authentication, authorization, or client-side policy. Clients MAY apply stricter local policies regardless of hints.
• No enforcement requirement: A client that ignores all hints is still a valid MCP client.
• Server-asserted: The server declares its own understanding of its tools. Gateways or deployers MAY override hints without violating the protocol.
• Stable across restarts: A tool's hints SHOULD NOT change between server restarts unless the tool's behavior changed.

Use cases

• Clients showing confirmation dialogs only for mutating tools.
• Gateways applying audit logging at different levels based on effect type.
• Proxies redacting tool results before they re-enter model context.
• Routing layers retrying only idempotent tools.
• CI checks verifying that destructive tools always declare requiresConfirmation: true.
• Documentation generators producing safety tables from metadata.

Backward compatibility

All hints are optional. Servers and clients that do not implement this proposal continue to work unchanged. The _meta field is already available for extensibility in the current spec.

Non-goals

• Replacing OAuth, capability-based auth, or transport-level security.
• Defining a formal security lattice or information-flow enforcement.
• Requiring servers to expose internal security policies.
• Blocking clients from implementing stricter local policies.
• Defining organization-specific classification hierarchies.

Open questions

1. Should effect support multiple values (e.g., a tool that reads and writes)?
2. Should there be a separate inputSensitivity hint for tools that accept sensitive arguments?
3. Should this live in _meta with namespaced keys, or in a dedicated annotations or hints field?
4. Should the spec recommend that requiresConfirmation tools be excluded from automatic batch execution?
5. Is there overlap with the existing annotations field in the 2025-03-26 spec revision that should be reconciled?

Community discussion

• Is this lightweight enough to avoid the complexity concerns that made SEP-1075 dormant?
• Should the vocabulary be fixed or extensible (e.g., allow custom effect types)?
• Would SDK authors (Python SDK, TypeScript SDK) be willing to expose these hints in their tool decorators?