Define accessibility requirements for WebMCP user-agent UI

[mlmrx]

Summary

Define accessibility requirements for any user-agent or agent-frontend UI that exposes WebMCP tool
discovery or mediates tool execution. This is a focused follow-up to the APA WG review in
#65 and the FAST self-review in #272.

This does not propose adding WebMCP tool metadata to the page accessibility tree; #91 settled
that question. It concerns the accessibility of user-facing UI created by a user agent or agent
frontend from WebMCP data.

Current gap

The draft says a tool's title is used by the user agent in UI,
but its Accessibility considerations section is empty.

The declarative explainer also defines user-visible behavior:

• without toolautosubmit, the browser focuses the submit button and asks the user to review the
  form;
• :tool-form-active and :tool-submit-active let authors visually highlight an agent-filled
  form;
• toolactivated and toolcanceled expose lifecycle changes to script, but do not ensure those
  changes are perceivable to the user.

Those hooks are useful, but author styling and script events are not a substitute for requirements
on the UI that people actually use. In particular, toolautosubmit skips the described review
state entirely.

Requirements to resolve

Any normative or recommended user-agent mediation should address at least:

1. Discovery: a user can determine that agent capabilities are available and identify them by
   an accessible name and description.
2. Review and approval: a user can inspect the exact tool, origin, arguments, target, and likely
   consequence before a consequential action is committed, then approve or reject it. A user-agent
   policy or user preference must be able to require review regardless of an author hint or
   toolautosubmit. This supports WCAG 2.2's review/confirm/correct model for consequential
   submissions.
3. Operation: the mediation UI is keyboard- and assistive-technology-accessible, with defined
   roles, names, states, values, focus behavior, and hardware-agnostic controls.
4. Status and recovery: start, progress, completion, partial failure, cancellation, and any undo
   opportunity are perceivable without relying only on color, animation, or visual focus.
5. Agent-filled state: users can tell which form values were supplied by an agent and review
   changes without requiring visual comparison. Whether this needs a WebMCP primitive, HTML work,
   or user-agent-only behavior remains an open layering question.
6. Privacy and parity: the same mediation is available whether or not assistive technology is
   present; implementations must not detect or reveal AT usage to select behavior.
7. Localization: accessible names, descriptions, status, and review UI follow the language and
   direction decisions tracked in Internationalization considerations #153 and Preserve language and direction for declarative tool descriptions #276.

Relationship to existing work

• WebMCP elicitation via requestUserInteraction() (was: Human in the Loop support for non-browser clients) #165 / PR Replace requestUserInteraction with requestUserInput #204: user-input and human-in-the-loop flows.
• Hint for reversible or consequential actions #176 / PR Add consequentialHint to ToolAnnotations #217 and Add declarative human-in-the-loop policy hints for tool execution #198: consequence/reversibility hints and review policy. Site-provided hints
  remain advisory; they are not authorization decisions.
• Communicate Validation Errors to Agent Prior to Form Submission #139: declarative validation feedback.
• Handling multiple labels #66, Should labels actually determine 'title'? #67, and Define the declarative input-schema synthesis algorithm (#declarative-api is currently a TODO) #210: labels and input-schema synthesis.
• Redundancy with the accessibility tree #91: WebMCP and the page accessibility tree remain separate layers.

The outcome could be conformance requirements, non-normative implementation guidance, or both, but
the current empty accessibility section does not answer the FAST API checklist item.

Maintainers: please apply the a11y-tracker label so APA is notified. I cannot apply repository
labels with my current permissions.

[mysticalseeker24]

Implementation data from the page side, offered because it bears on where some of these requirements have to live.

We built a booking app on the imperative API in which the human command surface is a caller of the same registry as the agent — a command palette that discovers with getTools() and executes with executeTool() rather than keeping a parallel list of commands. That put us against requirements 2, 4 and 5 from the page side, with mixed results.

Req 4 (status perceivable) — a page can do this today, cheaply

Every tool carries an announce() next to its execute(), and every execution — agent- or human-initiated — emits an aria-live message naming the actor:

"Agent selected Dr. Okafor, Neurology."
"You held Tuesday 14 October, 10:30, held for 10 minutes."
"Confirm booking is no longer available: the hold on the slot expired."

Because the wording is derived from the tool definition rather than written at a call site, it cannot drift from what the tool actually did. This seems worth recommending to authors in non-normative guidance even if the normative requirements land on the user agent, since it costs one function per tool.

Req 5 (agent-filled state) — the page cannot reliably tell who called

This is the one we could not solve cleanly, and it seems directly relevant to the open layering question in the issue.

When both the agent and our own UI execute through executeTool(), the page sees identical calls. We attribute by marking the expected caller immediately before invoking — a heuristic. Our first version used a single global mark, and a concurrent call stole it, so a human action was announced as the agent's. Keying the mark by tool name narrowed the window but does not close it, and nothing in the current API distinguishes a UA-mediated call from the page's own.

So if "users can tell which values an agent supplied" is to be reliable rather than best-effort, the page does not appear to be a layer that can determine it.

Req 2 (review and approval) — and a tension worth naming in the a11y section

We implement a page-side consent gate for consequential tools: a grant hashed over the canonical arguments, expiring, consumed once, released by a real activation on the page.

#288 shows that a user agent which is both the tool caller and a computer-use agent can satisfy that approval itself, and we reproduced that against our own gate. We deliberately did not add a CAPTCHA, dwell puzzle, or timing challenge, because every anti-automation mechanism that would defeat it is an accessibility barrier for exactly the users this mediation exists to protect.

That tension seems worth stating in the accessibility considerations directly: the obvious page-side defences against agent-completed approval are themselves a11y failures. It is an argument for requirement 2 living in the user agent with the user-preference override you describe, rather than being left to authors.

Caveat

All of the above is verified by markup review, automated assertion, and keyboard walkthroughs in Chrome. No screen reader has been run against it, and no disabled user has used it. Please treat it as implementation experience, not as an accessibility result.

Source, if it is useful as a datapoint: https://github.com/mysticalseeker24/parity-webmcp

[mlmrx]

Thanks—this is useful implementation evidence, and the caveat is exactly the right scope. I think it sharpens the split in this issue:

• Req. 4: Page-authored announcements are useful non-normative guidance, but the user-agent/agent UI still needs to expose its own start, progress, completion, cancellation, and recovery states. The current imperative API does not identify the caller, so page wording should not assert “Agent” versus “You” unless provenance is actually known.
• Req. 5: The concurrency result confirms that caller attribution cannot be made reliable from today's executeTool() surface. For declarative tools the user agent already knows that the fill is agent-originated; for imperative tools, reliable attribution would require a provenance signal or user-agent-only bookkeeping. We should not standardize the marking heuristic.
• Req. 2: This corroborates A user agent that both invokes tools and automates the page can complete the page's own human-approval step #288: page-side approval is not a security boundary when the same host can automate the page. CAPTCHA, timing, or dwell defenses would create accessibility barriers and still would not establish user authorization. Any normative requirement belongs in the user-agent processing model and should distinguish agent-originated from user-authorized, not physical from synthesized input.

A focused outcome can therefore separate normative user-agent requirements (review policy, provenance-aware state, and status/recovery) from non-normative author guidance (announce transitions with accessible patterns). If this implementation report is cited in spec discussion, its stated limitation should travel with it: it is implementation experience, not screen-reader or disabled-user validation.