---
name: sidecars-documents
description: Work on a Sidecars document through the Sidecars MCP server — find or create it, read it with its version, make the smallest edit, and run a resumable review loop over its comment threads (evaluate, edit, verify, reply, resolve). Use when asked to write into, update, or address the review on a Sidecars document.
compatibility: Needs the Sidecars MCP server connected (https://mcp.sidecars.ai/mcp, tools named sidecars/*). Any MCP host.
metadata:
  homepage: https://docs.sidecars.ai/skills
---

# Work on a Sidecars document

Sidecars documents are shared, live-edited by people, and versioned. Every
tool below is a Sidecars MCP tool; call it under whatever prefix your host
gives the `sidecars` server. Tool reference: https://docs.sidecars.ai/reference/documents
and https://docs.sidecars.ai/reference/comments.

## 1. Connect check

If no `sidecars` MCP tools are available, say so and point the person at
https://docs.sidecars.ai/connect. Never write a local file instead of the
Sidecars document the person asked for. The first document call may be
refused with `insufficient_scope`; the host re-runs consent — retry after it.

## 2. Locate, or create only when asked

- `list_documents` with the narrowest selector the person's words allow:
  `conversation_id` for a room, `pod_id` for a pod, `scope` for a library
  section, plus `query`. Follow `next_cursor` while it is a string. On the
  merged listing, `truncated: true` means narrow further, not "missing".
- `create_document` only when the person asked for a new document, and in
  the place they named: `conversation_id`, or `scope` (`user` | `pod` +
  `pod_id` | `org`). Do not widen visibility to make review easier; ask
  instead. Always pass an `idempotency_key` so a retry cannot create a twin.
- `list_conversations` resolves a room or pod name to its ids. A knowledge
  hit's `source_id` is never a document id.

## 3. Read, and keep the version

`read_document` returns markdown, `version`, and `parent.conversation_id`
when the document lives in a room. Page with `offset` while `truncated` is
true. Every write takes that `version` as `expected_version`.

## 4. Edit the smallest region

- `edit_document` `mode: "replace_section"` with `section_excerpt` quoted
  **from the read, not from text you wrote**: the served markdown normalises
  bullets (`-` becomes `*`) and renumbers list items, so a source-quoted
  excerpt fails. `excerpt_not_found` returns `candidates` (nearby passages
  as served) and `excerpt_ambiguous` returns `locations` (each place the
  excerpt occurs) — re-read, pick one and quote enough of it to be unique,
  retry once. Never append as a workaround for a failed section match.
- `append` adds a new section. `replace_all` only for a rewrite the person
  asked for, always with `expected_version`; it is refused on drift.
- A human may edit while you write: their blocks come back in `kept_blocks`.
  Keep them and say so. `stopped_early` with `next_step` means continue with
  a follow-up call. `write_conflict` means wait `retry_after_seconds`, once.
- Parallel `replace_section` calls with the same `expected_version` succeed
  but report `version_drift`; sequence edits when order matters.

## 5. Review loop — resumable, one thread at a time

1. `read_comments` (open threads only) and a fresh `read_document`. Each
   thread has `thread_id`, `anchor_excerpt` when it quotes a passage,
   `author_label`, `body` and `replies`. Group threads that touch the same
   passage; make one combined edit for overlapping asks.
2. **Evaluate before editing.** Classify each thread: a change request, a
   question, a suggestion that conflicts with another thread, something the
   text already addresses, or a decision only a person can make. Only change
   requests, and questions whose answer belongs in the document, get an edit.
3. **Resume safely.** Before editing for a thread, check whether the current
   text already reflects the ask — a previous run may have edited and then
   failed to reply. If so, skip to the reply. Never post a second reply that
   restates an existing one; read the thread's `replies` first.
4. Edit the anchored passage (or its enclosing section; an unanchored thread
   maps to the relevant heading, or `append` for a new section) → **read back
   and verify** the passage changed and its neighbours are intact →
   `add_comment` with `thread_id` and one or two sentences on what changed,
   or the answer → `resolve_comment` with `resolved: true`.
5. **Before each resolve, check for new threads.** Reviewers keep commenting
   while you work: call `read_comments` again before resolving; a thread that
   arrived since step 1 and touches the same passage joins the edit (one
   combined change) rather than being resolved past. Then resolve.
6. Leave a thread open, with a reply saying why, when the decision is the
   person's, the change was not possible, the ask conflicts with another open
   thread (name it), or resolve is refused for your role.
7. Finish with: threads resolved, threads left open and why, the new
   `version`.

## 6. Ask for a review

Give a second agent the `document_id` and this brief: read it with
`read_document`; leave one finding per `add_comment` thread with an
`anchor_excerpt` that appears exactly once; start the body with the severity
(blocker, major, minor); do not edit. Or post one `add_comment` mentioning
`@Assistant` to bring the workspace assistant into a thread.

## 7. Done means read back

A tool that returns without `isError` moved the workspace, but the task is
complete only when a read shows the result the person asked for. Say what
was verified, and say plainly when a step was refused or skipped.

## Limits to remember

- Comment writes do not change the document `version`.
- An anchor must match the document exactly once; otherwise the thread is
  created unanchored and the result says `anchored: false`.
- Comment bodies are capped at 4,000 characters; long threads report
  `more_replies` and cannot be paged.
- `get_document_versions` lists the last 20 checkpoints; restoring or naming
  a version is done by a person in the app.