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

# Document tools

> Agent tools for reading and modifying the shared working document of a conversation thread.

The `DocumentTools` collection exposes the agent tools that write to the shared working document (the center panel) of a conversation. One instance is created per thread and bound to a single `thread_id`, so every tool call targets the correct conversation without the agent having to pass `thread_id` as a parameter. The collection currently exposes two tools: [`update_document`](#update_document) and [`append_to_document`](#append_to_document).

Source: [`backend/app/tools/documents.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/documents.py).

Shared conventions for all workspace tools (the `@workspace_tool` decorator, the injected `action_and_reasoning` argument that every tool call must include, the `{success, summary, artifact}` JSON envelope, and the `(content, artifact)` return contract) are documented in [Tools](/docs/tools). The decorator injects the required `action_and_reasoning` argument into every tool below, so it is omitted from the per-tool argument tables.

## `update_document`

Replaces the entire content of the thread's working document in one call, optionally setting a new title.

**Description shown to the agent:**

> Replace the full content of the shared working document.

**Arguments**

| Argument  | Type          | Required            | Description shown to the agent            |
| --------- | ------------- | ------------------- | ----------------------------------------- |
| `content` | `str`         | Yes                 | Full new content of the working document. |
| `title`   | `str \| None` | No (default `None`) | Optional new title.                       |

**Returns:** a confirmation string of the form `document updated (<n> chars)`, where `<n>` is the new character count. This string becomes the `summary` field of the success envelope. No artifact is returned, so no SSE `artifact` event is emitted. On any exception the decorator rolls back the session and returns a failure envelope (`{"success": false, "error": "<message>"}`).

**Implementation:** Calls `WorkspaceRepository.upsert_document(thread_id, content=content, title=title)`, which performs a PostgreSQL `ON CONFLICT DO UPDATE` upsert keyed on `thread_id`; the title is only updated when explicitly provided (otherwise the existing title is kept). Source: [`backend/app/tools/documents.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/documents.py).

## `append_to_document`

Appends a chunk of text to the end of the thread's working document, creating the document if it does not yet exist.

**Description shown to the agent:**

> Append a chunk of text to the shared working document.

**Arguments**

| Argument | Type  | Required | Description shown to the agent                             |
| -------- | ----- | -------- | ---------------------------------------------------------- |
| `text`   | `str` | Yes      | Text to append to the document (a newline is recommended). |

**Returns:** a confirmation string of the form `appended (<n> chars total)`, where `<n>` is the updated total character count. This string becomes the `summary` field of the success envelope. No artifact is returned, so no SSE `artifact` event is emitted. On any exception the decorator rolls back the session and returns a failure envelope (`{"success": false, "error": "<message>"}`).

**Implementation:** Calls `WorkspaceRepository.append_document(thread_id, text)`, which concatenates `text` onto the existing document content; if no document exists for the thread yet, it creates one (via `upsert_document`) using `text` as the initial content. Source: [`backend/app/tools/documents.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/documents.py).