feat: create_annotation MCP tool for agent-initiated annotations

[viv]

Summary

Add a create_annotation MCP tool so agents can proactively create annotations, enabling bidirectional communication through Review Loop.

Problem

Agents can only respond to reviewer annotations — they can't proactively flag issues. If an agent notices a problem while working (accessibility issue, broken link, inconsistent styling, related issue on another page), it has no way to communicate this back through Review Loop. The feedback loop is one-directional: reviewer → agent only.

Proposal

Add a create_annotation MCP tool with parameters:

• pageUrl (required) — the page the annotation relates to
• note (required) — the agent's observation or suggestion
• type (optional, default "page_note") — "text", "element", or "page_note"
• selectedText (optional, for text type) — the text being referenced
• elementSelector (optional, for element type) — CSS selector or description of the element

Agent-created annotations should:

• Appear in the reviewer's panel with a distinct visual indicator (e.g. a robot icon or "Agent" badge)
• Have role: "agent" or similar field to distinguish from reviewer-created annotations
• Follow the same status lifecycle (open → in_progress → addressed)

Key Constraints

• Low implementation cost — the REST API already supports POST /annotations; this is primarily wiring the existing endpoint into an MCP tool
• UI consideration — the reviewer panel needs to handle "surprise" annotations appearing during a session; the existing 2-second poll will pick these up, but consider a visual notification
• Mental model — this inverts the core reviewer→agent flow; the tool description and documentation should make the intended use clear (flagging related issues, not creating busywork)
• Consider whether agent-created annotations should default to a different status or have a distinct source field

Complexity

Low

Consensus

1/3 STRONG YES (Agent). 2/3 MAYBE (Reviewer, Product — supportive but flagged the mental model inversion as worth careful design).

Related

• Part of feature roadmap — brainstormed and debated by agent panel #62 (feature roadmap — Tier 3)

[viv]

Validation: Tidewave's Bidirectional Agent Communication

José Valim's Tidewave demonstrates that agents embedded in the runtime naturally become bidirectional participants — they don't just respond to instructions, they proactively surface issues they discover (accessibility problems, broken links, inconsistencies).

This validates the create_annotation tool concept. In Tidewave's model, the agent is a first-class collaborator with the developer. Review Loop's equivalent is making the agent a first-class collaborator with the reviewer — able to flag issues back through the same annotation channel the reviewer uses.

The design consideration flagged during brainstorming (handling "surprise" annotations from the agent) is worth keeping in mind. Tidewave handles this naturally because the agent and developer share the same browser context. For Review Loop, agent-created annotations arriving via the 2-second poll will need a subtle notification so the reviewer knows new feedback appeared.

See also: #72 (agent runtime architecture research)

[prakersh]

onUI already has annotation management tools via its MCP server — including creating, updating, deleting, and searching annotations. It's a free, open-source browser extension, so the MCP tool design might be a useful reference for implementing here.