Skip to main content
Get the live schemas with editor.tools.getDefinitions(). They are generated from the same source as Revise’s production agent. The descriptions below are summaries; the schemas are authoritative. Every tool accepts an optional document_id. Omit it for the active document. On Node, get the headless subset from (await createServerDocumentSession(ydoc, options)).tools.getDefinitions(). A server session is bound to one document:
  • Its schemas and descriptions omit document_id.
  • It excludes get_selection and view_image.
  • It has no delegation, attachment import or storage, account document APIs, or viewport, canvas, and UI operations.
  • Untrusted calls use executeDynamic() and receive { ok: true, value } | { ok: false, error }.
The definitions list exactly what its execute() accepts.

​
Reading and searching

​
The user’s current semantic selection: text, caret or range positions, portable target segments, active formatting, comment IDs, suggestion IDs. No geometry.
​
Read consecutive blocks from a 0-based start index. The usual entry point.
​
Read specific blocks by ID.
​
Search text within one document. Use it to locate a term before editing. Results for the active document include a search_result_id that stands for the whole unpaginated match set. Pass it to replace, replace_block, style_blocks, or remove_blocks to act on every match in one call. Displayed matches are paginated.
​
Find highlighted blocks, optionally filtered by color. Highlights are not visible in loaded content, so this is the only way to find “the highlighted parts”. Returns 25 blocks per page.
​
Word, paragraph, block, and rendered page counts without loading body text. Primary totals treat pending suggestions as accepted. When that differs from the visible Review state, the result also includes the original projection. Use it instead of reading the document to count.
​
The same measurements for an inclusive block range.
​
View a document image by block ID when its src is hidden.
Read tools return HTML with block IDs, not flattened text. The mutation tools below target those IDs.

​
Editing text

​
The default tool for editing text inside a block: wording, sentences, typos, punctuation, and rewrites that keep formatting. It keeps block identity and untouched formatting. Use replace_block only when the block’s type or structure changes. Each operation can carry a comment, attached to every suggestion it produces. Edits across blocks need one call per block, or one call with search_result_id, which applies the same edits in every matched block.
​
Insert one or more HTML blocks before or after a reference block. Notes can be inline: <sup data-footnote="Body.">1</sup> creates the footnote in the same call.
​
Replace one or more consecutive blocks with new HTML blocks, for structural or block-type changes. Keeps the block type unless asked otherwise. Name a range with id and end_id (inclusive, in the same container). With search_result_id, the one-block replacement applies to every matched block. A reversed, unknown, or cross-container range fails with invalid_block_range before anything changes.
​
Remove blocks by consecutive range (id through end_id, inclusive, in the same container), an exact ID batch (ids), everything from one block through the document tail (through_end), or every block in a search result (search_result_id). The old remove_block name still executes as an alias but is not listed in the definitions.
​
Append HTML to an existing paragraph.
​
Split a paragraph at the first occurrence of a substring.
​
Join two adjacent paragraphs, preserving the inline formatting of both.

​
Formatting

​
Bulk formatting with CSS-lite selectors: *, #blockId, p, h1 to h6, li, lists, tables, and inline selectors such as b, i, code, mark, and a, optionally scoped (p b, #blockId strong). Use it instead of rewriting text to restyle it. Pass search_result_id to scope the selectors to a search result. * then means each matched block.
​
Strip removable inline emphasis from the targets.

​
Structure and layout

​
Change the document title.
​
Preset, page size, orientation, margins, page numbers, spacing, pageless mode. Lengths are strings with explicit units ("1in", "2.54cm", "72px"). Page numbers can be decimal, lowerRoman, or upperRoman per section (pageNumberFormat). With sectionIndex, pageNumberStart restarts numbering and pageNumberRestart: false makes a section continue. Native pageBorders configures individual top, right, bottom, and left edges (style, color, widthPt, spacePt), with offsetFrom (page or text), display (allPages, firstPage, notFirstPage), and zOrder (front or back). Borders remain editable in Page Layout and appear in PDF and DOCX exports. Use clearPageBorders: true to remove them. Omitted fields leave existing borders unchanged.
​
Set header and footer content by zone (left, center, right). {PAGE} and {PAGES} are live fields. An empty string clears one zone. slot targets the default, first, or even page header or footer, and a one-based sectionIndex edits one section’s own. image places a logo in a zone: image_id of an image already in the document, with optional alt, width, and height. clear: true without slot or sectionIndex removes that side from every page and section. A call that changes nothing fails with “No changes detected”.
​
Insert a numbered superscript reference and its note body. Endnotes are a separate stream.

​
Tables

​
Read a bounded part of a table by table_id. mode: "summary" returns dimensions and per-column empty, filled, and covered-cell counts with no cell contents. mode: "rows" (the default) returns up to 50 rows, optionally limited to a column range, with merged-anchor spans and a next_read continuation. mode: "cell_text" pages through one oversized cell. Only cells returned in full by a rows read can be edited with edit_table_cells. A summary, a partial column range, or a partial cell_text window does not authorize edits to anything else. The native Revise agent’s task-declaration arguments are not part of this schema. A call that passes one fails with unsupported_argument.
​
Set the plain text of up to 50 cells in one call, addressed by table_id, stable row_id, and 0-based column. text is literal: 007, 1e5, <b>, tabs, and newlines are written exactly as given, never parsed as HTML or numbers. mode: "fill_if_empty" skips and reports cells that already have content. mode: "replace" overwrites cells read in their current state. An unread, unknown, duplicate, covered (merged), or changed target rejects the whole batch with no changes. Cells with rich content are refused; use the block tools on their nested block IDs. In suggesting mode each cell is a separate reviewable suggestion.
​
​
Removes one or more rows in one call. Name rows by rowIds (a row ID or an array of them); row IDs stay valid after other rows are inserted or removed. rowIndices is a fallback for rows read at the current table layout. Every cell of each row must have been read. An unknown, duplicate, or unread row rejects the whole call with no changes. The earlier remove_table_row name with { tableId, rowIndex } still works.
​
​
Read before you write. edit_table_cells needs a read_table rows read of its targets on the same session. The row and column tools need the target <table> in loaded context.

​
Comments

​
Leave review feedback anchored to one location without changing the text. Use it for critique instead of rewriting a passage the user did not ask to change.To start a thread, pass the block id and exactly one anchor form: { text } for a short exact range, { start_text, end_text } for a longer one, or { whole_block: true }. To reply, pass reply_to_comment_id (any comment ID in the thread) with no id and no anchor. The reply uses the thread’s anchor.A new thread that overlaps an existing unresolved thread is rejected. To comment on the same passage with a different point, list the overlapping thread IDs in acknowledge_existing_thread_ids.

​
Delegation

​
Hand a complete task to Revise’s multi-turn agent loop. Call it through tools.execute() like any other tool. It is excluded from getDefinitions(), so pass it to your model explicitly. The delegated browser agent can use its internal render_document_pages tool to inspect bounded appearance or layout renders from the mounted canvas. See delegating to the Revise agent.

​
Not exposed as tools

Review navigation, comment-panel state, focus, viewport geometry, zoom, and direct canvas rendering are not in the tool catalog. Agents make semantic edits, and your UI presents them. The delegated Revise agent is the one exception: it uses render_document_pages internally to inspect pages on the mounted browser canvas. See the handle reference.