editor.tools.getDefinitions() — they are the
document-local subset 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.
On Node, retrieve the headless subset from
(await createServerDocumentSession(ydoc, options)).tools.getDefinitions(). A
bound server session omits document_id from its schemas and descriptions
(untrusted calls use executeDynamic() and receive an explicit
{ ok: true, value } | { ok: false, error } result) and excludes only
get_selection and view_image from this document-local catalogue. It also
does not expose delegation, attachment import/storage, account document APIs,
or any viewport/canvas/UI operation. 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 blocks by ID, when you already know which ones you want.
Search text within one document — the cheap way to locate a term before
editing it. Results for the active document carry a
search_result_id
standing for the whole unpaginated match set; hand 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 colour. Highlights are not
visible in loaded content, so this is the only way to resolve “the
highlighted parts”. Paginated at 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.
Cheap — prefer it over reading the document to count things.
The same measurements for an inclusive block range.
View a document image by block ID when its
src is hidden.Editing text
The default tool for editing text inside a block: wording, sentences, typos,
punctuation, formatting-preserving rewrites. It keeps block identity and
untouched formatting, so prefer it over
replace_block unless the block’s
type or structure has to change. Each operation may carry its own comment,
attached to every suggestion it produces. Edits spanning blocks need one call
per block — or one call with search_result_id, which applies the same edits
independently in every matched 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.Replace whole consecutive block(s) with new HTML blocks, for structural or
block-type changes. Preserves block type unless asked otherwise. With
search_result_id the one-block replacement is applied independently to
every matched block.Remove blocks by consecutive range (
id + count), 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 remains an executable compatibility alias but is no
longer advertised to models.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 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. 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").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.A numbered superscript reference plus its note body. Endnotes are a separate
stream.
Tables
Comments
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.Two modes. To start a thread, pass the block
id plus 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 inherits the thread’s anchor.A new thread that overlaps an existing unresolved one is rejected, so an
agent cannot pile a second thread onto a passage it already commented on.
When the overlap is deliberate and the point genuinely different, list the
overlapping thread IDs in acknowledge_existing_thread_ids.Delegation
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. 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 tools in the external catalogue. Agents make semantic edits; your UI presents them. The delegated Revise agent is the exception for page inspection: it usesrender_document_pages internally
against the mounted browser canvas. See the handle reference.