# Tools and purposes

## Infrastructure checks and result delivery

Design administrators can call `definitions` with `kind: "flow"`, `defId`, version and `simulation: {formData, decisions?}`. The read-only simulator uses the real engine and current organization. Approval nodes default to approve; `decisions` maps node IDs to approve/reject. It stops at services, waits or 100 actions and never creates instances, sends notifications, runs timers or performs HTTP. The browser exposes this under Fields & validation. This is a published-version scenario, not exhaustive path analysis or future-outcome assurance.

Explicitly subscribe signed Webhooks to `operation.succeeded`, `operation.failed`, `operation.unknown`, `operation.rejected`, or `operation.expired`, without a flowFilter. Empty event lists retain their existing instance-only behavior. Verify `x-sanctris-signature` and deduplicate by `payload.eventId`. `payload.operation` contains state and business references, not form data, confirmation arguments or tokens. State markers and outbox deliveries commit together. Delivery is at least once with bounded retries, not automatic push support in AI clients; an integration service must receive it. Unknown outcomes require reconciliation, never automatic replay.

Design sessions now retain multiple touched form/workflow references. Old sessions can migrate only the previously saved last reference. Connected AI apps show role/scope-filtered tool diagnostics; this does not verify client connectivity or bypass object-level authorization.

Sanctris exposes tools according to the connection's purpose, read/write scope and the user's business roles. Purpose is not a privilege escalation.

## Purpose selection

| Purpose | Typical work |
| --- | --- |
| Daily work (default) | Tasks, intake forms, requests and progress |
| Forms and workflow design | Definitions, drafts, validation and proposals |
| Data analytics | Dictionaries, queries, audit queries and exports |
| Administration | Organization, positions, agents and workflow administration |

Daily work currently has up to 15 tools, including the approved-operation executor. Tool visibility can be smaller for read-only connections. Use tools/list as the authority. Removed compatibility aliases are not supported.

## A typical intake flow

### Read-only preparation

`startable_flows({flowRef, formData?})` and `get_collection({collectionId, formData?})` accept partial input and return `prepared`: versioned fields/rules, authoritative preview data/context, editable keys, `valid` and `issues`. Omit formData for initial values. Closed collections retain their submitted snapshot.

Preparation neither submits data nor creates an approval. Validation currently reports the first issue, not every error. Submission always revalidates. Authenticated web clients can use `POST /api/forms/prepare` with `{formRef, data}`.

### Operation contract

Confirmation and outcome responses retain existing fields and add `operation`: `contractVersion`, `operationId`, `state`, `terminal`, `nextAction`, and `safeToReplay`. Next actions are `review`, `poll`, `reconcile` (unknown outcome), or `none`. Never interpret failure as permission to replay or automatically create a replacement.

The built-in studio and external MCP share a policy catalog, with intentionally narrower studio capabilities. Tool schemas remain authoritative in `tools/list`.


1. `fillable_collections`: discover forms available to the authenticated user.
2. `get_collection`: read schema, current response and browser link.
3. `fill_collection`: submit complete formData with schema-correct types.
4. Review the returned approvalUrl in the browser.
5. Approval automatically executes the stored parameters. Use `execute_approved_operation` with the original operation_id to retrieve the outcome; do not create a replacement.
6. Query the result, never infer success solely from approval.

Required fields, types, audience, collection status and deadline are checked before requesting approval and again when submitting.

## A typical workflow

Discover with `startable_flows`, initiate with `initiate`, read `my_todo`, act using `act_on_task`, track with `instance_progress`, and revise/withdraw using `act_on_instance`. Writes use the same confirmation mechanism.

## Field values

Keep text as text, including phone numbers with leading zeros. Send numbers for numeric fields, arrays for multi-select fields and schema-shaped objects for ranges or tables. Do not add literal quote characters to a phone to “force” a string.

## Design and administration

### Draft simulation and connection access

For `kind: "flow"`, `get_draft` accepts `simulation: {rev, formData, formRev?, decisions?}`. The workflow revision must match; omit formRev for the published bound form, or supply an exact form draft revision. Simulation does not submit, notify or call external services. AI Design also has a Simulate draft action.

Connection access settings can narrow tools and exact resources immediately, without expanding roles or OAuth scopes. Use unversioned `flow:flow.xxx`, `form:form.xxx`, `collection:UUID` or `instance:UUID` references. Workflow grants cover associated instances and the bound form when read through the workflow; direct form draft access needs its own grant. Resource restrictions deny global discovery and organization management. An empty restricted list denies all. Approved operations recheck access to reviewed parameters before execution.

Form preflight returns up to 100 validation issues, including table row paths, so AI can repair multiple fields at once. Preflight is not submission.

In AI Design, Simulate draft provides visual field/table input, published-versus-draft bound form selection, and per-node simulated approval decisions. Results show status and event trace with expandable technical details. This checks one scenario, not exhaustive path coverage.

Keep and name up to 10 temporary scenarios, then run them as a batch. Closing the dialog or changing form source clears them. Coverage reports observed nodes and directed transitions, including uncovered portions—not proof of every condition, input combination or path. Each scenario is bounded to 1000 transitions and 100 approval actions; external services and waits still stop simulation.

MCP `get_draft` accepts `simulationBatch: {rev, formRev?, scenarios: [{name, formData, decisions?}]}` instead of `simulation`. Invalid inputs are reported per scenario. Revision conflicts or authorization failures abort the whole batch rather than mixing revisions.

Draft changes go through validation and proposals. Administration remains role-restricted even when the connection requests the admin toolset. Reauthorize with the desired purpose if a tool is not available; do not use old aliases or an unrelated identity.