MCP tool reference: running trails

Tools that run flows as trails: start a trail, answer a step, move on, change its status, transfer it and add context. They need the floxar.execute capability. This page is generated from the tools as Floxar's MCP server registers them, so names, inputs and descriptions match what your client receives. See also reading content and authoring content.

Every tool answers with the same envelope: on success, success: true and the result in data; on failure, an error result whose error has a code, a message and an errorId to quote when reporting a problem. The rules every call follows, such as lock tokens, intent keys and scope, are in the server's instructions and Connecting an AI client.

add_trail_context

Add Trail Context. Append an observation to the trail's context chain (append-only): something relevant to the process or to a step (an external lookup, an environmental factor, the reasoning behind a decision) — NOT routine data capture, which goes through interactive elements via submit_step_data. The trail must be active. Returns the appended entry and the trail's new lock token, so the next trail write needs no re-read.

• Capability: floxar.execute
• Permission level: Engage
• Behaviour: writes

Input	Type	Required	Description
client_intent_id	id	no	Intent key (a UUID v4 you mint; see the server instructions) for a safe retry after an ambiguous outcome; never expires.
data	object	yes	Observation payload (a JSON object, never null, array or scalar). Cap 10KB per entry.
last_modified_date_time_utc	string	yes	Lock token from your latest read of the trail — see the server instructions.
scope_id	id	no
trail_created_date_time_utc	string	yes	Trail key — see the server instructions.
trail_id	id	yes	Trail UUID.

Returns: deduplicated, extension, last_modified_date_time_utc, trail_id.

create_trail

Create Trail. Start executing a flow: creates a trail (one run) and returns it with the first step under current_step. Needs flow_id and a descriptive trail_name; the flow must be active and approved with an active start_bit, and a supplied trail_context must satisfy the flow's trail_context_schema. Without assigned_user_id the trail is yours and starts active; another user needs Edit on the placement (below it 403 OWNERSHIP_VIOLATION, nothing written) and the trail is born transferred for them, displacing nothing; null needs Edit too and the trail is born queued for the team. trail_context is immutable afterwards. A human holds one active trail at a time: when this call pauses your other active trail it is listed under displaced_trails ({ trail_id, trail_created_date_time_utc, trail_name, previous_status }); absent when nothing was paused, and an agent is never displaced. At the account's agent capacity it may answer agent_capacity: outcome deferred (born queued, unassigned) or displaced (another agent trail was queued). Dedup needs origin_dedup_key and is bounded by 30 days. The first step carries unmet_required_elements (see get_current_step): creating is never gated on them, leaving the step is (navigate_next and completing via update_trail_status refuse 422 REQUIRED_ELEMENTS_INCOMPLETE while the list is non-empty; the refusal names the remedy).

• Capability: floxar.execute
• Permission level: Engage
• Behaviour: writes

Input	Type	Required	Description
assigned_user_id	id or null	no	Omit to run it yourself (born active); another user's id needs Edit (born transferred for them); null needs Edit (born queued). A non-member id is refused 404.
flow_id	id	yes	Parent flow UUID.
origin_dedup_key	string	no	Trigger-origin dedup key (a source delivery id or payload hash): a repeat with the same key within 30 days returns the EXISTING trail and its current step (deduplicated: true) — the recovery hook for a crash between insert and response. Filterable via list_trails.
priority	one of low, medium, high, critical	no	Optional — inherits the parent flow's priority when omitted.
response_format	one of slate, markdown, plain_text	no	Format of the returned current_step's bit_body: markdown (default), slate or plain_text.
scope_id	id	no	Optional scope UUID — omit for an account-level trail.
trail_categories	array of string	no	Trail-owned category tags: omitted or empty seeds a copy of the parent flow's categories; supplied, exactly these are used. Max 50 items, each ≤128 chars.
trail_context	object	no	Immutable observation context; the flow's trail_context_schema, when declared, enforces its required fields, and a field of type date takes a calendar date YYYY-MM-DD (no time). Max 50KB.
trail_name	string	yes	Descriptive trail name (≤256 chars).

Returns: agent_capacity, created_date_time_utc, current_step, deduplicated, displaced_trails, last_modified_date_time_utc, origin_dedup_key, trail_id.

navigate_next

Navigate Next. Move the trail forward (or back) along a connection: a connection_id from the current step's available_connections (or a prior step's, to step back). The server checks it is reachable in this trail's sequence chain (422 INVALID_NAVIGATION), resolves the target bit's current version and creates the next sequence; the trail must be active. Returns the new sequence and next step (with its unmet_required_elements, see get_current_step). Required elements gate the call: an unmet required element on the step you are leaving is refused 422 REQUIRED_ELEMENTS_INCOMPLETE with details.unmet_elements and no sequence is written — definitive for the same arguments, so do not retry unchanged; the refusal names the remedy.

• Capability: floxar.execute
• Permission level: Engage
• Behaviour: writes

Input	Type	Required	Description
client_intent_id	id	no	Intent key (a UUID v4 you mint; see the server instructions) for a safe retry after an ambiguous outcome; never expires.
connection_id	id	yes	Connection UUID from the current or a prior step's available_connections; one whose source bit is not in this trail's sequence chain is refused.
last_modified_date_time_utc	string	yes	Lock token from your latest read of the trail — see the server instructions.
rationale	string	no	Why this connection was chosen — recorded on the sequence and echoed on step reads (the branch-choice audit trail).
response_format	one of slate, markdown, plain_text	no	Format of the returned next_step's bit_body: markdown (default), slate or plain_text.
scope_id	id	no
trail_created_date_time_utc	string	yes	Trail key — see the server instructions.
trail_id	id	yes	Trail UUID.

Returns: deduplicated, last_modified_date_time_utc, next_step, trail_id.

report_unmatched_context

Report Unmatched Context. Record that, WHILE EXECUTING A WORKLOAD, you searched for a flow to run and found none suitable — only on the execution path, when you needed a flow to run as a trail for the situation in front of you and discovery yielded nothing usable: the search returned nothing (reason: empty_results) or only candidates you judged unsuitable (reason: judged_unsuitable). NOT for authoring: creating or editing flows and finding none to reuse means just create it — never log a signal first. Flow-less and trail-less: it starts, modifies or references no trail. Fill details to the depth the data warrants and redact what must not leave your environment. The server stamps your identity, account, scope access, permission level and timestamp. Permission: View.

• Capability: floxar.execute
• Permission level: View
• Behaviour: writes

Input	Type	Required	Description
candidate_flow_ids	array of id	no	The flow_ids you considered and rejected (judged_unsuitable). Max 50.
details	object	no	Free-form JSON: what you tried, what came back, your reasoning — your shape, redacted by sensitivity. Max 64KB serialized.
reason	one of empty_results, judged_unsuitable	yes	empty_results: the search returned nothing executable; judged_unsuitable: candidates returned, none fit.
result_count	integer	no	How many candidates you saw — 0 for empty_results, N for judged_unsuitable.
scope_id	id	no	The scope you were operating in (omit for account level); must be one you can access (else 404).
search_query	string	yes	The keyword/phrase you searched flows with (same value you passed to search_flows). Non-empty, ≤1024 chars.
severity	one of low, medium, high, critical	no	Optional urgency hint for operator routing.
summary	string	yes	A short human-readable description of what you were trying to do — the triageable headline. Non-empty, ≤2048 chars.

Returns: signal_id.

submit_step_data

Submit Step Data. Write values for one or more interactive elements on the current step as one atomic batch: any element failure fails the whole batch (nothing written), with error.details.element_id when the offender is known. At most 200 elements, each element_id once (a repeat is 422 VALIDATION_ERROR — send the final value once). The trail must be active (paused, transferred, queued, completed and abandoned all reject — resume, claim or reopen first). Each current_value is {value: <inner>}, the inner shape per element_type as the current_value field states. A stale trail lock token rejects the batch (409 CONFLICT); element writes do NOT advance the trail's token, echoed unchanged so the next trail write needs no re-read. Each element value is last-write-wins. With client_intent_id a repeat with the same id and elements returns the ORIGINAL outcome (deduplicated: true) and writes nothing, even if the elements changed since; the same id with different elements is 422 INTENT_PAYLOAD_MISMATCH — a new submission needs a new id.

• Capability: floxar.execute
• Permission level: Engage
• Behaviour: writes, destructive

Input	Type	Required	Description
client_intent_id	id	no	Intent key (a UUID v4 you mint; see the server instructions): a repeat with the same id and elements returns the ORIGINAL outcome (deduplicated: true) and writes nothing, even after later writes to those elements; the same id with different elements is refused 422 INTENT_PAYLOAD_MISMATCH.
elements	array of object	yes	Element-state updates (1..200), each element_id at most once (a repeat is refused 422 VALIDATION_ERROR); written atomically — any failure writes nothing, error.details.element_id naming the offender when known.
last_modified_date_time_utc	string	yes	Lock token from your latest read of the trail (see the server instructions) — a stale one rejects the whole batch.
scope_id	id	no
sequence_created_date_time_utc	string	yes	Sequence key beside sequence_id — see the server instructions.
sequence_id	id	yes	Sequence UUID — the step containing the elements.
trail_created_date_time_utc	string	yes	Trail key — see the server instructions.
trail_id	id	yes	Trail UUID.

Returns: deduplicated, elements, last_modified_date_time_utc.

transfer_trail

Transfer Trail. Transfer a trail to a user or agent, queue it for a team to claim, or claim a queued trail yourself: exactly ONE of assigned_user_id, claim_for_self: true or queue_for_team: true (none or two → 422 VALIDATION_ERROR). Direct transfer and queue_for_team need the current assignee or Admin+ on the trail's scope; claim_for_self needs Engage+ there and is atomic (racing claimers see one 200 and N 409 CLAIM_LOST). Returns the post-transfer trail with previous_status and the appended transfer_log_entry. A closed trail is refused 422 TRAIL_CLOSED.

• Capability: floxar.execute
• Permission level: Engage
• Behaviour: writes, destructive

Input	Type	Required	Description
assigned_user_id	id	no	DIRECT TRANSFER mode: the target user or agent UUID (not the current assignee). Naming yourself is refused for agents (use claim_for_self); for connector users a queued trail is claimed and a held trail is transferred by authority. Mutually exclusive with the other two.
claim_for_self	boolean	no	CLAIM mode: take a queued trail into your worklist (it lands in 'transferred'; start work with update_trail_status → active). Your user_id comes from the session. Atomic — a race loss is 409 CLAIM_LOST. Mutually exclusive with the other two.
client_intent_id	id	no	Intent key (a UUID v4 you mint; see the server instructions) for a safe retry after an ambiguous outcome; never expires. Direct transfer and queue_for_team only (a connector user's self-target on a queued trail is served as a claim and still deduplicated): a claim retry re-reads the assignment (CLAIM_LOST after your own successful claim means re-read, not re-claim).
last_modified_date_time_utc	string	yes	Lock token from your latest read of the trail (every path; see the server instructions). Stale → 409 CLAIM_LOST on claim_for_self, 409 CONFLICT otherwise.
queue_for_team	boolean	no	QUEUE-FOR-TEAM mode: clears the assignee and sets status 'queued' for any eligible team member in the trail's scope. Re-queuing a queued trail is recorded (a transfer_log entry and a new lock token). Mutually exclusive with the other two.
reason	string	no	Optional transfer reason, recorded in transfer_log_entry.reason (null if omitted).
trail_created_date_time_utc	string	yes	Trail key — see the server instructions.
trail_id	id	yes	Trail UUID to transfer / claim.

Returns: deduplicated, last_modified_date_time_utc, trail_id.

update_trail

Update Trail. Rename a trail or change its priority or categories (Edit tier; status goes through update_trail_status, assignment through transfer_trail). At least one of trail_name, priority, trail_categories, else 422 VALIDATION_ERROR before anything is written; trail_categories replaces the tags as a whole. A closed trail is refused 422 TRAIL_CLOSED. Returns the new lock token.

• Capability: floxar.execute
• Permission level: Edit
• Behaviour: writes, destructive

Input	Type	Required	Description
last_modified_date_time_utc	string	yes	Lock token from your latest read of the trail — see the server instructions.
priority	one of low, medium, high, critical	no	New priority.
scope_id	id	no
trail_categories	array of string	no	Replacement category tags (max 50, each ≤128 chars); an empty array clears them.
trail_created_date_time_utc	string	yes	Trail key — see the server instructions.
trail_id	id	yes	Trail UUID.
trail_name	string	no	New trail name (≤256 chars).

Returns: last_modified_date_time_utc, priority, trail_categories, trail_id, trail_name.

update_trail_status

Update Trail Status. Pause, resume, complete or abandon a trail: status is active / paused / completed / abandoned (queue or transfer with transfer_trail). Every change is checked against the trail state machine: an illegal edge (the current status included) is refused 422 INVALID_STATUS_TRANSITION with details.allowed_transitions (what is reachable now) and details.transition_conditions (the companion argument each target needs) — definitive for the same arguments: re-read the trail and choose from allowed_transitions rather than retrying. Reopening a completed or abandoned trail to active REQUIRES reason (422 MISSING_PARAMETER). Completing or abandoning MAY require closing_reason: the reason_key from get_trail_status's closing_reason_options for the target state; when the flow configures reasons a missing or invalid key is 422 with the valid keys — pick 'other' (plus a reason note) when none fit. Completing is also gated on required elements: unmet required elements on the latest step (see get_current_step's unmet_required_elements) refuse 422 REQUIRED_ELEMENTS_INCOMPLETE with details.unmet_elements and write nothing — definitive for the same arguments; the refusal names the remedy. Abandoning is never gated. Changes are recorded in status_change_logs (append-only). A human holds one active trail at a time: setting a trail active pauses your other active trail first, listed under displaced_trails ({ trail_id, trail_created_date_time_utc, trail_name, previous_status }); absent when nothing was paused, and an agent is never displaced. Activating an agent trail at the account's agent capacity may answer agent_capacity: outcome displaced (another agent trail was queued).

• Capability: floxar.execute
• Permission level: Engage
• Behaviour: writes, destructive

Input	Type	Required	Description
client_intent_id	id	no	Intent key (a UUID v4 you mint; see the server instructions) for a safe retry after an ambiguous outcome; never expires.
closing_reason	string	no	Closing-reason key (slug) when completing/abandoning — from get_trail_status's closing_reason_options for the target state; 422 with the valid keys when required or invalid.
last_modified_date_time_utc	string	yes	Lock token from your latest read of the trail — see the server instructions.
reason	string	no	Free-text reason. REQUIRED when reopening completed/abandoned to active, and when closing_reason is 'other' (422 when missing).
scope_id	id	no
status	one of active, paused, completed, abandoned	yes	Target trail status. Use transfer_trail to queue/transfer.
trail_created_date_time_utc	string	yes	Trail key — see the server instructions.
trail_id	id	yes	Trail UUID.

Returns: agent_capacity, deduplicated, displaced_trails, last_modified_date_time_utc, trail_id.

Last reviewed: 2026-10-06