Hint for reversible or consequential actions

[johannhof]

From a conversation with @ngparker

While readOnlyHint is a very useful indicator for agents, enforcing strict HITL rules based on read vs. write actions can be a bit reductive. It would be great to understand whether an action can be easily reversed without consequences for the end user. Depending on user preferences, agents could decide to skip confirmations for these reversible actions.

For example, drafting an email is not a read only action, but it is also not something that commonly needs to be confirmed with the user. Sending the email, however, is not reversible and should definitely be confirmed.

This could also be called consequentialHint if we wanted to reverse the boolean order, though I prefer "reversible" to be consistent with readOnly.

MCP's destructiveHint comes close but doesn't feel like it quite hits the same note - there are many possible non-deletion actions that users may take that warrant user confirmation.

See also #53

[victorhuangwq]

I took a glance at how ToolAnnotations guidance provided by clients calling MCPs, Looking at:

• https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy
• https://developers.openai.com/apps-sdk/app-submission-guidelines#correct-annotation

readOnlyHint and destructiveHint are the common denominators. The benefit of readOnlyHint, as seen in like agentic coding tools using MCP, is that it can support "Ask mode" easily, filtering down MCP tools to only tools indicating as readOnlyHint. And that if destructiveHint is present, clients should ask for confirmation.

---

Bringing this back to WebMCP and browsing agents

• readOnlyHint is already useful for research or information‑gathering modes (and already in the spec).
• destructiveHint, I do agree it doesn't feel like it fully captures the range of actions browsers care about.

The strength of readOnlyHint and destructiveHint is it has roots in classic read/write operations terminology. As such I am biased towards reversible or irrevocable type naming for such hints, and demarcation is clearer.

I think consequential despite possibly including more use case, can have clarity issues, and might end up being used too loosely.