Add declarative human-in-the-loop policy hints for tool execution

[beladevo]

Problem

WebMCP tools have vastly different risk profiles (e.g., a read-only search vs. sending a payment or deleting data). Currently, there is no declarative way for a web application to communicate its expected Human-in-the-Loop (HITL) policy per tool.

Without a structured signal, User Agents (UAs) must infer risk from natural-language descriptions or tool names, leading to inconsistent UX or unsafe assumptions.

Proposal

Add an optional, advisory humanInTheLoopHint to ToolAnnotations.

enum ToolHumanInTheLoopPolicy {
  "none",     // Safe to run autonomously (e.g., read-only lookup)
  "notify",   // Run autonomously but notify user (e.g., temporary UI preference)
  "review",   // Requires preview/summary before finalizing (e.g., staging a draft)
  "confirm"   // Requires explicit approval (e.g., sending email, deleting a file)
};

dictionary ToolAnnotations {
  boolean readOnlyHint = false;
  boolean untrustedContentHint = false;
  ToolHumanInTheLoopPolicy humanInTheLoopHint = "confirm"; 
};

Example Usage

document.modelContext.registerTool({
  name: "email.createDraft",
  title: "Create email draft",
  inputSchema: { /* ... */ },
  annotations: {
    readOnlyHint: false,
    humanInTheLoopHint: "review" 
  },
  async execute(input) { return await createDraft(input); }
});

Why this matters

1. UX Consistency: Provides a common vocabulary for tool-level expectations, enabling UAs to render standardized confirmation/review states.
2. Advisory Nature: This does not replace UA safety frameworks. The UA can always ignore the hint or enforce a stricter policy (e.g., forcing a confirm on sensitive actions even if the site requests none).

Open Questions

1. Should this be a single enum or separate boolean hints (e.g., requiresConfirmationHint)?
2. What should the default value be? Should readOnlyHint: true implicitly default to "none"?
3. Should high-risk categories (payments, external communication) have stricter normative guidance that overrides loose site hints?

Next Steps

If the working group is open to this direction, I can submit a PR adding this annotation schema, minimal examples, and non-normative safety guidance to the spec.

[rpelevin]

I like the advisory shape, but I would keep one boundary very explicit: humanInTheLoopHint should be a site-provided risk hint, not the authorization decision.

A UA can use the hint as one input, but the actual approval policy should still be computed by the UA from the tool, origin, resource, user context, and arguments. Otherwise a high-risk tool could accidentally downgrade itself by declaring none or notify.

The test cases I would want around the annotation are:

• readOnlyHint: true plus humanInTheLoopHint: "none" can run without approval only when the UA agrees the call is actually read-only.
• external communication, payment, deletion, permission change, or customer-data mutation cannot be forced below the UA's minimum policy by the site hint.
• an approval binds to the exact tool call: origin, tool name, resource/target, canonical args digest, policy version, and expiry.
• if the tool args, resource, or origin changes after review/confirm, the old approval is stale and a new decision is required.
• review creates a preview/summary state, while confirm creates an explicit yes/no decision state; neither should be treated as a generic notification.

That keeps the web-facing API useful for UX while leaving authority with the user agent rather than the application that wants the tool to run.