Revise

View saved version →

---
name: revise
description: Revise renders a full word processor in the chat, shared between the user and you. Use it whenever the user wants to write, refine, edit, or get feedback on a piece of writing (an essay, report, letter, resume, story, contract), work on a .docx or other document file. Not needed for a quick one-off rewrite the user just wants back in chat, but should be used for iterative editing.
---

# Revise

Revise puts a real word processor in the conversation. The user sees the
document live and can edit it themselves while you work in it with the Revise
tools. Your edits show up as tracked changes they can accept or reject, and you
can leave comments anchored to specific passages. Documents can be imported
from .docx and other files and exported back to DOCX, PDF, and more.

Use it to start a new document or to work on one the user already has. When
the writing is the deliverable, put it in a Revise document instead of in
your reply.

- The document is the work. Don't paste its contents back into chat; reply
  with a short note on what you did and what's left for the user to review.
- When you write a first draft, put the whole draft in `create_document`, and
  give the document a real title.
- When asked for feedback, leave comments in the document instead of a list
  in chat.

## Working in a shared document

- The user edits too. Between your turns they may have rewritten passages or
  accepted or rejected your suggestions. After any gap, reread the part you're
  about to change (or call `get_recent_changes`) before editing it.
- Reads show your pending suggestions as if accepted, which doesn't mean the
  user accepted them. Don't stack new edits on passages that still have
  pending suggestions. When the user approves ("looks good", "lgtm"), call
  `resolve_suggestions` to accept them; when they withdraw them, reject them.
- Change existing documents with targeted edits and `style_blocks`, never by
  regenerating the whole thing. A full rewrite through markdown loses
  comments, footnotes, tables, styles, and formatting imported from Word.
- Use real structure: headings rather than bold paragraphs, real lists rather
  than typed "1.", and `insert_footnote` rather than "[1]". The outline, list
  numbering, and DOCX export depend on it.
- For academic papers, `set_page_layout` has an APA-7 preset.

## The document lives on

- It's saved in the user's Revise account; the link opens it in the full web
  editor, where they can come back to it later. Mention this when it's useful.
- The user can export and share from the document view. Call
  `export_document` when they want a file in chat, and match the format the
  document came in: a document imported from .docx goes back out as .docx.
- Only the user can make a document public; point them to Share instead of
  trying.

The tool descriptions and server instructions cover the details.

Referenced files: 1 — file references are metadata, not package contents.