Repository navigation
Add declarative human-in-the-loop policy hints for tool execution #198
Description
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
- UX Consistency: Provides a common vocabulary for tool-level expectations, enabling UAs to render standardized confirmation/review states.
- 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
confirmon sensitive actions even if the site requestsnone).
Open Questions
- Should this be a single enum or separate boolean hints (e.g.,
requiresConfirmationHint)? - What should the default value be? Should
readOnlyHint: trueimplicitly default to"none"? - 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.
Activity
rpelevin commentedon Jun 9, 2026
I like the advisory shape, but I would keep one boundary very explicit:
humanInTheLoopHintshould 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
noneornotify.The test cases I would want around the annotation are:
readOnlyHint: trueplushumanInTheLoopHint: "none"can run without approval only when the UA agrees the call is actually read-only.reviewcreates a preview/summary state, whileconfirmcreates 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.
victorhuangwq commentedon Jul 21, 2026
The use case you're describing, where a tool wants to signal that user involvement may be appropriate before execution, is a reasonable one to consider.
I agree with @rpelevin that these kinds of hints should remain advisory, with the exact UX and behaviour left up to the user agent.
It's also worth noting that we've had some closely related discussions already. In particular, #176 explores hints around reversible or consequential actions, which may address at least part of the scenario you're describing. If the primary goal is to support explicit human involvement in the execution flow, then #165 is probably the closer discussion.
I'd encourage you to share your thoughts and requirements on those threads as well. It would be helpful to understand whether the existing proposals cover your use case, or whether there's a distinct gap that isn't addressed by either discussion today.