Skip to content

Write Safety

Every write on this server is double-gated: a server-issued token bound to the exact payload, plus a human confirmation. An agent cannot publish, cancel, reassign, or edit a load in a single unchecked call — and none of the gates rely on the agent "being careful."

Creating loads

validate_load  ──►  errors[] + warnings[] + validation_token
create_load    ──►  requires the token · warnings acknowledged · human confirm
  1. validate_load is a true dry run. It executes the same validation the create path runs — schema, cross-tenant reference checks, tank/site/mode rules, priority-slot uniqueness, window ordering — and returns exhaustive errors[] (blocking) plus warnings[] (dispatcher-overridable: tight windows, unusual quantities, driver PTO conflicts, tank overfill risk).
  2. The validation_token is payload-bound. It is derived from the exact assignment bytes that validated and expires in 15 minutes. Change one field afterwards and the token is dead — create_load will demand a fresh validation.
  3. Warnings must be acknowledged. If validation produced warnings, create_load refuses until the agent passes acknowledge_warnings=true — which it is instructed to do only after surfacing them to you.
  4. The human confirms. Before writing, the server asks the user via MCP elicitation with a plain-language summary of what's about to be created. Declining aborts. Clients without elicitation support fall back to the token gate plus the client's own tool-approval UX.
  5. Retries can't double-create. Every create carries an idempotency key derived from the token; a network retry replays the original response instead of creating twice.
  6. Results are per-item. A create response reports success_count, total_count, and errors[] — agents are instructed that a non-empty errors[] means partial failure even when the call itself succeeded.

Changing existing loads

update_load_status, reassign_load, and update_load have no dry-run endpoint, so they gate themselves in two phases:

call #1 (no token)   ──►  preview of current state + confirm_token · writes NOTHING
call #2 (with token) ──►  human confirm via elicitation · executes
  • The confirm_token is bound to the exact (assignment, arguments) pair — any drift between preview and execute invalidates it.
  • Status changes send an optimistic-lock header (If-Match) from the previewed state, so a load modified by someone else in between returns a clean conflict instead of a blind overwrite.
  • Cancelling is deleting: dispatch never hard-deletes records; the cancelled load stays visible in history and its timeline.
  • Reassignment creates a new assignment (same reference code) and retires the old one — the tool says so loudly so agents track the new id.

What the gates are — and aren't

The tokens are workflow gates, not security boundaries. Real authorization is always your forwarded credential, evaluated by the FolioX backend on every single call — the same rules the FolioX app follows. The gates exist so that an agent acting within your permissions still can't take an irreversible action without a checkpoint you saw.