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

# Inbox

> User inbox list, read, mark read, and reply.

The **inbox** is where agents deliver to the human user: reports, escalations, replies and approvals-as-items. Every item carries `inbox_type:"user"`.

**Disambiguation:** these tools address the *human* inbox. Agent-to-agent traffic lives in the `agent_inbox` data view — query it with `data_query`.

***

## `inbox_list`

List the user's inbox items. Default `status=unread`.

| Name       | Type   | Required | Description                                                                     |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `status`   | string | no       | `unread` (default) \| `read` \| `responded` \| `snoozed` \| `archived` \| `all` |
| `category` | string | no       | e.g. `report`, `escalation`, `reply`                                            |
| `limit`    | number | no       | Max rows                                                                        |

**Returns:** `{ items: [...], count }`. Each item: `id, from_actor, category, tags, subject, body, priority, status, source_table, source_record_id, thread_id, created_at, read_at, responded_at`, plus `inbox_type:"user"` on every row (distinguishes this human inbox from the `agent_inbox` data view).

**Permissions:** read; own inbox only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "inbox_list", "arguments": { "status": "unread" } } }
```

## `inbox_get`

One inbox item in full (body + payload) with its thread (the conversation on the same thread id).

| Name | Type   | Required | Description     |
| ---- | ------ | -------- | --------------- |
| `id` | string | yes      | Inbox item uuid |

**Returns:** `{ item, thread }`. `item` is the full row (list columns plus `payload, parent_id, inbox_type`); `thread` is the sibling rows on the same `thread_id`, oldest first (up to 50), each tagged `inbox_type:"user"`. Not found → `{ error: "Inbox item not found" }`.

**Permissions:** read; own inbox only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "inbox_get", "arguments": { "id": "<item-uuid>" } } }
```

## `inbox_mark_read`

Mark an inbox item as read.

| Name | Type   | Required | Description     |
| ---- | ------ | -------- | --------------- |
| `id` | string | yes      | Inbox item uuid |

**Returns:** `{ ok:true, id, status:"read" }`. Only unread items are marked (an already-`responded` item is left untouched → `{ error: "Inbox item not found (or already responded)" }`).

**Permissions:** write; own inbox only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "inbox_mark_read", "arguments": { "id": "<item-uuid>" } } }
```

## `inbox_reply`

Reply to an inbox item. The reply is addressed back to the original sender (the agent) and the item is marked `responded`. **Caution: only call when the human user dictated the reply.**

| Name   | Type   | Required | Description                 |
| ------ | ------ | -------- | --------------------------- |
| `id`   | string | yes      | Inbox item uuid to reply to |
| `text` | string | yes      | The reply text              |

**Returns:** `{ ok:true, reply_id, note }` — the reply row is addressed back to the original sender and the parent item is marked `responded`. (Reply text is capped at 10000 chars.)

**Permissions:** write; own inbox only; human-dictated replies only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "inbox_reply", "arguments": {
  "id": "<item-uuid>", "text": "Approved — proceed with option B."
} } }
```