MCP tool reference: authoring content
Tools that write content: create and update bits, flows, connections and references. They need the floxar.author 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 running trails.
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_bit
Add Bit. Create a standalone bit (an atomic process step) — bits have no flow position; attach it into a flow's graph with connect_bits. bit_body is markdown (default) or a Slate node array. Interactive elements are created with elements[], each anchored in the markdown by its key; element-like text written as prose is refused UNSUPPORTED_MARKDOWN_CONSTRUCT. Cite a reference as [[ref:<reference_id>|<label>]] (ids from search_references); declare a credential as [credential: <handle>](credential:<handle> "<purpose>"). An outgoing connection may also be its own line [<label>](bit-connection:<target_bit_id>) (params as update_bit describes).
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes
| Input | Type | Required | Description |
|---|---|---|---|
bit_abstract | string | no | ≤2048 chars. Empty string → null. |
bit_body | string or array of any | yes | Bit body: a markdown string, or a Slate document as a node array (a JSON-stringified array is accepted). Cap 8 MB post-conversion. Slate shapes of table, figure, code-block and svg: describe_platform authoring step 2. |
bit_categories | array of string | no | Optional category tags — max 50 items, each ≤128 chars. |
bit_description | string | no | ≤1024 chars. Empty string → null. |
bit_title | string | yes | Bit title (non-empty, ≤256 chars). |
complexity | one of low, medium, high | no | Bit complexity: low | medium | high. Rides the step payload so executors can weigh the step. Default medium. |
content_format | one of slate, markdown | no | Format of bit_body: markdown (default) or slate (a node array reads as slate). |
elements | array of object | no | Interactive nodes to create or configure. Each entry: exactly one of id (an existing node's element_id; a CheckListItem's list by its parent_element_id) or key (a new node, placed where bit_body holds its [<type>: <label>](floxar-node:<key>) line; the answer's minted_node_ids maps key → id). props: the node's properties as get_bit's interactive_elements[].props returns them (an unknown prop is refused, details.allowed_props lists the type's). items (radio-button, check-list, dropdown): id to edit, key to add; a keyed item sits under its element's line as - ( ) [text](floxar-node:<key>) (radio), - [ ] [text](floxar-node:<key>) (check-list) or - [text](floxar-node:<key>) (dropdown). Without bit_body the stored body is kept and these entries edit its nodes in place. Not with content_format: slate. |
human_required | boolean | no | Execution-policy floor: when true the step must be performed by a human — an executing agent sees it on the step and escalates (transfers) without acting. Default false. |
scope_id | id | no | Optional scope UUID — omit for an account-level bit. |
Returns: bit_id, last_modified_date_time_utc, minted_node_ids, removed_node_ids.
archive_bit
Archive Bit. Archive a bit, cascade-clearing every incoming and outgoing connection. Refused 422 BIT_IS_ACTIVE_FLOW_START while it is the start_bit_id of an active flow — deactivate or repoint those flows first. Idempotent on already-archived (200, was_already_archived=true, no cascade re-run). Restoration is REST-only.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
bit_id | id | yes | Bit UUID to archive. |
last_modified_date_time_utc | string | no | Ignored; accepted for older clients (writes are last-write-wins). |
Returns: bit_id, last_modified_date_time_utc, was_already_archived.
connect_bits
Connect Bits. Create one bit-to-bit connection in a flow's graph (call once per connection). Source and target MUST share scope. sort_order auto-assigns the source's next-available position; an explicit value MUST equal it (append-only). Outgoing connections cap at 20 per source. Atomic: the Slate update and the mirror row in one transaction.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes
| Input | Type | Required | Description |
|---|---|---|---|
sort_order | integer | no | Omit for the server's next-available (the source's outgoing count); an explicit value MUST equal it. |
source_bit_id | id | yes | Source bit UUID (active, scope-aligned with target). |
source_bit_last_modified_date_time_utc | string | no | Ignored; accepted for older clients (writes are last-write-wins). |
target_bit_id | id | yes | Target bit UUID (active, scope-aligned with source). |
Returns: connection_id, source_bit_id, source_bit_last_modified_date_time_utc, target_bit_id.
create_flow
Create Flow. Create a flow (workflow template): a title and an existing, active start_bit_id of this account, in the flow's scope. trail_context_schema declares the trail_context fields agents must supply when starting trails on it.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes
| Input | Type | Required | Description |
|---|---|---|---|
flow_categories | array of string | no | Optional category tags — max 50 items, each ≤128 chars. |
flow_description | string | no | Optional description (≤1024 chars). Empty string coerces to null. |
flow_title | string | yes | Flow title (non-empty, ≤256 chars). |
priority | one of low, medium, high, critical | no | Optional priority — defaults to 'medium' when omitted. |
scope_id | id | no | Optional scope UUID — omit for an account-level flow. |
start_bit_id | id | yes | Entry-point bit UUID (active and scope-aligned). |
trail_context_schema | object | no | Schema of the trail_context fields agents must supply when starting trails on this flow. |
Returns: flow_id, last_modified_date_time_utc.
create_reference
Create Reference. Create a References Library record from a non-interactive Slate document: the server derives searchable text, rejects interactive elements and records you as the author.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes
| Input | Type | Required | Description |
|---|---|---|---|
content_format | string | no | Format of reference_content; only slate (the default). |
reference_abstract | string | no | Optional abstract (≤2048 chars). Omit to let the server derive one from the body text. |
reference_categories | array of string | no | Optional category tags — max 50 items, each ≤128 chars. |
reference_content | array of any | yes | Reference body as a Slate node array; interactive elements are rejected. |
reference_title | string | yes | Reference title (non-empty, ≤256 chars). |
scope_id | id | no | Optional scope UUID — omit for an account-level reference. |
Returns: last_modified_date_time_utc, reference_id.
link_reference
Link Reference. Link an active References Library record to a bit. The server enforces same-scope alignment, active-only references, duplicate-link rejection and Edit on the bit.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes
| Input | Type | Required | Description |
|---|---|---|---|
bit_id | id | yes | Bit UUID to link the reference to. |
display_label | string | no | Optional per-bit trigger label (≤128 chars). Omit to use the reference title at render time. |
position | integer | no | Optional display order for the bit's reference trigger list. |
reference_id | id | yes | References Library record UUID (active and same-scope as the bit). |
Returns: bit_id, bit_reference_id, reference_id.
remove_connection
Remove Connection. Remove one bit-to-bit connection by id: strips its void node from the source bit's Slate, syncs the mirror row out and advances the source bit's last_modified_date_time_utc, atomically. Not idempotent: 404 CONNECTION_NOT_FOUND on an already-removed connection (a hard delete).
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive
| Input | Type | Required | Description |
|---|---|---|---|
connection_id | id | yes | Connection UUID to remove. |
source_bit_last_modified_date_time_utc | string | no | Ignored; accepted for older clients (writes are last-write-wins). |
Returns: connection_id, source_bit_id, source_bit_last_modified_date_time_utc, target_bit_id.
unlink_reference
Unlink Reference. Unlink a References Library record from a bit. A missing link, bit or reference is not-found; permission and account scope are the server's. Not idempotent: an already-removed link is not-found.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive
| Input | Type | Required | Description |
|---|---|---|---|
bit_id | id | yes | Bit UUID whose bit-level reference link should be removed. |
reference_id | id | yes | Reference UUID to unlink from the bit. |
Returns: bit_id, reference_id.
update_bit
Update Bit. Update a bit's content or metadata; omitted fields stay unchanged. status is not exposed — archive with archive_bit (restoration is REST-only). bit_title cannot be blanked. bit_body replaces the whole body and needs content_format. Markdown: keep each element, link and media node by writing its floxar-node anchor back as get_bit returns it, and each connection by its line's node=; a node left out is refused BIT_CONTENT_LOSS unless listed in remove_node_ids. A connection is its own line [<label>](bit-connection:<target_bit_id>?node=<id>) (label → for none); a line without node= adds one (or claims the unclaimed stored connection to that target). Optional params: preview=0, description=0, categories=0, readingTime=0 hide parts of its preview card; when=<element_id>:<option_id>[,<option_id>] (dropdown or radio option ids) or when=<check_list_item_id>:checked|unchecked makes it available only then. A link or media destination changed on a kept anchor is applied (a link's or embed's url can also be set as elements[] props.url). Cite a reference as [[ref:<reference_id>|<label>]] (ids from search_references); declare a credential as [credential: <handle>](credential:<handle> "<purpose>"). Slate is the complete document: what it omits is deleted. elements[] creates or configures interactive nodes.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive
| Input | Type | Required | Description |
|---|---|---|---|
bit_abstract | string | no | Empty string → null. |
bit_body | string or array of any | no | New bit body, replacing the whole body: a markdown string, or a Slate document as a node array (a JSON-stringified array is accepted). Cap 8 MB post-conversion. Slate shapes of table, figure, code-block and svg: describe_platform authoring step 2. |
bit_categories | array of string | no | Full-replace category tags — max 50 items, each ≤128 chars. |
bit_description | string | no | Empty string → null. |
bit_id | id | yes | Bit UUID. |
bit_title | string | no | New title (≤256 chars; cannot be blanked). |
complexity | one of low, medium, high | no | Bit complexity: low | medium | high. Omit to keep the stored value. |
content_format | one of slate, markdown | no | Format of bit_body: markdown or slate. Required with bit_body. |
elements | array of object | no | Interactive nodes to create or configure. Each entry: exactly one of id (an existing node's element_id; a CheckListItem's list by its parent_element_id) or key (a new node, placed where bit_body holds its [<type>: <label>](floxar-node:<key>) line; the answer's minted_node_ids maps key → id). props: the node's properties as get_bit's interactive_elements[].props returns them (an unknown prop is refused, details.allowed_props lists the type's). items (radio-button, check-list, dropdown): id to edit, key to add; a keyed item sits under its element's line as - ( ) [text](floxar-node:<key>) (radio), - [ ] [text](floxar-node:<key>) (check-list) or - [text](floxar-node:<key>) (dropdown). Without bit_body the stored body is kept and these entries edit its nodes in place. Not with content_format: slate. |
human_required | boolean | no | Execution-policy floor: when true the step must be performed by a human — an executing agent sees it on the step and escalates (transfers) without acting. Default false. |
last_modified_date_time_utc | string | no | Ignored; accepted for older clients (writes are last-write-wins). |
remove_node_ids | array of string | no | Non-prose nodes this markdown write deletes on purpose, as a BIT_CONTENT_LOSS refusal lists them (details.removed_nodes[].id, or its label when id is null). Needs bit_body. |
Returns: bit_id, last_modified_date_time_utc, minted_node_ids, removed_node_ids.
update_bit_reference_link
Update Bit Reference Link. Update a bit-level reference link's display label or position. No lock token (a same-arguments repeat succeeds with the same state); not-found, permission, account scope, label normalization and reordering are the server's.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive, idempotent
| Input | Type | Required | Description |
|---|---|---|---|
bit_id | id | yes | Bit UUID whose bit-level reference link should be updated. |
display_label | string | no | Optional per-bit display label override (≤128 chars). |
position | integer | no | Optional zero-based display order for this bit-level reference link. |
reference_id | id | yes | Reference UUID linked to the bit. |
Returns: bit_id, bit_reference_id, reference_id.
update_flow
Update Flow. Update a flow's metadata; omitted fields stay unchanged. flow_title cannot be blanked (422); start_bit_id cannot be unset (every flow needs an entry point). is_active toggles the lifecycle (re-activation needs review_status='approved' and an active start_bit).
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive
| Input | Type | Required | Description |
|---|---|---|---|
flow_categories | array of string | no | Full-replace category tags — max 50 items, each ≤128 chars. |
flow_description | string | no | New description (≤1024). Empty string clears the field. |
flow_id | id | yes | Flow UUID. |
flow_title | string | no | New title (≤256 chars, non-empty). |
is_active | boolean | no | Lifecycle toggle; re-activation needs review_status='approved' and an active start_bit. |
last_modified_date_time_utc | string | no | Ignored; accepted for older clients (writes are last-write-wins). |
priority | one of low, medium, high, critical | no | |
start_bit_id | id or null | no | New start_bit UUID; null is REJECTED (every flow needs an entry point). |
trail_context_schema | object | no |
Returns: flow_id, last_modified_date_time_utc.
update_reference
Update Reference. Update a References Library record's metadata or non-interactive Slate body, or archive it with is_active:false; omitted fields stay unchanged. Archiving is blocked while any bit links the reference; un-archive is unsupported.
- Capability:
floxar.author - Permission level: Edit
- Behaviour: writes, destructive
| Input | Type | Required | Description |
|---|---|---|---|
content_format | string | no | Format of reference_content; only slate (the default). |
is_active | boolean | no | false archives; true is refused (un-archive is unsupported). |
last_modified_date_time_utc | string | no | Ignored; accepted for older clients (writes are last-write-wins). |
reference_abstract | string | no | Optional abstract override (≤2048 chars). |
reference_categories | array of string | no | Full-replace category tags — max 50 items, each ≤128 chars. |
reference_content | array of any | no | New reference body as a Slate node array; interactive elements are rejected. |
reference_id | id | yes | Reference UUID. |
reference_title | string | no | New title (non-empty, ≤256 chars). |
Returns: last_modified_date_time_utc, reference_id.
Last reviewed: 2026-10-06