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 and append_to_document.
Source: 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. 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
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.
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
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.