MCP tool reference: reading content
Tools that read your account's content and runs: identity and platform description, flows, bits, references, trails and the current step. They need the floxar.read 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 running trails 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.
describe_platform
Describe Platform. Learn Floxar's domain model (flows, bits, trails, connections, scopes), entity relationships and the step-by-step guides for the three workflows: authoring (creating a flow), execution (running a trail) and handoff_discovery (finding and claiming queued trails). Most agents do not need it — the tool descriptions cover the domain. For your identity, permissions and available tools use get_identity.
- Capability:
floxar.read - Permission level: Authenticated
- Behaviour: read-only, idempotent
Takes no input.
Returns: domain, platform, workflows.
get_bit
Get Bit. Read a single bit by id for authoring tasks (refine by id, style exemplars); operators read the current step through the trail tools. response_format defaults to markdown (slate or plain_text on request); the markdown carries floxar-node anchors on elements, links and media and node= on connection lines — write them back as read to keep those nodes on update_bit. include_interactive_elements: true adds the bit's interactive_elements (element_type, name, label, required — the authored must-answer flag, always false for LinkInline / LinkBlock / Video — per-type config, and the node_type, props and items an elements[] entry takes); include_references: true adds its References Library triggers; include_feedback: true adds active feedback comments plus the rating aggregate and needs Engage (a View caller's call with it is refused PERMISSION_DENIED as a whole).
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
bit_id | id | yes | Bit UUID to read. |
include_feedback | boolean | no | Add active feedback comments plus the rating aggregate (default false). Needs Engage — a View caller's call with this flag is refused PERMISSION_DENIED. |
include_interactive_elements | boolean | no | Add interactive_elements from the stored Slate body (default false). |
include_references | boolean | no | Add the bit's References Library triggers (default false). |
response_format | one of slate, markdown, plain_text | no | Format of bit_body: markdown (default), slate or plain_text. |
Returns: authored_by_type, bit_abstract, bit_body, bit_categories, bit_description, bit_id, bit_title, complexity, created_date_time_utc, feedback, human_required, interactive_elements, last_modified_date_time_utc, references, scope_id, status.
get_current_step
Get Current Step. The canonical step shape for a trail: by default the latest sequence (the current step); pass sequence_id and sequence_created_date_time_utc together for a prior one (replay or audit) — the same three categories (degenerate / latest / past-step). Each interactive_elements entry carries required (boolean) and the step carries unmet_required_elements — the required elements still unanswered on this sequence ({ element_id, type, name, label, reason }; empty means nothing outstanding). Non-empty with non-empty available_connections is the blocked state: navigate_next (and completing via update_trail_status) refuses 422 REQUIRED_ELEMENTS_INCOMPLETE until it clears. Submit truthful values with submit_step_data, then retry; never fabricate a value. Reasons no_element_id and no_answerable_value are content defects only an editor can repair — escalate, naming the elements.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
response_format | one of slate, markdown, plain_text | no | Format of bit_body: markdown (default), slate or plain_text; elements and states are always structured JSON. |
scope_id | id | no | |
sequence_created_date_time_utc | string | no | Past-step review: sequence_id's key (required with it) — see the server instructions. |
sequence_id | id | no | Past-step review: the sequence to fetch (with its key). |
trail_created_date_time_utc | string | yes | Trail key — see the server instructions. |
trail_id | id | yes | Trail UUID. |
Returns: flow_id, is_final_step, last_modified_date_time_utc, status, step, trail_context, trail_context_extensions, trail_id.
get_flow
Get Flow. Read one flow by id — title, description, categories, priority, status, review_status, start_bit_id, trail_context_schema — whatever its status or review status. For its bits and connections use get_flow_structure. A missing flow is FLOW_NOT_FOUND; a scope_id that differs from the flow's own scope is refused WORKING_SCOPE_MISMATCH with details.target_scope_id.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
flow_id | id | yes | The flow to read. |
scope_id | id | no | Optional working scope; must be the flow's own scope (else WORKING_SCOPE_MISMATCH). |
Returns: authored_by_type, created_date_time_utc, flow_categories, flow_description, flow_id, flow_title, last_modified_date_time_utc, priority, review_status, scope_id, start_bit_id, status, trail_context_schema.
get_flow_structure
Get Flow Structure. Get a flow's complete structure: the flow, every bit reachable from start_bit (BFS order) and all connections. bit_body is null unless include_bit_bodies: true (in response_format); markdown bodies carry floxar-node anchors (node= on connection lines) — write them back as read to keep those nodes on update_bit. include_interactive_elements: true adds each bit's interactive_elements (element_type, name, label, required — the authored must-answer flag, always false for LinkInline / LinkBlock / Video — per-type config, and the node_type, props and items an elements[] entry takes); include_references: true adds each bit's References Library triggers; include_feedback: true adds each bit's active feedback comments plus rating aggregate and needs Engage (a View caller's call with it is refused PERMISSION_DENIED as a whole). total_bits and total_connections are always returned. A scope_id that differs from the flow's own scope is refused WORKING_SCOPE_MISMATCH with details.target_scope_id.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
flow_id | id | yes | The flow whose structure to fetch. |
include_bit_bodies | boolean | no | Include bit_body on each bit (default false: metadata and graph shape only; large flows produce very large responses). |
include_feedback | boolean | no | Add each bit's active feedback comments plus rating aggregate (default false; extra reads per bit). Needs Engage — a View caller's call with this flag is refused PERMISSION_DENIED. |
include_interactive_elements | boolean | no | Add each bit's interactive_elements from the stored Slate (default false). |
include_references | boolean | no | Add each bit's References Library triggers (default false; one extra read per bit). |
response_format | one of slate, markdown, plain_text | no | Format of bit_body when include_bit_bodies is true: markdown (default), slate or plain_text. |
scope_id | id | no | Optional working scope; must be the flow's own scope (else WORKING_SCOPE_MISMATCH). |
Returns: bits, connections, flow, total_bits, total_connections.
get_identity
Get Identity. Get your identity and permissions — call this first: your user_id (to name yourself when assigning trails via transfer_trail), permission level, account (id, name and environment — shown for awareness, never a permission), scopes and capabilities. Calling it at session start also marks your presence.
- Capability:
floxar.read - Permission level: Authenticated
- Behaviour: read-only, idempotent
Takes no input.
Returns: agent_limits, caller, capabilities, connection, integration.
get_reference
Get Reference. Read one References Library record by id. Returns the full Slate body, flattened text, abstract, categories, author type, lifecycle flag and last_modified_date_time_utc. View/Engage callers cannot read archived references.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
reference_id | id | yes | Reference UUID. |
Returns: authored_by_type, created_date_time_utc, is_active, last_modified_date_time_utc, reference_abstract, reference_categories, reference_content_raw, reference_content_text, reference_id, reference_title, scope_id.
get_trail_status
Get Trail Status. Check one trail's progress, assignment and status: the trail as a flat object with steps_completed, trail_context and the full trail_context_extensions chain. 404 NOT_FOUND when it does not exist or is not visible to you (View and Engage see only their own).
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
scope_id | id | no | |
trail_created_date_time_utc | string | yes | Trail key — see the server instructions. |
trail_id | id | yes | Trail UUID. |
Returns: assigned_user_id, closing_reason_options, closing_reason_required, created_date_time_utc, executor_type, flow_id, flow_title, last_modified_date_time_utc, origin_dedup_key, priority, scope_id, status, status_change_logs, steps_completed, trail_categories, trail_context, trail_context_extensions, trail_id, trail_name, transfer_logs.
list_bits
List Bits. Browse standalone bits (reusable steps) in your account, sorted by created_date_time_utc DESC unless sort_by/sort_order say otherwise. When status is omitted only active bits are returned — pass ['active','archived'] to include archived, or exclude_status to drop one; orphaned: true keeps only bits no flow reaches. include_total adds pagination.total (a separate count). Bits have no review_status or priority. For ranked keyword search use search_bits.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
authored_by_type | array of one of human, agent, automation | no | Filter by author type. Empty array → 422. |
categories | array of string | no | Bits carrying any of these category tags. |
created_after | string | no | ISO 8601 lower bound on creation. |
created_before | string | no | ISO 8601 upper bound on creation. |
exclude_status | array of one of active, archived | no | Statuses to drop (not with status; excluding both → 422). |
include_total | boolean | no | Add pagination.total, the matching count (a separate query; default false). |
last_modified_after | string | no | ISO 8601 lower bound on modification. |
last_modified_before | string | no | ISO 8601 upper bound on modification. |
limit | integer | no | Max results (default 25, max 49). |
offset | integer | no | Results to skip (default 0). |
orphaned | boolean | no | Only bits contained in no flow (default false). |
scope_id | id | no | Scope level to read (see the server instructions); omit for the account level. |
search | string | no | Substring filter on bit title (ranked search: search_bits). |
sort_by | one of bit_title, created_date_time_utc, last_modified_date_time_utc | no | Sort column (default created_date_time_utc). |
sort_order | one of asc, desc | no | Sort direction (default desc). |
status | array of one of active, archived | no | Filter by archival status. Defaults to ['active'] when omitted. Empty array → 422. |
Returns: bits, pagination.
list_bits_for_flow
List Bits for Flow. List every bit reachable from a flow's start_bit by walking its live connections, with the shortest-path depth (0 for start_bit; a bit reachable by several paths is reported once, at its minimum depth). Identifiers and depth only — fetch payloads with get_flow_structure or get_bit. A path through an archived or deleted bit is broken and the bits behind it are excluded. Empty when the flow is missing, archived, deleted or filtered by your permissions; a flow_id of another account is refused 400 SECURABLE_MISMATCH, a caller below View on the target 403. scope_id narrows the walk (every bit walked must match it). Response: {rows: [{flow_id, bit_id, depth}]}.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
flow_id | id | yes | The flow whose reachable bits to enumerate. |
scope_id | id | no | Optional scope: every bit walked must match it. |
Returns: rows.
list_flows
List Flows. Browse flows (workflow templates) in your account, sorted by created_date_time_utc DESC unless sort_by/sort_order say otherwise. When status and review_status are both omitted only active + approved flows (those executable as trails) are returned — pass arrays to broaden, or exclude_status to drop a status; an empty array → 422 VALIDATION_ERROR. include_total adds pagination.total (a separate count). For ranked keyword search use search_flows.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
authored_by_type | array of one of human, agent, automation | no | Filter by author type. Empty array → 422. |
categories | array of string | no | Flows carrying any of these category tags. |
created_after | string | no | ISO 8601 lower bound on creation. |
created_before | string | no | ISO 8601 upper bound on creation. |
exclude_status | array of one of active, inactive | no | Statuses to drop (not with status; excluding both → 422). |
include_total | boolean | no | Add pagination.total, the matching count (a separate query; default false). |
last_modified_after | string | no | ISO 8601 lower bound on modification. |
last_modified_before | string | no | ISO 8601 upper bound on modification. |
limit | integer | no | Max results (default 25, max 49). |
offset | integer | no | Results to skip (default 0). |
priority | array of one of low, medium, high, critical | no | Filter by priority. Empty array → 422. |
review_status | array of one of approved, draft, pending_review, rejected | no | Filter by review status (default ['approved'] when omitted; only approved flows are executable). Empty array → 422. |
scope_id | id | no | Scope level to read (see the server instructions); omit for the account level. |
search | string | no | Substring filter on flow title (ranked search: search_flows). |
sort_by | one of flow_title, created_date_time_utc, last_modified_date_time_utc | no | Sort column (default created_date_time_utc). |
sort_order | one of asc, desc | no | Sort direction (default desc). |
status | array of one of active, inactive | no | Filter by lifecycle status (default ['active'] when omitted, with review_status). Empty array → 422. |
Returns: flows, pagination.
list_flows_for_bit
List Flows for Bit. List every flow whose start_bit reaches a bit through live connections: flow_id, flow_title and start_bit_id only (fetch a flow with get_flow_structure). Use it before editing or archiving a bit — archive_bit cascade-clears the bit's connections, so the flows listed here lose that path (or their start_bit). A path through an archived or deleted bit is broken; a bit may appear in several flows. Empty when the bit is missing, archived, deleted or no live flow reaches it; a bit_id of another account is refused 400 SECURABLE_MISMATCH, a caller below View on the target 403. Depth is not returned — call list_bits_for_flow per flow and filter to bit_id. scope_id narrows the walk (every bit walked and every flow returned must match it). Response: {rows: [{bit_id, flow_id, flow_title, start_bit_id}]}.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
bit_id | id | yes | The bit whose containing flows to enumerate. |
scope_id | id | no | Optional scope: every bit walked and every flow returned must match it. |
Returns: rows.
list_trails
List Trails. Browse trails by flow, status, priority or assignee. With no status and no created bound: open trails (active, paused, transferred, queued) of any age. A status set including completed or abandoned reads the partitioned table and needs a created window: none supplied → the last 30 days (to now + 1 h); one bound → the other derived 30 days from it (a created_after past now + 1 h is refused); both → a span over 30 days + 1 h is refused VALIDATION_ERROR, never clipped. An omitted status with a bound means all six statuses; exclude_status drops statuses from the set (an emptied set is refused). Sorted by trail_created_date_time_utc DESC unless sort_by/sort_order say otherwise. assigned_to_me: trails assigned to you; queued_in_my_scope: queued trails you can claim (open, no window); these two and assigned_user_ids are mutually exclusive (422). Each read is contained to one scope level — scope_id names it, omitted is the account level — except an origin_dedup_key lookup, which finds your trail in any scope when scope_id is omitted (a supplied scope_id narrows it). View/Engage see only their own trails; Admin every trail at the level read.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
assigned_to_me | boolean | no | Trails assigned to you. Mutually exclusive with queued_in_my_scope and assigned_user_ids. |
assigned_user_ids | array of id | no | Trails assigned to these users. Empty array → 422. Mutually exclusive with assigned_to_me and queued_in_my_scope. |
categories | array of string | no | Trails carrying any of these category tags. |
created_after | string | no | ISO 8601 lower bound on creation (see the description's window rules). |
created_before | string | no | ISO 8601 upper bound on creation (see the description's window rules). |
exclude_status | array of one of active, paused, transferred, queued, completed, abandoned | no | Statuses dropped from the set status (or its default) names; a set left empty is refused 422. |
flow_id | id | no | Filter to one flow's trails. |
include_total | boolean | no | Add pagination.total, the matching count (default false). |
last_modified_after | string | no | ISO 8601 lower bound on modification. |
last_modified_before | string | no | ISO 8601 upper bound on modification. |
limit | integer | no | Max results (default 25, max 49). |
offset | integer | no | Results to skip (default 0). |
origin_dedup_key | string | no | Exact match on create_trail's origin_dedup_key (the crash-recovery lookup). Omit scope_id to find it in any scope; with a terminal status in the set and no bound, the create's dedup window (now − 30 days to now + 1 h) is read. |
priority | array of one of low, medium, high, critical | no | Filter by priority. Empty array → 422. |
queued_in_my_scope | boolean | no | Queued trails you can claim at the level scope_id names (the account level when omitted; needs Engage+ there). Mutually exclusive with assigned_to_me and assigned_user_ids. |
scope_id | id | no | Scope level to read (see the server instructions); omit for the account level. An origin_dedup_key lookup without scope_id searches every scope. |
sort_by | one of trail_created_date_time_utc, trail_last_modified_date_time_utc, priority | no | Sort column (default trail_created_date_time_utc). |
sort_order | one of asc, desc | no | Sort direction (default desc). |
status | array of one of active, paused, transferred, queued, completed, abandoned | no | Filter by status. Omitted with no created bound means the four open statuses; omitted with a bound means all six. Empty array → 422. |
Returns: pagination, trails.
search_bits
Search Bits. Find reusable bits by keyword (ranked full-text search, ordered by relevance) — use it before creating a bit, to avoid duplicates. When status is omitted only active bits are returned; pass ['active','archived'] to include archived. Each result carries an optional match_context snippet. Bits have no review_status or priority.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
authored_by_type | array of one of human, agent, automation | no | Filter by author type. Empty array → 422. |
created_after | string | no | ISO 8601 lower bound on creation. |
created_before | string | no | ISO 8601 upper bound on creation. |
exclude_status | array of one of active, archived | no | Statuses to drop (not with status; excluding both → 422). |
last_modified_after | string | no | ISO 8601 lower bound on modification. |
last_modified_before | string | no | ISO 8601 upper bound on modification. |
limit | integer | no | Max results (default 10, max 49). |
offset | integer | no | Results to skip (default 0). |
query | string | no | Keyword(s), or its alias search; neither or both is refused 422 VALIDATION_ERROR. |
scope_id | id | no | Scope level to read (see the server instructions); omit for the account level. |
search | string | no | Alias of query. |
status | array of one of active, archived | no | Filter by archival status. Defaults to ['active']. Empty array → 422. |
Returns: bits, pagination.
search_flows
Search Flows. Find flows by keyword (ranked full-text search across title, description and content, ordered by relevance). When status and review_status are both omitted only active + approved flows are returned. Each result carries an optional match_context snippet.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
authored_by_type | array of one of human, agent, automation | no | Filter by author type. Empty array → 422. |
created_after | string | no | ISO 8601 lower bound on creation. |
created_before | string | no | ISO 8601 upper bound on creation. |
exclude_review_status | array of one of approved, draft, pending_review, rejected | no | Review statuses to drop (not with review_status; excluding all → 422). |
exclude_status | array of one of active, inactive | no | Statuses to drop (not with status; excluding both → 422). |
last_modified_after | string | no | ISO 8601 lower bound on modification. |
last_modified_before | string | no | ISO 8601 upper bound on modification. |
limit | integer | no | Max results (default 10, max 49). |
offset | integer | no | Results to skip (default 0). |
priority | array of one of low, medium, high, critical | no | Filter by priority. Empty array → 422. |
query | string | no | Keyword(s), or its alias search; neither or both is refused 422 VALIDATION_ERROR. |
review_status | array of one of approved, draft, pending_review, rejected | no | Filter by review status. Defaults to ['approved']. Empty array → 422. |
scope_id | id | no | Scope level to read (see the server instructions); omit for the account level. |
search | string | no | Alias of query. |
status | array of one of active, inactive | no | Filter by lifecycle status. Defaults to ['active']. Empty array → 422. |
Returns: flows, pagination.
search_references
Search References. Search or browse the References Library (read-only supporting documents linkable to bits). View/Engage see active references only; Edit+ may request archived ones with archived=true. Returns light rows without the body; get_reference has the full Slate body.
- Capability:
floxar.read - Permission level: View
- Behaviour: read-only, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
archived | boolean | no | true requests archived rows only (View/Engage stay active-only). |
categories | array of string | no | Optional category/tag overlap filter. Empty strings are rejected. |
limit | integer | no | Max results (default 20, max 100). |
offset | integer | no | Results to skip (default 0). |
query | string | no | Alias of search. |
scope_id | id | no | Scope level to read (see the server instructions); omit for the account level. |
search | string | no | Full-text search over title, abstract and body: each whitespace-delimited term is prefix-matched and terms are ANDed ('req' matches 'required' and 'request'); case-insensitive, no stemming, no infix match. Omit or blank to browse. query is an alias (not both). |
Returns: pagination, references.
Last reviewed: 2026-10-06