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

# Conversations

> Turn a room or pod name into the conversation_id and pod_id the document tools take: list the rooms and pods you can reach, by pod, by title, or across the workspace.

Find rooms (conversations) and pods by name. This is the one tool that turns
"the launch room" into an id; every other tool takes the id.

| Tool                                        | Scope                | Kind      |
| ------------------------------------------- | -------------------- | --------- |
| [`list_conversations`](#list-conversations) | `conversations:read` | read-only |

## list\_conversations

**Scope:** `conversations:read` (step-up) · **Kind:** read-only · **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`

> The rooms (conversations) and pods you can reach, newest activity first —
> how to turn a name like "the launch room" into the `conversation_id` and
> `pod_id` the document tools take. Pass `pod` as a pod id, slug or name to
> list one pod's rooms; with no `pod`, every pod you belong to is listed with
> its newest rooms. `query` narrows by room title. A name matching two pods
> is refused with the candidates (`pod_ambiguous`): pick one and call again
> with its id. `truncated: true` means more rooms exist — narrow with `pod`
> or `query`. Artifact rooms are not listed; reach a document's own room
> through read\_document's `parent`.

### Parameters

<ParamField body="pod" type="string">
  A pod id, its slug, or its name. Names match case-insensitively, exactly
  first and then as a substring, so `launch` finds "Product Launch" when it
  is the only pod with that word. Omit to span every pod you can see.
</ParamField>

<ParamField body="query" type="string">
  Words from the room title. A ranked title search inside the selected pod
  (or each pod, without `pod`).
</ParamField>

<ParamField body="include_archived" type="boolean" default="false">
  Include archived rooms.
</ParamField>

<ParamField body="limit" type="number" default="50">
  Rooms to return, 1 to 50. Clamped.
</ParamField>

### Returns

<ResponseField name="pods" type="array">
  The pod named by `pod`, or every pod you can see.

  <Expandable title="pod">
    <ResponseField name="pod_id" type="string">Pass to `create_document` (`scope: "pod"`) and `list_documents`.</ResponseField>

    <ResponseField name="name" type="string" />

    <ResponseField name="slug" type="string" />

    <ResponseField name="visibility" type="'open' | 'restricted'" />

    <ResponseField name="my_role" type="'editor' | 'member' | null">Your role in the pod; `null` when you are not a member (an org admin, or an open pod you have not joined).</ResponseField>
    <ResponseField name="can_manage" type="boolean">Whether you may administer the pod.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conversations" type="array">
  Rooms, newest activity first.

  <Expandable title="room">
    <ResponseField name="conversation_id" type="string">Pass to `create_document` and `list_documents`.</ResponseField>

    <ResponseField name="title" type="string" />

    <ResponseField name="pod_id" type="string" />

    <ResponseField name="pod_name" type="string" />

    <ResponseField name="status" type="'active' | 'archived'" />

    <ResponseField name="last_activity_at" type="number">Milliseconds since epoch.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="truncated" type="boolean">
  `true` when more rooms exist than were returned, or when a workspace-wide
  listing stopped after 50 pods. There is no cursor; narrow with `pod` or
  `query`.
</ResponseField>

Text, pods first then rooms:

```text theme={null}
- pod <name> — pod_id: <id>, slug <slug>, open, your role editor

- <title> [active] — conversation_id: <id>, in <pod name>, active <ISO time>
[…more rooms not listed]
```

### Permissions and side effects

* Needs `conversations:read`. The first call triggers the host's step-up
  consent for it.
* The pods you can see are exactly the pod switcher's: open pods, restricted
  pods you belong to, and every pod for an org admin. A restricted pod you
  are not in is absent, not locked.
* A document's own discussion room is never listed here; it is reached from
  the document (`parent` on `read_document`).
* Reads only. Recorded in the agent activity history.

### Errors

| Text                                                                               | Cause                                                                                         |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `Tool failed: … Pod not found`                                                     | `pod` names nothing you can see: no such id, slug or name, or a restricted pod you are not in |
| `\`pod\` matches more than one pod: …`with`error: "pod\_ambiguous"`, `candidates\` | The name matched two or more pods. Call again with one `pod_id` from `candidates`.            |

### Example

**Request**

```json theme={null}
{ "name": "list_conversations", "arguments": { "pod": "launch", "query": "checklist" } }
```

**Response (structuredContent)**

```json theme={null}
{
  "pods": [
    {
      "pod_id": "p31growthpod00000000000000000000",
      "name": "Product Launch",
      "slug": "product-launch",
      "visibility": "open",
      "my_role": "editor",
      "can_manage": true
    }
  ],
  "conversations": [
    {
      "conversation_id": "j52launchroom0000000000000000000",
      "title": "Launch checklist",
      "pod_id": "p31growthpod00000000000000000000",
      "pod_name": "Product Launch",
      "status": "active",
      "last_activity_at": 1757160729000
    }
  ],
  "truncated": false
}
```

Then `create_document` with that `conversation_id` posts the document's card
into the room.