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

# ask_architect

> Run one turn of a conversation with the Architect, Qobra's compensation design agent. Its changes are saved as the compensation's draft, never published.

Hand the design of a compensation to the **Architect**, Qobra's compensation
design agent. Each call runs one turn of a conversation in which the Architect
builds, changes or explains a compensation's calculation: scopes, fields,
formulas, tiers, accelerators and payout.

Use it when the user wants a compensation built or changed from a description
in their own words ("pay 5% of every closed deal"), or wants to understand why
a compensation computes what it does ("why is Q3 at zero?").

## Start and continue a conversation

Start a conversation with an `instruction` and the `compensation_id` to work
on. [`get_plan`](https://docs.qobra.co/mcp_documentation/tools/get_plan) lists a plan's
compensations, and
[`create_compensation`](https://docs.qobra.co/mcp_documentation/tools/create_compensation) opens an
empty one.

Every later call of the same work passes back the `conversation_id` the first
call returned, a retry included. Without it, Qobra starts a new conversation
and the Architect loses what was said. The conversation also shows on the
compensation in the Qobra web app.

```json theme={null}
{
  "instruction": "Pay 5% of every closed deal, 7% above quota",
  "compensation_id": "<compensation-id>"
}
```

## Read the result

`status` says where the turn stands:

* `answered`: the Architect finished its turn. Relay `answer` to the user.
* `awaiting_user`: the Architect paused on a question (`pending_question`) or
  on a plan of changes to validate (`pending_plan`). The client must show it
  to the user as it is, wait for their reply, and send that reply as the next
  `instruction` with the same `conversation_id`. Approving a plan is the
  user's decision, not the model's.
* `running`: the turn is still going. Each call waits about 45 seconds before
  answering `running`, and a turn can take several minutes. Call
  [`get_architect_turn`](https://docs.qobra.co/mcp_documentation/tools/get_architect_turn) with the
  `conversation_id` to keep waiting. Calling `ask_architect` on a conversation
  whose turn is still running is refused.

A turn that ends on an error is raised as a tool error that names the
conversation, so the client can send the instruction again in it.

## Draft only, never published

What the Architect changes is saved as the compensation's **draft**. Nothing
reaches a statement until the user publishes the draft in the Qobra web app.
Each turn starts from the latest draft, including one edited in the app
meanwhile.

The result carries the `compensation` to review, in the same shape
[`get_plan`](https://docs.qobra.co/mcp_documentation/tools/get_plan) lists it. `saved` is `true`
when the turn's changes were saved as the draft. It is `false` when nothing
was saved, and `save_note` says why.

## Availability

Available only where the Qobra write tools beta is enabled and the Architect is
switched on for the company. The caller needs write access on plan
compensations, as in the web app.

## Parameters

> [accordion] Body
>
> **instruction** `string` *required*
>
> What to ask or tell the Architect, in the user's words: 'pay 5% of every
> closed deal', 'why is Q3 at zero?'. Also the user's answer to a question or
> a plan it is waiting on.
>
> **compensation\_id** `string`
>
> Id of the compensation to work on: the id get\_plan lists, or the one
> create\_compensation returns. Needed to start a conversation; a
> conversation\_id already names its compensation.
>
> **conversation\_id** `string`
>
> Id of the conversation to continue: the one an earlier ask\_architect call
> returned. Omit it only to start a new conversation on a compensation.

## Response

> [accordion] Body
>
> **status** `string`
>
> 'answered': the Architect finished its turn, its reply is in answer.
> 'awaiting\_user': it paused on a question (pending\_question) or on a plan to
> validate (pending\_plan); show it to the user and send their reply as the
> next instruction of this conversation with ask\_architect. 'running': a turn
> is still going; call get\_architect\_turn with this conversation\_id to keep
> waiting for it. One of: `answered`, `awaiting_user`, `running`.
>
> **conversation\_id** `string`
>
> The conversation this turn belongs to, the same one the web app shows on the
> compensation. Pass it back on every follow-up call.
>
> **answer** `string`
>
> The Architect's reply when status is 'answered', to relay to the user. Null
> otherwise.
>
> **pending\_question** `object`
>
> The question the Architect is waiting on, with the options it offers
> (multi\_select: several may be picked; the user may also answer in their own
> words). Set only when status is 'awaiting\_user'.
>
> **object properties**
>
> **question** `string`
>
> **options** `string[]`
>
> **multi\_select** `boolean`
>
> **pending\_plan** `object`
>
> The changes the Architect proposes, waiting for the user to approve or amend
> them; it applies nothing before. Set only when status is 'awaiting\_user'.
>
> **object properties**
>
> **summary** `string`
>
> **changes** `object[]`
>
> **object properties**
>
> **step** `integer`
>
> **action** `string`
>
> One of: `create`, `edit`, `delete`.
>
> **name** `string`
>
> **description** `string`
>
> **entity\_type** `string`
>
> **old** `string`
>
> **new** `string`
>
> **details** `string[]`
>
> **compensation** `object`
>
> The compensation to review, as get\_plan lists it: its draft version when it
> has one, the compensation itself otherwise. Publishing it is the user's
> decision, made in the Qobra web app.
>
> **object properties**
>
> **id** `string`
>
> **resource\_url** `string`
>
> Deep link to open this compensation's configuration in the Qobra web
> app.
>
> **name** `string`
>
> **recurring** `boolean`
>
> True when the compensation has no fixed date range (it applies every
> period).
>
> **start\_date** `string`
>
> YYYY-MM; null when the compensation is recurring.
>
> **end\_date** `string`
>
> YYYY-MM; null when the compensation is recurring.
>
> **period** `string`
>
> How often the compensation is calculated, on the company's fiscal
> calendar. EACH\_MONTH every month; EACH\_MONTH\_EXCEPT\_END\_OF\_QUARTER every
> month but the one each quarter closes on; EACH\_QUARTER, EACH\_SEMESTER
> and EACH\_YEAR at each period's close; Q1-Q4 once a year, at that
> quarter's close only.
>
> **status** `string`
>
> "live" when the compensation is active on the plan; "draft" while it is
> still being edited and not yet applied.
>
> **description** `string`
>
> The compensation's own free-text note, as written on the plan; null when
> it carries none.
>
> **flagged\_metrics** `object[]`
>
> The reporting metrics this compensation feeds, one entry per metric
> flagged on one of its variables. Empty when this compensation feeds none
> — which says nothing about the plan on its own: a plan is missing from a
> report built on a metric only when none of its compensations feeds that
> metric.
>
> **object properties**
>
> **id** `string`
>
> **name** `string`
>
> **type** `string`
>
> One of: `float`, `amount`, `percentage`, `string`, `picklist`,
> `multipicklist`, `bool`, `date`, `user`, `object`, `group`,
> `record_status`.
>
> **saved** `boolean`
>
> True: the turn's changes were saved as the compensation's draft, which
> nothing reads until the user publishes it. False: nothing was saved,
> save\_note says why. Null while a turn runs, and for a turn asked from the
> web app, which saves from its own page.
>
> **save\_note** `string`
>
> Why nothing was saved, or what the save had to change on the way, to tell
> the user. Null when there is nothing to add.