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

# Agent tool reference

> Every tool the editor exposes to a model.

Retrieve the live schemas with `editor.tools.getDefinitions()` — they are
generated from the same source as Revise's production agent, so the
descriptions below are summaries, not the authoritative text.

Every tool accepts an optional `document_id`. Omit it for the active document.

## 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 blocks by ID, when you already know which ones you want.
</ResponseField>

<ResponseField name="search_document">
  Search text within one document.
</ResponseField>

<ResponseField name="find_highlights">
  Find highlighted blocks, optionally filtered by colour. Paginated at 25
  blocks per page.
</ResponseField>

<ResponseField name="measure_document">
  Word, paragraph, block, and rendered page counts without loading body text.
  Cheap — prefer it over reading the document to count things.
</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>

<Tip>
  Read tools return block-ID-preserving HTML rather than flattened text, and
  those IDs are exactly what the mutation tools below target.
</Tip>

## Editing text

<ResponseField name="replace">
  One or more small in-place edits **inside one block**, applied in order. Each
  operation may carry its own comment, attached to every suggestion it
  produces. Edits spanning blocks need one call per block.
</ResponseField>

<ResponseField name="insert_block">
  Insert HTML block(s) before or after a reference block. Notes can be embedded
  inline: `<sup data-footnote="Body.">1</sup>` creates the footnote in the same
  call.
</ResponseField>

<ResponseField name="replace_block">
  Replace consecutive block(s) with new HTML blocks. Preserves block type
  unless asked otherwise.
</ResponseField>

<ResponseField name="remove_block">
  Remove blocks by consecutive range (`id` + `count`) or an exact ID batch.
</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 through CSS-lite selectors — `*`, `#blockId`, `p`, `h1`–`h6`,
  `li`, lists, tables, and inline selectors such as `b`, `i`, `code`, `mark`,
  `a`, optionally scoped (`p b`, `#blockId strong`). Use this instead of
  rewriting text to restyle it.
</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"`).
</ResponseField>

<ResponseField name="set_header_footer">
  Header and footer content by zone (left, centre, right). `{PAGE}` and
  `{PAGES}` are live fields. An empty string clears one zone; `clear: true`
  removes the whole header or footer.
</ResponseField>

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

## Tables

<ResponseField name="insert_table_row" />

<ResponseField name="remove_table_row" />

<ResponseField name="insert_table_column" />

<ResponseField name="remove_table_column" />

<Warning>
  Table tools require the target `<table>` to be in loaded context. Read the
  table's blocks first.
</Warning>

## Comments

<ResponseField name="leave_comment">
  Granular review feedback anchored to one location, without changing the text.
  The right tool for critique — prefer it over rewriting a passage the user did
  not ask you to change.
</ResponseField>

## Delegation

<ResponseField name="revise_run_agent">
  Hand a complete task to Revise's own multi-turn agent loop. Callable through
  `tools.execute()` like any other tool. Excluded from `getDefinitions()` —
  pass it to your model explicitly if you want it available. See [delegating to
  the Revise agent](/guides/delegated-agent).
</ResponseField>

## Not exposed as tools

Review navigation, comment-panel state, focus, viewport geometry, and zoom are
host APIs. Agents make semantic edits; your UI presents them. See the [handle
reference](/api/handle).