MarkLayer

Mark an annotation as in_progress and tag it with this agent so the human sees you are working on it.

Put a multiple-choice question to the room — "Which hero variant?", "Ship with the banner?" — when you need a decision rather than open-ended feedback. Each reviewer gets one vote and may change it. Read the tally with marklayer_get_feedback.

Tick a step of the checklist off (or back on with done: false). Reviewers see it change live.

Connect to a MarkLayer room (annotation session) by URL or bare room id. Disconnects any prior room.

Leave a new comment annotation yourself — proactive feedback (a bug, a UX issue, an accessibility gap, an idea) rather than only responding to a human’s. For an exact text replacement (a copy or grammar fix), use marklayer_suggest_edit instead — it renders as a diff the human can accept, rather than prose describing one. Use this after you have looked at the page with your own tools (a screenshot, a DOM read) and decided something is worth flagging; call it once per finding so each becomes its own pin the human can triage. x/y are document pixels (not viewport pixels — scroll offset already added in). Pass selector + tag + markdown (straight from marklayer_read_page) to pin to that element: the pin sits on the element and follows it when the page reflows, and x/y become optional (a fallback only). Omit all three for a fixed-point pin at x/y.

Mark an annotation as dismissed when it cannot be acted on. The reason will be visible to the human.

Get full detail for a single annotation of any kind (comment, area, selection, inspect), including its element `target` context and — for comments — the reply thread.

Everything the room has told you, in one read: annotation counts by status with the open ones in full, the next-steps checklist and how far along it is, and every poll with its current tally. Use it to decide what to do next; use marklayer_watch_annotations to wait for more.

List every annotation in the connected room across all tools (comment, area, selection, inspect). Each entry carries a `kind` discriminator and, where the user marked an element, a `target` block with selector + markdown so you can address the change without reopening the page. Filter by status: open, in_progress, resolved, approved, dismissed, or all (default). `approved` means the person who asked for the change confirmed the fix, so those need nothing from you.

Read the page this room annotates — its headings, paragraphs, links, buttons and labels, each with the CSS selector and tag that locate it. Call this FIRST when asked to review, audit or improve a page and no annotations exist yet: without it you can only answer feedback someone else left, never find anything yourself. Every entry is already in the shape marklayer_suggest_edit and marklayer_create_annotation take, so pass `selector`, `tag` and `markdown` straight through to anchor a mark to the element you are talking about. If the answer says the page renders client-side, the copy is not in the HTML and you should say so rather than review an empty shell.

Post a reply to an annotation thread without changing its status. Use to ask clarifying questions.

Mark an annotation as resolved. Pass a summary describing what was changed — it will be posted as a reply to the thread.

Get metadata about the connected room: page URL, viewport width, timestamps.

Publish your plan as a short ordered checklist the reviewers see live in the room, distilled from their feedback — one step per change you will make, each naming the annotation ids it answers. Replaces any list you set before. Tick steps off with marklayer_complete_next_step as you finish them, so the humans can watch the work land instead of asking where it is.

Open a new review room on a page you built — a preview deploy, a staging URL — and get back the link to hand to a human. Call this when you have something for someone to look at, rather than asking them to open a URL and describe what they see. The page is framed live and reviewers annotate it directly; their feedback then reaches you through the other tools. Pass `repo` + `branch` (and `sha`) when the page comes from a branch: a later preview of the same repo and branch becomes the next version of this one, and reviewers can step between versions. Over stdio this also connects you to the new room. Over HTTP the endpoint stays bound to the room in its URL, so reconnect to the returned `mcpUrl` to work the new room.

Propose an exact replacement for a piece of text on the page — a copy or grammar fix — as a diff the human can accept, rather than a comment describing the change in prose. `rects` are the on-page bounding boxes of `text`, in document pixels: one per line it spans, so a wrapped sentence highlights as several boxes rather than one box swallowing the whole paragraph between its first and last line. Pass selector + tag + markdown together to anchor it to the containing element so it re-resolves if the page reflows.

Block until there is work, then return a batch of whatever arrives within a short window. CALL THIS AGAIN IMMEDIATELY EVERY TIME IT RETURNS, including when it returns nothing — an empty result means the window expired, not that the reviewer is done. Nothing pushes work to you: between your calls, a comment someone leaves reaches no one. Keep looping until the person tells you to stop or ends the session. Each event has a `kind`: "new" is an annotation someone just left; "handoff" is one given to you — assigned to you, a reply that @mentions you, or a reply on a thread you already own. A handoff also carries `request`, the reply that asked: read it, it is the instruction, and act on it rather than only acknowledging. Every event carries the full annotation with its `target` element context.