Four connections, one contract
| Connection | How it is obtained | Reaches | Typical use |
|---|---|---|---|
| Account | OAuth 2.1 from the app | Every document you own | Long-running work, “continue last month’s draft” |
| Document link | Hand off → copy link, per document | One document, live copy | Send one file to one client |
| Review link | Share for review, per snapshot | One frozen round | An AI acting as a reviewer |
| Anonymous | No credential | Documents it creates in that session | Trying it without a signup |
tools/list only returns what that connection can actually call, so a client
that connects with a review link will not see list_documents at all. If you are
writing an integration, discover the surface at runtime instead of assuming it.
Read
Nothing here changes the document.
| Tool | What it does | Doc | Review | Account |
|---|---|---|---|---|
get_tool_guide | Full contract for one or more tools: parameters, limits, next calls. Use it before a tool whose summary is ambiguous. | ✓ | ✓ | ✓ |
get_document | Read one document. Long documents return a map first; drill into a section or a page instead of reading a book page by page. | ✓ | ✓ | ✓ |
list_documents | List and filter documents by title, tag or modification time. Not full-text search. | — | — | ✓ |
get_document_history | The rounds of a review, with a diff against the current text. | — | ✓ | — |
get_active_document | The one document this session is bound to, from the grant: id, title, size, expiry. | — | ✓ | — |
list_comments | Every comment thread: quoted text, all messages, intent, whose turn it is, status. | ✓ | ✓ | ✓ |
list_edit_requests | Threads the user marked for revision where it is the AI’s turn. | ✓ | — | ✓ |
Propose
The write path. Nothing lands in the body until the user accepts a hunk.
| Tool | What it does | Doc | Review | Account |
|---|---|---|---|---|
suggest_revision | Propose a change: replace a verbatim span, rewrite a section, rewrite the whole document, or restore a version. | ✓ | ✓ | ✓ |
get_revision | Read one proposal in full: text, reason, current state. | ✓ | ✓ | ✓ |
get_review_status | What the user did with it: pending, accepted, partial (which hunks), rejected, withdrawn. Can wait for the answer. | ✓ | ✓ | ✓ |
withdraw_revision | Take back one of your own proposals that has not been reviewed yet. | ✓ | ✓ | ✓ |
add_comment | Add a comment or question anchored to a verbatim quote. Does not change the text. | ✓ | ✓ | ✓ |
reply_to_comment | Reply inside a thread, signed with your name, and hand the turn back to the user. | ✓ | ✓ | ✓ |
Write
Direct writes, scoped to the connection. On a document the user has opened for editing, edits become proposals instead.
| Tool | What it does | Doc | Review | Account |
|---|---|---|---|---|
create_document | Create a new document. Never overwrites an existing one. | — | — | ✓ |
edit_document | Apply precise edits via verbatim quote anchors. In draft phase it writes; once the user has edited, it is converted to proposals. | ✓ | — | ✓ |
append_to_document | Append text to the end of a document, to one section, or to today’s note. Additive only. | ✓ | — | ✓ |
show_document | Show the document to the user and scroll to a section or quote. Read-only by contract. | ✓ | ✓ | ✓ |
Deliver
Getting the finished text out.
| Tool | What it does | Doc | Review | Account |
|---|---|---|---|---|
export_document | Export to docx, pdf or html. Online returns a download URL; desktop saves beside the original. | ✓ | — | ✓ |
create_review_link | Create a no-signup review link with an expiry window. | ✓ | — | ✓ |
revoke_review_link | Revoke a link, optionally blocking one reviewer. Comments already collected stay. | ✓ | — | ✓ |
The rules that do not change
- A proposal is not a write.
suggest_revisionlands nothing in the body; the document records a proposal and waits for a person. - Anchors are verbatim. Edits and comments quote the text they target. A stale quote fails loudly and returns candidate snippets so the model can retry — it never guesses a nearby position.
- No file-writing tools. The server rejects edits made with the model’s own filesystem tools; the only path into a document is this contract.
- Identities are derived, not declared. Who wrote a comment or a proposal comes from the credential. A caller cannot claim to be the author.
- Reads are bounded. A single
get_documentreturns a map for long documents and truncates at 100k characters with an explicit note, rather than silently cutting the text.
A worked round
get_document(document_id) → pending_edit_requests_count: 1
list_edit_requests(document_id) → thread anchored at “the second paragraph”
# 2 · propose, do not write
suggest_revision(document_id, replace="…verbatim span…", with="…new text…")
# 3 · the user accepts part of it
get_review_status(revision_id, waitSeconds=60) → partial · hunks 1,3 accepted
# 4 · answer in the thread and hand the turn back
reply_to_comment(thread_id, "Took the first and third; left the second alone on purpose.")
When a tool changes
Tool names are stable; parameters occasionally are not. Every change to this surface is written down in the changelog with the tool name in the entry, so an integration can be checked against it instead of against a hope.