---
name: review-markdown
description: Open a markdown file in an interactive review viewer where the user highlights spans and leaves comments, then sends them to you. Use when the user wants to comment on, review, mark up, or give feedback on a .md file — or says "let me comment on this", "open this for review", "review this markdown".
---

# review-markdown

Open a markdown file in the live MCP-Apps review viewer so the user can highlight
text and leave comments, Google-Docs style. Comments come back to you as ordinary
messages — you act on them.

## How it works

1. Call the **`open_markdown`** tool with the file path and a `mode`:
   - `mode: "edit"` (default) — submitted comments are edit instructions; you modify
     the anchored ranges in the file, then re-render/verify.
   - `mode: "review"` — submitted comments are a punch-list; do **not** edit the file
     until the user approves items.
2. The viewer opens in Claude Desktop. The user has three actions:
   - **Answer Now** — sends a single comment to you *immediately* (a quick question or
     fix). Handle it on its own without waiting for anything else.
   - **Add to batch** — the user is accumulating comments while reading; nothing reaches
     you yet.
   - **Submit All** — flushes the whole batch to you as one message and persists it to a
     sidecar (`.claude/md-comments/<hash>.json`).
3. Comments arrive as messages shaped like:
   ```
   Apply these review comments by editing `path.md` (N comment(s)):

   --- L12-14
   > the quoted span
   Comment: the user's note
   ```
   Respect the verb in the header (edit vs punch-list).

## Rules

- Call `open_markdown` **once** per file; the viewer stays live.
- Honor the **mode** stated in each incoming message header — don't edit the file in
  review mode.
- For an **Answer Now** message ("Quick question on …"), respond to just that one item;
  don't assume there are others.
- When editing from a comment, anchor on the **quoted span** (and the `Lx-y` lines) to
  locate the exact text; read the file region before editing (it may have shifted).
- Never call `submit_batch` yourself — it is the viewer's internal persistence tool.
- Re-opening a file surfaces previously saved sidecar comments in `existingComments`;
  use them to resume an unfinished review.