# get_fill_state

Report a draft's progress, open targets, rules, and the next target to fill

Canonical URL: https://docs.paradoc.dev/ai-tools/get-fill-state/

Reports where a form or checklist draft stands: how many required targets are done, which are still open or blocked, whether the rules pass, and which target to fill next. An agent uses it to decide its next question.

The draft is not changed. Only forms and checklists are supported.

## Input

Takes a [source](/ai-tools#sources) plus:

| Field                | Type      | Required | Description                                                                                                              |
| -------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `data`               | `object`  | No       | The draft payload, usually `data` from [`fill`](/ai-tools/fill) or [`update_fill`](/ai-tools/update-fill). Default `{}`. |
| `evaluation_context` | `object`  | No       | The draft's `evaluation_context`                                                                                         |
| `include_optional`   | `boolean` | No       | Include optional targets in `candidates`. Default `false`.                                                               |

## Output

| Field                | Type                                              | Description                                                                                                                                                                                      |
| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `artifact_kind`      | `"form" \| "document" \| "bundle" \| "checklist"` | Artifact kind, when known                                                                                                                                                                        |
| `phase`              | `string`                                          | Draft phase, such as `draft`                                                                                                                                                                     |
| `summary`            | `object`                                          | `required_total`, `required_done`, `required_remaining`, `completion_percent`                                                                                                                    |
| `defs_values`        | `object`                                          | Evaluated `defs` values                                                                                                                                                                          |
| `rules`              | `object`                                          | `valid`, plus `errors[]` and `warnings[]` of `RuleViolation` entries from the artifact's rules                                                                                                   |
| `open_required`      | `FillItemState[]`                                 | Visible, required, unfilled targets                                                                                                                                                              |
| `open_optional`      | `FillItemState[]`                                 | Visible, optional, unfilled targets                                                                                                                                                              |
| `blocked`            | `FillItemState[]`                                 | Hidden targets that can become visible once their prerequisites are filled                                                                                                                       |
| `done`               | `FillItemState[]`                                 | Filled targets                                                                                                                                                                                   |
| `candidates`         | `FillTarget[]`                                    | Targets that can be filled now. Forms use dependency order, with required targets before optional targets by default and declaration order breaking ties. Checklists use item declaration order. |
| `next`               | `FillTarget \| null`                              | The first candidate, or `null` when nothing is left                                                                                                                                              |
| `evaluation_context` | `object`                                          | The draft's fixed context                                                                                                                                                                        |
| `errors`             | [`ToolError[]`](/ai-tools#errors)                 | Set when the draft data was rejected (`validation_error`), or when the form's logic could not be evaluated (`logic_unresolved`) and the rules were not run                                       |
| `error`              | [`ToolError`](/ai-tools#errors)                   | Set when the state could not be computed                                                                                                                                                         |

A `RuleViolation` has `rule_id`, the key of the failed rule in the artifact's `rules` section, and `message`, the rule's message. Errors come from rules with `error` severity and make `valid` false. Warnings come from rules with `warning` severity and do not.

```json
{
  "valid": false,
  "errors": [{ "rule_id": "depositWithinLimit", "message": "Pet deposit cannot exceed $500" }],
  "warnings": []
}
```

A `FillTarget` has `kind` (`field`, `party`, or `annex` for forms; `item` for checklists), `key`, `required`, and `order`. A `FillItemState` adds `visible`, `status` (`hidden`, `optional`, or `required`), `filled`, and `blockedBy` (the unfilled targets that keep it hidden). These nested entries keep their camelCase keys.

## Direct usage

```typescript
import { executeGetFillState } from "@paradoc/ai-tools"

const state = await executeGetFillState({
  source: "registry",
  registry_url: "https://public.paradoc.dev",
  artifact_name: "pet-addendum",
  data: draft.data,
  evaluation_context: draft.evaluation_context,
})

if (state.next) {
  // Ask the user for state.next.key
}
```

## Example response

For a pet addendum with the tenant, pet name, and species filled. The `open_required`, `done`, and `candidates` lists are shortened.

```json
{
  "artifact_kind": "form",
  "phase": "draft",
  "summary": {
    "required_total": 6,
    "required_done": 3,
    "required_remaining": 3,
    "completion_percent": 50
  },
  "defs_values": {},
  "rules": { "valid": true, "errors": [], "warnings": [] },
  "open_required": [
    { "kind": "party", "key": "landlord", "required": true, "order": 1, "visible": true, "status": "required", "filled": false, "blockedBy": [] }
  ],
  "open_optional": [],
  "blocked": [],
  "done": [
    { "kind": "party", "key": "tenant", "required": true, "order": 0, "visible": true, "status": "required", "filled": true, "blockedBy": [] }
  ],
  "candidates": [
    { "kind": "party", "key": "landlord", "required": true, "order": 1 }
  ],
  "next": { "kind": "party", "key": "landlord", "required": true, "order": 1 },
  "evaluation_context": {
    "asOf": { "date": "2026-09-22", "datetime": "2026-09-22T14:05:11.630Z" }
  }
}
```