# write\_document

Write a markdown document for the person, as a type from `list_document_types` and following its context.

writes · not idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

Pass [`id`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-id) and the version last read to rewrite one of the caller's documents. The write fails with `failed_precondition` when someone wrote the document since.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/WriteDocument \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<name>",
  "type": "<type>",
  "body": "<body>"
}'
```

```bash
komrad rpc write-document \
  --name '<string>' \
  --type '<string>' \
  --body '<string>'
```

```json
{
  "name": "write_document",
  "arguments": {
    "name": "<name>",
    "type": "<type>",
    "body": "<body>"
  }
}
```

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

## Request

### WriteDocumentRequest

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-id) | uuid | The document to rewrite, by id. Unset creates a document. |
| [`name`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-name) | string\* at most 200 characters must not contain control characters | The document's title. |
| [`type`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-type) | string\* at most 100 characters | The name of the document's type, one [`list_document_types`](https://komrad.dev/latest/api/agent/list-document-types.md) returns. |
| [one of](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-source)\* |  | The source of the document's text. |
| [`body`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-body) | string not empty at most 1048576 bytes | The document's text, in markdown. |
| [`path`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-path) | string not empty | A markdown file on the machine komrad runs on. A relative path starts at the writing agent's checkout. |
| [`version`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-version) | int32 more than 0 | The document's [`version`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-version) when last read. Required on a rewrite. |
| [`agent_id`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentRequest-agent_id) | uuid | The agent to write the document for, by id. An agent may name only itself. |

## Response

### WriteDocumentResponse

| Field | Type | Description |
| --- | --- | --- |
| [`document`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-WriteDocumentResponse-document) | [Document](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-Document) | The document as written, without its text. |

## Types

### Document

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

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-Document-id) | uuid\* | The document's id. |
| [`agent_id`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-Document-agent_id) | uuid\* | The id of the agent that owns the document. |
| [`name`](https://komrad.dev/latest/api/agent/write-document.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/write-document.md#komrad-agent-v1-Document-type) | string | The name of the document's type. |
| [`body`](https://komrad.dev/latest/api/agent/write-document.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/write-document.md#komrad-agent-v1-Document-created_at) | timestamp | When the document was created. |
| [`updated_at`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-Document-updated_at) | timestamp | When the document was last written. |
| [`version`](https://komrad.dev/latest/api/agent/write-document.md#komrad-agent-v1-Document-version) | int32 | How many times the document has been written. |
| [`task_id`](https://komrad.dev/latest/api/agent/write-document.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. |
