get_fill_stateLast updated on
Last updated on
Report a draft's progress, open targets, rules, and the next target to fill
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 plus:
| Field | Type | Required | Description |
|---|---|---|---|
data | object | No | The draft payload, usually data from fill or 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[] | 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 | 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.
{
"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
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.
{
"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" }
}
}