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

# Objective tool

> The set_objective tool: the agent's evolving one-line understanding of the user's goal.

The `ObjectiveTools` collection exposes the conversation Objective: the agent's evolving, one-line understanding of what the user is trying to achieve. There is one collection per thread, bound to a single `thread_id`, so the tool targets the right conversation without `thread_id` being an LLM-facing parameter. Source: [`backend/app/tools/objective.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/objective.py).

Shared conventions (the `@workspace_tool` decorator, the injected `action_and_reasoning` argument, and the JSON envelope returned by every tool) are documented in [Tools](/docs/tools).

## `set_objective`

Sets or updates the agent's concise understanding of the user's goal.

**Description shown to the agent:**

> Set or update the Objective — your concise understanding of what the user is trying to achieve. Call it on the first substantive turn and whenever your understanding of the goal changes.

**Arguments**

| Argument | Type  | Required | Description shown to the agent                                                                                                                                                   |
| -------- | ----- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`   | `str` | Yes      | One or two sentences capturing the user's goal as you currently understand it, written from the user's perspective (the outcome they want), not a description of your own steps. |

The agent also receives the required injected `action_and_reasoning` argument described in [Tools](/docs/tools); it is not a member of this tool's args schema.

**Returns:** a confirmation string of the form `objective set: <text>`, wrapped in the standard success envelope.

**Implementation:** the tool body calls `repo.upsert_objective(thread_id, text)`. There is exactly one objective row per thread (an `ON CONFLICT DO UPDATE` on `thread_id`), so each call replaces the previous objective rather than appending. The objective is user-owned: the agent proposes and refines it via `set_objective`, while the user can edit it directly through the workspace API, and both paths converge on `upsert_objective`. The objective is snapshotted at the start of every turn into `workspace_snapshots`, so its full evolution over the conversation is recoverable.

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