# list\_documents

List the documents agents have written, without their bodies.

read-only · idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

Set [`agent_id`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-agent_id) to list one agent's documents.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/ListDocuments \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```bash
komrad rpc list-documents
```

```json
{
  "name": "list_documents",
  "arguments": {}
}
```

Offered by the komrad MCP server to writer, reviewer, orchestrator agents.

## Request

### ListDocumentsRequest

| Field | Type | Description |
| --- | --- | --- |
| [`agent_id`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-agent_id) | uuid | The agent whose documents to list, by id. Unset lists every agent's, archived agents included. |
| [`type`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-type) | string not empty at most 100 characters | The type of documents to list, by name. Unset lists every type. |
| [`pagination`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-pagination) | [Pagination](https://komrad.dev/latest/api/agent/list-documents.md#komrad-pagination-v1-Pagination) | The page to read. |
| [one of](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-task) |  | The task whose documents to list. Unset lists every task's. |
| [`task_id`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-task_id) | uuid | The task, by id. |
| [`task_slug`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsRequest-task_slug) | string not empty | The task, by slug. |

## Response

### ListDocumentsResponse

| Field | Type | Description |
| --- | --- | --- |
| [`documents`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsResponse-documents) | [Document\[\]](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document) | One page of documents, most recently written first, without their text. |
| [`next_page_token`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-ListDocumentsResponse-next_page_token) | string | The cursor for the next page. Unset on the last page. |

## Types

### Pagination

Pagination selects one page of a listing.

| Field | Type | Description |
| --- | --- | --- |
| [`limit`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-pagination-v1-Pagination-limit) | int32 at least 0 | How many records to return. Komrad caps the value, and picks one when unset. |
| [`cursor`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-pagination-v1-Pagination-cursor) | string at most 2048 characters | The `next_page_token` from the previous response. Unset to start from the first page. |

### Document

Document is markdown an agent writes for the person to read.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-id) | uuid\* | The document's id. |
| [`agent_id`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-agent_id) | uuid\* | The id of the agent that owns the document. |
| [`name`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-name) | string | The document's title. No two of one agent's documents share one. |
| [`type`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-type) | string | The name of the document's type. |
| [`body`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-body) | string | The document's text, in markdown. Empty in a listing. |
| [`created_at`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-created_at) | timestamp | When the document was created. |
| [`updated_at`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-updated_at) | timestamp | When the document was last written. |
| [`version`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-version) | int32 | How many times the document has been written. |
| [`task_id`](https://komrad.dev/latest/api/agent/list-documents.md#komrad-agent-v1-Document-task_id) | uuid | The id of the task the agent was on when the document was created. Unset for an orchestrator's documents. |
