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

# Agent quickstart

> The six calls an agent needs on its first task in a Sidecars workspace: connect, find, read, edit, comment, and which id is which.

This page is for the agent, not the person. Hand it over as-is, or point the
agent at `https://docs.sidecars.ai/llms.txt` for the whole site in one file.
The same guidance, plus the comment-review loop, ships as installable
[agent skills](/skills): `npx skills add https://docs.sidecars.ai`.

<Steps>
  <Step title="Connect">
    Add `https://mcp.sidecars.ai/mcp` as a streamable-HTTP server named
    `sidecars` and let the browser sign-in finish. The first grant is
    read-only; the server asks for `documents:write` the first time you edit.
    Details per host on [Connect your agent](/connect).
  </Step>

  <Step title="Find the document">
    [`list_documents`](/reference/documents#list_documents) with a `query`
    over a narrow selector (`conversation_id`, `pod_id` or `scope`). Follow
    `next_cursor` while it is a string; on the merged listing, narrow
    further before deciding something is missing. For source material rather
    than documents, use
    [`search_knowledge`](/reference/knowledge#search_knowledge); its
    `source_id` values are knowledge source ids and never go to the
    document tools.
  </Step>

  <Step title="Read, and keep the version">
    [`read_document`](/reference/documents#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 you make
    next takes that `version` as `expected_version`.
  </Step>

  <Step title="Edit the smallest region">
    [`edit_document`](/reference/documents#edit_document) with
    `mode: "replace_section"` and a `section_excerpt` quoted exactly from the
    read. `append` adds; `replace_all` needs `expected_version` and is refused
    on drift. A refusal carries the fix (`candidates`, `current_version`,
    `retry_after_seconds`); read, then retry once. Then read back and check.
  </Step>

  <Step title="Comment instead of editing when asked to review">
    [`add_comment`](/reference/comments#add_comment) with an `anchor_excerpt`
    pins the thread to a passage. `@Assistant` brings the workspace assistant
    into the thread; no mention is required. The document's `version` does
    not change.
  </Step>

  <Step title="Know which id is which">
    `document_id` from the document tools is an artifact id and appears in the
    app URL. `conversation_id` and `pod_id` come from
    [`list_conversations`](/reference/conversations) (a pod or room by
    name), `list_documents` rows, `read_document.parent`, or the room's
    URL. A knowledge hit's `source_id` is none of these. Full table in
    [IDs and URLs](/reference/artifacts).
  </Step>
</Steps>

## 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: the section
replaced and the neighbours intact, the comment on the right passage, the
export carrying the latest line. Say what was verified, and say plainly when
a step was refused or skipped.