Reviso MCP tools

MCP tools

• reviso_document_create (write): Create a Markdown or HTML review document on the server. Changes persistent content, comments or access state within the connection's permissions. Capabilities: create_file. Input schema: {"additionalProperties": false, "properties": {"background": {"description": "Optional background pool: why-decisions and sources this document's future readers should be able to query. Loss-tolerant; omit when there is nothing to record.", "items": {"properties": {"body": {"type": "string"}, "kind": {"enum": ["decision", "source"], "type": "string"}, "ref": {"description": "Optional source url/path.", "type": "string"}}, "required": ["kind", "body"], "type": "object"}, "type": "array"}, "content": {"type": "string"}, "description": {"type": "string"}, "document_kind": {"description": "html_deck is contract-validated: violations return located fix_hints. Full rules: reviso_deck_contract.", "enum": ["document", "html_deck"]}, "operation_id": {"description": "Optional exactly-once id (op_...). Provide a stable id and REUSE it across retries of ONE logical create so a committed-but-lost-response replays instead of double-creating. Same id with a different payload is rejected 409.", "maxLength": 199, "minLength": 4, "pattern": "^op_[A-Za-z0-9_-]{1,196}$", "type": ["string", "null"]}, "parent_id": {"description": "Optional folder parent in the same workspace.", "type": "string"}, "source_format": {"default": "markdown", "enum": ["markdown", "html"], "type": "string"}, "title": {"type": "string"}, "workspace_id": {"description": "Optional. Auto-resolved to the account's workspace when there is exactly one. When the account has multiple, the call returns an error naming them \u2014 pass one, or call reviso_list_workspaces first. Scoped keys validate but do not supply it.", "type": "string"}}, "required": ["title", "content", "description"], "type": "object"}
• reviso_document_update (write): Replace the FULL Markdown/HTML body with version-CAS protection. For targeted Markdown edits prefer reviso_document_read_structure + reviso_document_apply_patch. Use this tool for wholesale rewrites or HTML. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"agent_name": {"default": "Agent", "type": "string"}, "background": {"description": "Optional background pool: why-decisions and sources this document's future readers should be able to query. Loss-tolerant; omit when there is nothing to record.", "items": {"properties": {"body": {"type": "string"}, "kind": {"enum": ["decision", "source"], "type": "string"}, "ref": {"description": "Optional source url/path.", "type": "string"}}, "required": ["kind", "body"], "type": "object"}, "type": "array"}, "base_version_id": {"description": "The version_id (ver_...) of the CURRENT latest version \u2014 read it from reviso_document_retrieve (or reviso_document_status in the full profile) immediately before writing; it must equal head. A stale base is rejected with CAS_CONFLICT (409, base_version_changed, not retryable) and there is NO cross-version merge: re-read the current content and re-apply your edit against the fresh head. Concurrent autosaves on the SAME version still fold: edits to DISTINCT blocks by both sides both survive, and a same-block race \u2014 a block you edited was concurrently edited to different content or deleted, OR a block you deleted was concurrently edited \u2014 fails CLOSED with a recoverable pei_ failed-intent handle, never a silent overwrite. For targeted block edits that merge over concurrent changes, prefer reviso_document_apply_patch. HTML documents use the same direct version-CAS check.", "type": "string"}, "content": {"type": "string"}, "description": {"type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "operation_id": {"description": "Optional exactly-once id (op_...). Provide a stable id and REUSE it across retries of ONE logical update so a committed-but-lost-response replays instead of writing a duplicate version. Same id with a different payload is rejected 409.", "maxLength": 199, "minLength": 4, "pattern": "^op_[A-Za-z0-9_-]{1,196}$", "type": ["string", "null"]}, "source_format": {"description": "Omit to preserve the existing document format. Pass markdown or html explicitly to change it.", "enum": ["markdown", "html"], "type": "string"}}, "required": ["document_id", "content", "base_version_id", "description"], "type": "object"}
• reviso_document_collaborative_update (write): Autosave a document's FULL Markdown body through block-aware CRDT collaboration without creating a version checkpoint. Decision path among the three write tools: prefer reviso_document_apply_patch for targeted structural edits (never resends the body); use reviso_document_update for a wholesale rewrite or HTML that DOES cut a version checkpoint; use THIS tool only when you must resend the whole Markdown body as a checkpoint-free autosave. Pass base_version_id (the version you last read/authored against); the server 3-way merges your edit over concurrent human edits and rejects a non-ancestor base with 409. MULTI-WRITER RULE: when other writers may be editing the same document, autosave back the content you read from reviso_document_read_structure or reviso_document_retrieve VERBATIM, including its <!-- reviso-node-id: blk_... --> anchor comments. Those anchors are block identity; a bare full-text body with the anchors stripped carries none, so a line that already exists is inserted as a SECOND independent block (same text, new block_id) instead of merging into the existing one, and the document ends up with duplicated paragraphs. A bare anchor-free body is only safe when you are the sole writer of the document: at seq 0 the server re-derives anchors from the version, and a concurrent writer's anchorless autosave can still duplicate. This tool never overwrites another writer's edit -- the failure mode is redundant blocks, not lost ones. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"base_version_id": {"description": "The version_id you authored this content against (read it from reviso_document_status). The server verifies it is an ancestor of the live head before merging.", "type": "string"}, "client_id": {"type": "string"}, "content": {"type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id", "content", "base_version_id"], "type": "object"}
• reviso_document_retrieve (read): Retrieve a document's latest content and version metadata. Pass version_id to read a committed version and receive its authenticated preview_url, content_hash and rendered HTML. Open that URL to inspect the real web rendering; receiving it does not prove a visual check. version_id cannot be combined with include. Pass include=["comments","versions"] to get the full agent packet in one call instead of separate fetches. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "include": {"description": "Expand the response: comments + version CAS metadata (agent packet). \"blocks\" adds a structured block index (block_id + kind + the quote each block would highlight) so you can anchor a comment without regexing ids out of the markdown. \"access\" re-adds the effective_access/security_policy blocks, which are stripped by default because they are browser UI state.", "items": {"enum": ["comments", "versions", "access", "blocks"], "type": "string"}, "type": "array"}, "thread_ids": {"description": "When include has comments, filter to these thread IDs.", "items": {"type": "string"}, "type": "array"}, "version_id": {"description": "Optional committed ver_ identifier, usually from the edit receipt. Pins content and the browser preview to that version.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_version_diff (read): Get a unified diff between two versions of a review's document, so the agent compares revisions without re-fetching and diffing full content itself. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "from_version_id": {"description": "Base version to diff from (ver_...).", "type": "string"}, "to_version_id": {"description": "Target version to diff to (ver_...).", "type": "string"}}, "required": ["document_id", "from_version_id", "to_version_id"], "type": "object"}
• reviso_document_read_structure (ephemeral_write): Read Markdown blocks and edit preconditions for reviso_document_apply_patch: base_version_id, update_seq, schema_version, block IDs/order/hashes and nullable neighbor IDs. Copy block_hash to base_block_hash or the insertion anchor hash; copy neighbor IDs, including null at edges. Filter block_ids or section_ids from the sections index; omit selectors for all blocks. Updates temporary activity or presence without changing persistent document content. Capabilities: view. Input schema: {"additionalProperties": false, "properties": {"block_ids": {"description": "Read only these blocks in document order. Mutually exclusive with section_ids. Unknown IDs fail; neighbors retain their global IDs.", "items": {"minLength": 1, "type": "string"}, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "include_content": {"default": true, "description": "Include each selected block's Markdown with its edit preconditions. Set false for metadata only.", "type": "boolean"}, "section_ids": {"description": "Read sections listed in this tool's sections index. Each section stops at the next heading. Mutually exclusive with block_ids.", "items": {"minLength": 1, "type": "string"}, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true}}, "required": ["document_id"], "type": "object"}
• reviso_document_apply_patch (write): Targeted Markdown editing: reviso_document_read_structure first, then copy base_version_id, update_seq as base_update_seq, and block hashes. Unrelated edits merge; changed/deleted targets or insertion boundaries return 409 with a pei_ failed intent. Recover via reviso_document_failed_intent or reviso_document_list_failed_intents, reread, reapply, then reviso_document_resolve_failed_intent. merged_over_stale_base reports version/cursor drift; null means no durable append evidence. applied_against_version_id/update_seq identify the actual pre-append state. changes and change_summary compare that state with the committed version; unavailable change_scope means no proven comparison. Copy current IDs/hashes from committed_blocks. Reuse idempotency_key only for retries of the same edit; verbosity=minimal omits unchanged blocks and full bodies. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"agent_name": {"default": "Agent", "type": "string"}, "attempt": {"description": "Optional retry attempt number recorded with the committed version for retry provenance.", "type": "integer"}, "base_update_seq": {"description": "Copy update_seq from the SAME read_structure call as base_version_id: the LIVE CRDT cursor, never a version row's resolved_update_seq; omitted or 0 uses the saved version, and hashes still protect concurrent edits.", "minimum": 0, "type": "integer"}, "base_version_id": {"description": "The version_id you read structure against (ver_...).", "type": "string"}, "description": {"description": "Brief explanation of this edit, recorded with the new version.", "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "idempotency_key": {"description": "Reuse across retries of the SAME edit: returns the first committed result without reapplying. Use a new key for a new edit.", "type": "string"}, "note": {"description": "Optional free-form note recorded alongside the resulting version (e.g. why this retry ran).", "type": "string"}, "ops": {"description": "Atomic block edits. Markdown is limited to 200,000 UTF-8 bytes per operation. range_edit_block rejects table/code blocks; use replace_block for those.", "items": {"oneOf": [{"additionalProperties": false, "properties": {"base_block_hash": {"description": "Copy block_hash from read_structure; do not recompute.", "minLength": 1, "type": "string"}, "block_id": {"minLength": 1, "type": "string"}, "replacement_markdown": {"description": "Exactly one nonempty Markdown block, including a heading. To add paragraphs use insert_before_block or insert_after_block. To split a block, replace it with the first paragraph and insert the rest after it in the same batch.", "minLength": 1, "pattern": "\\S", "type": "string"}, "type": {"const": "replace_block"}}, "required": ["type", "block_id", "base_block_hash", "replacement_markdown"], "type": "object"}, {"additionalProperties": false, "properties": {"base_block_hash": {"description": "Copy block_hash from read_structure; do not recompute.", "minLength": 1, "type": "string"}, "block_id": {"minLength": 1, "type": "string"}, "type": {"const": "delete_block"}}, "required": ["type", "block_id", "base_block_hash"], "type": "object"}, {"additionalProperties": false, "properties": {"after_block_id": {"minLength": 1, "type": "string"}, "base_after_block_hash": {"description": "Copy block_hash from read_structure; do not recompute.", "minLength": 1, "type": "string"}, "base_next_block_id": {"description": "Copy next_block_id of the anchor, including null at the end.", "type": ["string", "null"]}, "markdown": {"minLength": 1, "pattern": "\\S", "type": "string"}, "type": {"const": "insert_after_block"}}, "required": ["type", "after_block_id", "base_after_block_hash", "base_next_block_id", "markdown"], "type": "object"}, {"additionalProperties": false, "properties": {"base_before_block_hash": {"description": "Copy block_hash from read_structure; do not recompute.", "minLength": 1, "type": "string"}, "base_previous_block_id": {"description": "Copy previous_block_id of the anchor, including null at the start.", "type": ["string", "null"]}, "before_block_id": {"minLength": 1, "type": "string"}, "markdown": {"minLength": 1, "pattern": "\\S", "type": "string"}, "type": {"const": "insert_before_block"}}, "required": ["type", "before_block_id", "base_before_block_hash", "base_previous_block_id", "markdown"], "type": "object"}, {"additionalProperties": false, "properties": {"base_block_hash": {"description": "Copy block_hash from read_structure; do not recompute.", "minLength": 1, "type": "string"}, "block_id": {"minLength": 1, "type": "string"}, "end": {"description": "Exclusive Unicode code point offset in the block's Markdown; start <= end <= code point length. An astral emoji counts as 1, not 2 UTF-16 units.", "minimum": 0, "type": "integer"}, "replacement_text": {"description": "May be empty, but the resulting block must remain nonempty.", "type": "string"}, "start": {"description": "Zero-based Unicode code point offset in the block markdown from reviso_document_read_structure, not UTF-16 units or UTF-8 bytes. An astral emoji counts as 1; JavaScript: Array.from(markdown).", "minimum": 0, "type": "integer"}, "type": {"const": "range_edit_block"}}, "required": ["type", "block_id", "base_block_hash", "start", "end", "replacement_text"], "type": "object"}]}, "maxItems": 50, "minItems": 1, "type": "array"}, "run_id": {"description": "Optional agent run/session id recorded with the committed version for retry provenance.", "type": "string"}, "schema_version": {"description": "Optional read_structure schema_version the preconditions were captured under. Validated: a version the server does not speak is rejected (VALIDATION_FAILED).", "type": "integer"}, "source_format": {"description": "Only markdown documents support block/range patching.", "enum": ["markdown"], "type": "string"}, "verbosity": {"default": "minimal", "description": "Defaults to minimal: changed committed_blocks, removed_blocks and merge metadata, without unchanged blocks or full Markdown/HTML. Includes neighbors. Without append evidence: addressed blocks, change_scope=unavailable. Explicit full includes all committed blocks and available full bodies; retries may omit bodies (retrieve the committed version when needed). Safe to change verbosity on retry.", "enum": ["minimal", "full"], "type": "string"}}, "required": ["document_id", "ops", "base_version_id", "description"], "type": "object"}
• reviso_document_status (read): Get a review's status and latest-version metadata (title, current_version_id, version_no, source_format, lifecycle_status) without the document body. Use current_version_id as base_version_id for an update or rollback. For permission details, call reviso_document_retrieve with include=['access']. Distinct from the live CRDT cursor: read_structure.update_seq is the cursor reviso_document_apply_patch takes as base_update_seq, while a version row's resolved_update_seq is the stream cursor sealed into that version when it was committed. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_document_rollback (write): Roll a review's document back to an earlier version, creating a NEW version whose content equals the target version. CAS-protected: base_version_id must equal current_version_id from reviso_document_status, otherwise the call is rejected as a conflict. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"base_version_id": {"description": "Current latest version_id for CAS (ver_...).", "type": "string"}, "description": {"description": "Why the rollback is happening.", "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "target_version_id": {"description": "Version whose content is restored (ver_...).", "type": "string"}}, "required": ["document_id", "target_version_id", "base_version_id", "description"], "type": "object"}
• reviso_event_wait (read): Read events on a review newer than after_seq. Returns immediately by default; pass timeout to long-poll, blocking up to that many seconds when nothing is waiting. Each event carries seq (the cursor to pass back as after_seq), event_type (e.g. version_updated, comment_added, thread_resolved), and a payload object; poll again with the returned cursor to stream changes. SEQ IS A GLOBAL SERVER COUNTER, not a per-document one: it is allocated by one sequence shared by every document and every workspace, so the seqs you see for ONE document are sparse and a gap between two consecutive events (e.g. 2214 -> 2218) is NORMAL and never means events were lost. Do not use gap-freeness as an integrity check, and do not infer event counts from seq arithmetic. Events are also retained for a bounded window and are best-effort, so treat after_seq as an opaque high-water cursor: pass back the maximum seq you have seen and re-read state with reviso_document_status or reviso_document_read_structure when you need a guaranteed-current view. Reads accessible data without changing persistent content or access state. Capabilities: receive_events. Input schema: {"properties": {"after_seq": {"default": 0, "description": "Return events with seq > this value.", "type": "integer"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "timeout": {"default": 0, "description": "Seconds to block waiting for the first event. The default 0 returns whatever is already there immediately; pass a value to long-poll.", "maximum": 60, "minimum": 0, "type": "integer"}}, "required": ["document_id"], "type": "object"}
• reviso_comment_list (read): List all comment threads for a review with messages and anchors. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_comment_create (write): Open a thread; severity is required and must be one of info, warning, or error. Inspect resolution/warnings: 'exact' means the anchor RESOLVES, relocated means normalized, document means unanchored; invalid anchors return 400. Browser checks whether resolved owned content has a positive-area layout box; server raises an 'anchor_unpainted' event if absent. This does not prove viewport visibility or absence of ancestor clipping. Poll reviso_event_wait after publishing (full profile). Changes persistent content, comments or access state within the connection's permissions. Capabilities: comment. Input schema: {"additionalProperties": false, "properties": {"agent_name": {"description": "Agent name (max 64 chars)", "maxLength": 64, "type": "string"}, "anchor": {"description": "Omit for a document comment; do not send a \"type\" field. Deck: retrieve content/version_id; find the page by section order, then send {\"slide_id\":\"data-slide-id\",\"version_id\":\"...\"}, optionally \"element_id\" from data-element-id. Quote alone cannot navigate slides. Element quote must be full text.", "oneOf": [{"additionalProperties": false, "properties": {}, "title": "document comment", "type": "object"}, {"additionalProperties": false, "properties": {"occurrence": {"description": "1-based match index; defaults to 1.", "minimum": 1, "type": "integer"}, "quote": {"description": "Use rendered quote/text from reviso_document_retrieve include:[\"blocks\"], not Markdown source. Whitespace is collapsed (max 200 characters).", "maxLength": 200, "minLength": 1, "type": "string"}}, "required": ["quote"], "title": "quote anchor", "type": "object"}, {"additionalProperties": false, "properties": {"block_id": {"description": "From reviso_document_retrieve include:[\"blocks\"].", "pattern": "^blk_[0-9a-f]{12}(_\\d+)?$", "type": "string"}, "quote": {"description": "Use rendered quote/text from reviso_document_retrieve include:[\"blocks\"], not Markdown source. Whitespace is collapsed (max 200 characters). Optional; omitted uses the block's first line.", "maxLength": 200, "minLength": 1, "type": "string"}}, "required": ["block_id"], "title": "block anchor", "type": "object"}, {"additionalProperties": false, "properties": {"slide_id": {"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string"}, "version_id": {"maxLength": 100, "minLength": 1, "type": "string"}}, "required": ["slide_id", "version_id"], "title": "slide anchor", "type": "object"}, {"additionalProperties": false, "properties": {"element_id": {"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,159}$", "type": "string"}, "quote": {"maxLength": 10000, "type": "string"}, "slide_id": {"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string"}, "version_id": {"maxLength": 100, "minLength": 1, "type": "string"}}, "required": ["slide_id", "version_id", "element_id"], "title": "slide element anchor", "type": "object"}], "type": "object"}, "body": {"description": "Comment body text. @mentions in body are auto-parsed.", "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "mentions": {"description": "Optional explicit mention targets.", "items": {"type": "string"}, "type": "array"}, "severity": {"description": "Severity level: one of info, warning, error. info = an observation or suggestion, warning = a problem that should be addressed, error = a blocking defect.", "enum": ["info", "warning", "error"], "type": "string"}}, "required": ["document_id", "agent_name", "severity", "body"], "type": "object"}
• reviso_comment_create_batch (write): Create several independent threads; quote/block anchors share the current version, slide anchors use their explicit viewed version; each entry needs severity -- info, warning, or error -- and body. No rollback: HTTP 200 may include failures. Inspect results in input order: index, ok, attempted, and comment (with resolution/warnings) or error. attempted:false means rate limiting stopped the batch before that entry was written; resend only those entries. created/failed are counts. Changes persistent content, comments or access state within the connection's permissions. Capabilities: comment. Input schema: {"additionalProperties": false, "properties": {"agent_name": {"description": "Agent name (max 64 chars). Applies to every entry.", "maxLength": 64, "type": "string"}, "comments": {"description": "The findings to publish, at most 50 per call.", "items": {"properties": {"anchor": {"description": "Omit for a document comment; do not send a \"type\" field. Deck: retrieve content/version_id; find the page by section order, then send {\"slide_id\":\"data-slide-id\",\"version_id\":\"...\"}, optionally \"element_id\" from data-element-id. Quote alone cannot navigate slides. Element quote must be full text.", "oneOf": [{"additionalProperties": false, "properties": {}, "title": "document comment", "type": "object"}, {"additionalProperties": false, "properties": {"occurrence": {"description": "1-based match index; defaults to 1.", "minimum": 1, "type": "integer"}, "quote": {"description": "Use rendered quote/text from reviso_document_retrieve include:[\"blocks\"], not Markdown source. Whitespace is collapsed (max 200 characters).", "maxLength": 200, "minLength": 1, "type": "string"}}, "required": ["quote"], "title": "quote anchor", "type": "object"}, {"additionalProperties": false, "properties": {"block_id": {"description": "From reviso_document_retrieve include:[\"blocks\"].", "pattern": "^blk_[0-9a-f]{12}(_\\d+)?$", "type": "string"}, "quote": {"description": "Use rendered quote/text from reviso_document_retrieve include:[\"blocks\"], not Markdown source. Whitespace is collapsed (max 200 characters). Optional; omitted uses the block's first line.", "maxLength": 200, "minLength": 1, "type": "string"}}, "required": ["block_id"], "title": "block anchor", "type": "object"}, {"additionalProperties": false, "properties": {"slide_id": {"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string"}, "version_id": {"maxLength": 100, "minLength": 1, "type": "string"}}, "required": ["slide_id", "version_id"], "title": "slide anchor", "type": "object"}, {"additionalProperties": false, "properties": {"element_id": {"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,159}$", "type": "string"}, "quote": {"maxLength": 10000, "type": "string"}, "slide_id": {"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string"}, "version_id": {"maxLength": 100, "minLength": 1, "type": "string"}}, "required": ["slide_id", "version_id", "element_id"], "title": "slide element anchor", "type": "object"}], "type": "object"}, "body": {"description": "Comment body text. @mentions in body are auto-parsed.", "type": "string"}, "mentions": {"description": "Optional explicit mention targets.", "items": {"type": "string"}, "type": "array"}, "severity": {"description": "Severity level: one of info, warning, error. info = an observation or suggestion, warning = a problem that should be addressed, error = a blocking defect.", "enum": ["info", "warning", "error"], "type": "string"}}, "required": ["severity", "body"], "type": "object"}, "maxItems": 50, "minItems": 1, "type": "array"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id", "agent_name", "comments"], "type": "object"}
• reviso_comment_reply (write): Reply to an existing comment thread. Changes persistent content, comments or access state within the connection's permissions. Capabilities: comment. Input schema: {"additionalProperties": false, "properties": {"body": {"type": "string"}, "thread_id": {"type": "string"}}, "required": ["thread_id", "body"], "type": "object"}
• reviso_comment_resolve (write): Resolve an existing comment thread after addressing it. reason must be one of answered, fixed_in_version, wont_fix, duplicate. Etiquette: close the loop with the human by passing reply -- it posts your closing message on the thread in the same call, so the person who wrote the comment sees what was done. A reply failure aborts the resolve (retry, or drop reply to resolve silently). Changes persistent content, comments or access state within the connection's permissions. Capabilities: comment. Input schema: {"additionalProperties": false, "properties": {"reason": {"default": "answered", "description": "Why the thread is being closed. Must be one of the listed values.", "enum": ["answered", "fixed_in_version", "wont_fix", "duplicate"], "type": "string"}, "reply": {"description": "Optional closing message posted on the thread in the same call, so the human sees what was done. A reply failure aborts the resolve.", "type": "string"}, "thread_id": {"type": "string"}}, "required": ["thread_id"], "type": "object"}
• reviso_list_workspaces (read): List accessible workspaces with id/name/type aliases and a personal-or-only workspace recommendation. Pass the chosen workspace_id explicitly when creating in an account with multiple workspaces; recommendations never change permissions. legacy_default is not canonical. Reads accessible data without changing persistent content or access state. Capabilities: . Input schema: {"properties": {}, "required": [], "type": "object"}
• reviso_document_list_failed_intents (read): List open failed CRDT intents (pei_...) after a 409 edit-vs-edit or delete-vs-edit conflict. Each row includes conflicted_block_ids, actor and attempted_content for recovery; no concurrent edit was overwritten. Reads accessible data without changing persistent content or access state. Capabilities: edit_file. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_document_failed_intent (read): Read an open pei_ recovery frame: attempted_content (whole-document Markdown), conflicted_block_ids and base_version_id. Review, reread_structure, then reapply against a fresh base. Resolved/discarded intents reject. Reads accessible data without changing persistent content or access state. Capabilities: edit_file. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "intent_id": {"description": "The failed-intent handle (pei_...)", "type": "string"}}, "required": ["document_id", "intent_id"], "type": "object"}
• reviso_document_resolve_failed_intent (write): Close an open pei_ intent: resolved after reapplying against a fresh base; discarded to accept the live head; comment after exhausted retries to hand off as a warning-severity agent comment with attempted-content preview anchored to the first conflicted block, then discard. Prefer comment when unable to recover; never silently lose the blocked edit. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "intent_id": {"description": "The failed-intent handle (pei_...)", "type": "string"}, "resolution": {"description": "'resolved' (re-applied), 'discarded' (took latest), or 'comment' (exhausted retries \u2014 surface as a human-visible agent comment, then discard).", "enum": ["resolved", "discarded", "comment"], "type": "string"}}, "required": ["document_id", "intent_id", "resolution"], "type": "object"}
• reviso_document_signal_activity (ephemeral_write): Report your ephemeral activity on a review so humans and other agents can see who is working on which block (presence + soft lease). EXPERIENCE layer only: this NEVER changes the document, never gates or blocks a write, and never affects an apply_patch result -- it is a best-effort display signal. activity_state is what you are doing: 'reading' (inspecting structure), 'preparing' (composing a patch), 'applying' (writing), 'retrying' (re-applying after a conflict), 'self_reviewing' (checking a committed edit). Pass block_id to advertise a SOFT lease on the block you are working -- advisory only, it does not stop anyone else from editing that block. Call with done=true (or activity_state='idle') to release your presence when you finish or step away. Heartbeat again to refresh; presence ages out on its own if you go silent. Updates temporary activity or presence without changing persistent document content. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"activity_state": {"description": "What you are doing. 'idle' releases your presence (same as done=true).", "enum": ["reading", "preparing", "applying", "retrying", "self_reviewing", "idle"], "type": "string"}, "block_id": {"description": "Optional block (blk_...) you are working on -- a SOFT advisory lease, never a write gate.", "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "done": {"description": "Release your presence row (finished / stepping away).", "type": "boolean"}}, "required": ["document_id"], "type": "object"}
• reviso_create_invite (write): Share a document with a person. Registered accounts receive a direct grant; new guests receive a one-time invite URL. Repeating a pending invite preserves its original access and does not return its token again. Changes persistent content, comments or access state within the connection's permissions. Capabilities: manage_members. Input schema: {"additionalProperties": false, "properties": {"access": {"default": "comment", "enum": ["view", "comment", "edit"], "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "email": {"type": "string"}}, "required": ["document_id", "email"], "type": "object"}
• reviso_list_invites (read): List document collaboration invites without exposing invite tokens or token hashes. Reads accessible data without changing persistent content or access state. Capabilities: manage_members. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_revoke_invite (write): Revoke a pending document collaboration invite. Does not remove accepted collaborators. Changes persistent content, comments or access state within the connection's permissions. Capabilities: manage_members. Input schema: {"additionalProperties": false, "properties": {"invite_id": {"type": "string"}}, "required": ["invite_id"], "type": "object"}
• reviso_share_create (write): Create a public share link so anyone can open the document without an account. Returns share_url (self-contained link with the access token) and browser_url (plain document URL). Access is view or comment only — share links cannot grant edit. Changes persistent content, comments or access state within the connection's permissions. Capabilities: manage_members. Input schema: {"additionalProperties": false, "properties": {"access": {"default": "view", "description": "What anyone with the link can do.", "enum": ["view", "comment"], "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "expires_at": {"description": "Optional ISO-8601 expiry.", "type": "string"}, "label": {"description": "Optional human label for the link.", "type": "string"}, "password": {"description": "Optional password protecting the link.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_share_list (read): List the share links on a document, including revoked and expired ones. Never exposes tokens or token hashes. Reads accessible data without changing persistent content or access state. Capabilities: manage_members. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_share_revoke (write): Revoke a share link. Existing sessions opened through it are closed; the link stops working for new visitors. Changes persistent content, comments or access state within the connection's permissions. Capabilities: manage_members. Input schema: {"additionalProperties": false, "properties": {"share_id": {"description": "Share link id (shr_...).", "type": "string"}}, "required": ["share_id"], "type": "object"}
• reviso_list_documents (read): List documents visible to this connection, newest first, with compact metadata and comment counts. Follow next_offset while has_more is true. Use it to find a review_id. Pass archived=true to list the recycle bin instead of the active documents. Reads accessible data without changing persistent content or access state. Capabilities: . Input schema: {"properties": {"archived": {"default": false, "description": "List deleted documents (recycle bin) instead of active ones.", "type": "boolean"}, "limit": {"default": 50, "maximum": 100, "minimum": 1, "type": "integer"}, "offset": {"default": 0, "minimum": 0, "type": "integer"}, "workspace_id": {"description": "Optional. Restrict to one workspace; see reviso_list_workspaces.", "type": "string"}}, "required": [], "type": "object"}
• reviso_search_documents (read): Search visible documents by title and metadata. Pass include_content=true to search live content. Each call examines up to 100 visible documents; follow next_offset while has_more is true, even if matches is empty. Reads accessible data without changing persistent content or access state. Capabilities: . Input schema: {"properties": {"archived": {"default": false, "type": "boolean"}, "include_content": {"default": false, "description": "Also read latest visible content to find and return a snippet.", "type": "boolean"}, "limit": {"default": 10, "maximum": 50, "minimum": 1, "type": "integer"}, "offset": {"default": 0, "description": "Continuation: use next_offset from the previous result with the same query and scope.", "minimum": 0, "type": "integer"}, "query": {"maxLength": 500, "type": "string"}, "workspace_id": {"description": "Optional. Restrict to one workspace.", "type": "string"}}, "required": ["query"], "type": "object"}
• reviso_document_rename (write): Rename a document: set the title metadata that file lists, cards, and search results show. By default this only changes metadata and never the body. Two modes. (1) Metadata rename (default): send title with required base_version_id, base_content_hash and expected_title to check the observed document; works on every document kind, including html and html_deck. (2) Heading sync (sync_heading=true): Markdown documents only, atomically renames AND rewrites the sole top-level H1 in one version. Heading sync additionally requires description and operation_id (they are recorded on the new version) and the edit_file capability; a document with no Markdown H1 returns a validation error naming the metadata path instead. In both modes the preconditions are the top-level base_version_id and content_hash from ONE reviso_document_read_structure call plus the current name from reviso_document_status -- do not pass the content_hash of a reviso_document_update or reviso_document_retrieve receipt, which digests the committed canonical content and will not match. A stale precondition returns CAS_CONFLICT with the expected values in details; nothing is changed. Changes persistent content, comments or access state within the connection's permissions. Capabilities: rename_file. Input schema: {"additionalProperties": false, "properties": {"base_content_hash": {"description": "Precondition: the TOP-LEVEL content_hash from reviso_document_read_structure. Do not pass the content_hash of a reviso_document_update or reviso_document_retrieve receipt: that digests the committed canonical content and always fails this check.", "type": "string"}, "base_version_id": {"description": "Precondition: the live base_version_id from the SAME reviso_document_read_structure call as base_content_hash.", "type": "string"}, "description": {"description": "Recorded on the new version. Requires sync_heading=true, which is the mode that creates one.", "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "expected_title": {"description": "Precondition: the current name, read from reviso_document_status or the document's own status fields. A concurrent rename rejects the whole call.", "type": "string"}, "operation_id": {"description": "Exactly-once id for the sync_heading write. Requires sync_heading=true; a metadata-only rename creates no version to record it, and is naturally idempotent.", "maxLength": 199, "minLength": 4, "pattern": "^op_[A-Za-z0-9_-]{1,196}$", "type": ["string", "null"]}, "sync_heading": {"default": false, "description": "True also rewrites the document's sole top-level Markdown H1 in the same transaction. Markdown documents only; a document with no Markdown H1 (html, html_deck) cannot synchronize a heading.", "type": "boolean"}, "title": {"description": "New document name, 1-160 characters after trimming.", "maxLength": 160, "type": "string"}}, "required": ["document_id", "title", "base_version_id", "base_content_hash", "expected_title"], "type": "object"}
• reviso_document_delete (write): Delete a document. This is a soft delete: the document moves to the recycle bin and can be brought back with reviso_document_restore. It is the same action as the delete button in the browser. Changes persistent content, comments or access state within the connection's permissions. Capabilities: archive_file. Input schema: {"additionalProperties": false, "properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_document_restore (write): Restore a document previously deleted with reviso_document_delete, taking it out of the recycle bin. Changes persistent content, comments or access state within the connection's permissions. Capabilities: archive_file. Input schema: {"additionalProperties": false, "properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_connection_self (read): Connection identity, workspaces, tools and editing_features. Availability follows profile and grant; optional document_id checks its format and permissions. Reads accessible data without changing persistent content or access state. Capabilities: . Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": [], "type": "object"}
• reviso_favorite_add (write): Favorite an accessible document for the connected account. Repeating the call keeps it favorited; returns document_id and favorited. Changes persistent content, comments or access state within the connection's permissions. Capabilities: view. Input schema: {"additionalProperties": false, "properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_favorite_remove (write): Remove a document from the connected account's favorites. Requires current view access; repeating the call is safe. Changes persistent content, comments or access state within the connection's permissions. Capabilities: view. Input schema: {"additionalProperties": false, "properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_favorite_list (read): List the connected account's favorites that this connection can currently view. Returns one page of lightweight document summaries; revoked access is filtered out. While has_more is true, pass next_offset as offset, even when a page has no visible favorites. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"limit": {"default": 100, "maximum": 100, "minimum": 1, "type": "integer"}, "offset": {"default": 0, "minimum": 0, "type": "integer"}}, "required": [], "type": "object"}
• reviso_version_label (write): Name or group an existing saved version. Read versions with reviso_document_retrieve include=[versions] first; copy label_revision. Content, version IDs, compare and restore history remain unchanged. Concurrent label edits fail closed. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "group_label": {"description": "Group related saved versions without deleting any history; empty clears it.", "maxLength": 120, "type": "string"}, "label": {"description": "Version name; empty string clears it.", "maxLength": 120, "type": "string"}, "label_revision": {"description": "Copy from versions; use 0 for a version without labels.", "minimum": 0, "type": "integer"}, "version_id": {"type": "string"}}, "required": ["document_id", "version_id", "label", "group_label", "label_revision"], "type": "object"}
• reviso_document_links (read): Read rendered web links with actual target (_blank or _self), exact block/hash/URL/occurrence selectors, document policy and write preconditions. Same URL appearing twice has separate selectors. Fragment, mail and phone links retain native navigation. Stale overrides are reported and ignored. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_document_set_link_policy (write): Set the document web-link default and exact per-link overrides. Read document_links and copy base_version_id, update_seq, policy_revision first. _blank opens a new tab, _self the current tab; both use noopener/noreferrer. Overrides replace the list and bind saved block content; changed blocks invalidate old overrides. Settings apply to web rendering; plain Markdown exports cannot store navigation metadata. Changes persistent content, comments or access state within the connection's permissions. Capabilities: edit_file. Input schema: {"additionalProperties": false, "properties": {"base_version_id": {"type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "policy": {"additionalProperties": false, "properties": {"overrides": {"items": {"additionalProperties": false, "properties": {"block_hash": {"type": "string"}, "block_id": {"type": "string"}, "href": {"type": "string"}, "occurrence": {"minimum": 0, "type": "integer"}, "target": {"enum": ["_blank", "_self"], "type": "string"}}, "required": ["block_id", "block_hash", "href", "occurrence", "target"], "type": "object"}, "maxItems": 100, "type": "array"}, "web_target": {"enum": ["_blank", "_self"], "type": "string"}}, "required": ["web_target", "overrides"], "type": "object"}, "policy_revision": {"minimum": 0, "type": "integer"}, "update_seq": {"minimum": 0, "type": "integer"}}, "required": ["document_id", "policy", "base_version_id", "update_seq", "policy_revision"], "type": "object"}
• reviso_document_usage (read): Measure live document source, blocks, table cells and images against document limits. The response identifies whether enforcement is active; legacy workspaces require adoption. Reads accessible data without changing persistent content or access state. Capabilities: view. Input schema: {"properties": {"document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}}, "required": ["document_id"], "type": "object"}
• reviso_workspace_usage (read): Read workspace usage and Free/Pro entitlements, or legacy observation totals before adoption. Requires workspace usage permission. Use a cleanup preview for reclaimable bytes. Reads accessible data without changing persistent content or access state. Capabilities: view_workspace_usage. Input schema: {"properties": {"workspace_id": {"type": "string"}}, "required": ["workspace_id"], "type": "object"}
• reviso_document_upload_image (write): Upload a PNG/JPEG/GIF/WebP image (at most 5 MiB decoded) to a writable document. Send raw Base64, not a data URL. Reuse operation_id only for identical retries. Returns an image URL; insert it with a document update to publish. Unpublished uploads are private to the uploader and protected for 24 hours, or 7 days with draft_session_id. Retrying does not extend protection. Changes persistent content, comments or access state within the connection's permissions. Capabilities: upload_asset. Input schema: {"additionalProperties": false, "properties": {"content_type": {"enum": ["image/png", "image/jpeg", "image/gif", "image/webp"], "type": "string"}, "data_base64": {"maxLength": 6990508, "type": "string"}, "document_id": {"description": "The document id, doc_<12hex>. The bare 12-hex key from a /documents/<key> URL is also accepted. Call reviso_list_documents if you do not have one; the legacy rev_ prefix was retired and now 404s.", "type": "string"}, "draft_session_id": {"maxLength": 120, "type": "string"}, "file_name": {"type": "string"}, "operation_id": {"maxLength": 120, "minLength": 1, "type": "string"}}, "required": ["document_id", "content_type", "data_base64", "operation_id"], "type": "object"}
• reviso_deck_contract (read): Read the complete html-deck/1 authoring contract before submitting an html_deck: the required fragment shape (a leading doctype declaration is fine, but the html, head and body elements are NOT allowlisted and are rejected as unknown_tag), the tag/attribute/CSS allowlists, the 1280x720 canvas rules, the limits, and the Chromium geometry checks. Returns authoring_rules (with the rule id that explains the failure), a skeleton_fragment that already validates, and the field meanings of a rejection. Needs no document and no capability. Deck writes are all-or-nothing: a rejected submission stores nothing, and details.diagnostics carries every violation from every layer in one response. Reads accessible data without changing persistent content or access state. Capabilities: . Input schema: {"properties": {}, "required": [], "type": "object"}