> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tool reference

> The document-local tools the SDK exposes to a model.

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

<ResponseField name="get_selection">
  The user's current semantic selection: text, caret or range positions,
  portable target segments, active formatting, comment IDs, suggestion IDs. No
  geometry.
</ResponseField>

<ResponseField name="read_blocks_from_index">
  Read consecutive blocks from a 0-based start index. The usual entry point.
</ResponseField>

<ResponseField name="read_specific_blocks">
  Read specific blocks by ID.
</ResponseField>

<ResponseField name="search_document">
  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.
</ResponseField>

<ResponseField name="find_highlights">
  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.
</ResponseField>

<ResponseField name="measure_document">
  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.
</ResponseField>

<ResponseField name="measure_blocks">
  The same measurements for an inclusive block range.
</ResponseField>

<ResponseField name="view_image">
  View a document image by block ID when its `src` is hidden.
</ResponseField>

<Note>
  Read tools return HTML with block IDs, not flattened text. The mutation tools
  below target those IDs.
</Note>

## Editing text

<ResponseField name="replace">
  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.
</ResponseField>

<ResponseField name="insert_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.
</ResponseField>

<ResponseField name="replace_block">
  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.
</ResponseField>

<ResponseField name="remove_blocks">
  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.
</ResponseField>

<ResponseField name="append_to_paragraph">
  Append HTML to an existing paragraph.
</ResponseField>

<ResponseField name="break_paragraph">
  Split a paragraph at the first occurrence of a substring.
</ResponseField>

<ResponseField name="join_paragraphs">
  Join two adjacent paragraphs, preserving the inline formatting of both.
</ResponseField>

## Formatting

<ResponseField name="style_blocks">
  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.
</ResponseField>

<ResponseField name="clear_formatting">
  Strip removable inline emphasis from the targets.
</ResponseField>

## Structure and layout

<ResponseField name="set_title">Change the document title.</ResponseField>

<ResponseField name="set_page_layout">
  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.
</ResponseField>

<ResponseField name="set_header_footer">
  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".
</ResponseField>

<ResponseField name="insert_footnote">
  Insert a numbered superscript reference and its note body. Endnotes are a
  separate stream.
</ResponseField>

## Tables

<ResponseField name="read_table">
  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`.
</ResponseField>

<ResponseField name="edit_table_cells">
  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.
</ResponseField>

<ResponseField name="insert_table_row" />

<ResponseField name="remove_table_rows">
  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.
</ResponseField>

<ResponseField name="insert_table_column" />

<ResponseField name="remove_table_column" />

<Warning>
  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.
</Warning>

## Comments

<ResponseField name="leave_comment">
  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`.
</ResponseField>

## Delegation

<ResponseField name="revise_run_agent">
  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](/developer/docs/developer/docs/editor-sdk/guides/delegated-agent).
</ResponseField>

## 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](/developer/docs/developer/docs/editor-sdk/api/handle).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.