> ## 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.

# Available tools

> Every operation an agent can run on the Sidecars MCP server, grouped by product area, marked read or write, with the scope each one needs.

The server at `https://mcp.sidecars.ai/mcp` exposes 14 tools and one resource
template, and no prompts. Each entry below links to its full contract:
parameters, returned fields, errors and an example.

**Read** tools change nothing. **Write** tools act as you in the workspace and
are checkpointed and audited. **Destructive** write tools can replace existing
content and require a version check.

## Knowledge

Scope `knowledge:read`, granted on first connect.

* [**search\_knowledge**](/reference/knowledge#search_knowledge) (read): hybrid
  vector and full-text search over the workspace knowledge base, returning
  ranked excerpts.
* [**ask\_knowledge**](/reference/knowledge#ask_knowledge) (read): a synthesized
  answer to a question, with cited sources.

## Conversations

Scope `conversations:read`, by step-up consent on first use.

* [**list\_conversations**](/reference/conversations#list_conversations) (read):
  the rooms and pods you can reach, by pod name, slug or id and by room title —
  how a name becomes the `conversation_id` / `pod_id` the document tools take.

## Documents

Reads need `documents:read`, writes need `documents:write`. Both arrive by
step-up consent on first use.

* [**list\_documents**](/reference/documents#list_documents) (read): the
  documents and pages you can reach, filtered by conversation, pod or library
  section, with your role on each.
* [**read\_document**](/reference/documents#read_document) (read): a document as
  markdown, windowed for long content, always with its `version`.
* [**create\_document**](/reference/documents#create_document) (write): a new
  document in a conversation or in your library, optionally pre-filled, with
  idempotent retries.
* [**edit\_document**](/reference/documents#edit_document) (write, destructive):
  append, replace a quoted section, replace everything, or fill an empty
  document while people may be editing it live.
* [**get\_document\_versions**](/reference/documents#get_document_versions)
  (read): the recent checkpoints and named versions, newest first.

## Pages

Same scopes as documents.

* [**create\_page**](/reference/pages#create_page) (write): a new HTML page
  artifact in a conversation or your library.
* [**read\_page**](/reference/pages#read_page) (read): a page's stored HTML and
  its `version`.
* [**write\_page**](/reference/pages#write_page) (write, destructive): replace a
  page's HTML under a required `expected_version`; a conflict returns a diff.

## Export

Scope `documents:read`.

* [**export\_document**](/reference/export#export_document) (read): render a
  document, page or table to markdown, PDF, HTML, CSV or JSON and get a
  15-minute download URL.

## Comments

Reads need `documents:read`, writes need `documents:write`.

* [**read\_comments**](/reference/comments#read_comments) (read): the comment
  threads on a document or page, with anchors, replies and your role.
* [**add\_comment**](/reference/comments#add_comment) (write): start a thread,
  optionally anchored to a quoted passage, or reply in one.
* [**resolve\_comment**](/reference/comments#resolve_comment) (write,
  idempotent): resolve or reopen a thread.

## Resources

* [**sidecars://document/\{id}**](/reference/resources): the documents you can
  reach, as `text/markdown` resources for hosts that mount them next to tools.

## Which methods need a token

| Method                                       | Token required                     |
| -------------------------------------------- | ---------------------------------- |
| `initialize`, `ping`                         | No                                 |
| `tools/list`                                 | No                                 |
| `resources/list`, `resources/templates/list` | No (an anonymous listing is empty) |
| `resources/read`                             | Yes                                |
| `tools/call`                                 | Yes, with the tool's scope         |

A presented-but-invalid token is refused on every method.

## How to read a tool result

A successful call returns a text block for a person and a `structuredContent`
object for the host. The two always agree.

```json theme={null}
{
  "content": [{ "type": "text", "text": "Created \"Q3 launch plan\" (document_id: k97fq2example000000000000000000, version 1)." }],
  "structuredContent": {
    "document_id": "k97fq2example000000000000000000",
    "title": "Q3 launch plan",
    "version": 1
  }
}
```

A recoverable failure comes back the same way with `isError: true` and, when
there is something to act on, an `error` code in `structuredContent`. See
[Troubleshooting](/troubleshooting#how-errors-come-back).

Every tool declares MCP annotations so a host can decide whether to ask before
calling it:

| Annotation              | Meaning here                                                          |
| ----------------------- | --------------------------------------------------------------------- |
| `readOnlyHint: true`    | The tool changes nothing                                              |
| `destructiveHint: true` | The tool can replace existing content (`edit_document`, `write_page`) |
| `idempotentHint: true`  | Repeating the call has no further effect (`resolve_comment`)          |
| `openWorldHint: false`  | The tool acts only inside the token's workspace                       |

## Not exposed

These are not available through this server today, and no tool pretends
otherwise:

* Posting messages or reading a room's messages (`conversations:write` is
  reserved for a future release; `conversations:read` lists rooms only).
* Sharing, granting, moving or linking artifacts.
* Restoring a version, naming a version, or deleting anything.
* Editing tables (a table is filled in by the agent that created it).
* Resource subscriptions (`notifications/resources/updated`).
* Prompts (`prompts/list` is answered as unsupported).