MCP tools and call shapes

​

Server

​

Published tools

​

Tables, formulas, and mappings

​

Pages and Canvas blocks

​

Scenarios and history

​

Connected data

​

Workspace, people, and automation

​

Ari chats

• Reads are bounded. steps chooses how Ari’s tool work shows. none, the default, folds each turn’s tool steps and the notes between them into one steps item with their count. summary shows one item per step. full adds each step’s input and result, cut at 4,000 characters. A page holds at most 40 items and about 48 KB. A read without a cursor keeps the newest items and returns older to page back; a read with after keeps the oldest and returns next.
• Waiting for Ari. create and send return at once with next: the exact inspect_chats read call that waits, up to 50 seconds through wait_seconds, while the chat is busy. A read of a chat that is still busy returns another next. A client that sends a progress token gets a progress notification each second it waits, naming what Ari is doing. To hear when a turn starts or ends instead of waiting, subscribe to the chat’s resource_uri, cfoai://orgs/{org_id}/chats/{chat_id}, on the MCP 2026-07-28 subscriptions/listen stream, and read the chat’s newest page with resources/read. The older resources/subscribe is refused.
• While Ari works. delivery on send is steer by default, which ends the running turn after its current step and answers the message next; queue waits for the turn to end. request_id, a UUID the client makes, makes a repeated send a no_op that returns the same message_id.
• Limits. A create, or a send to a chat that is not busy, is refused when 5 of the user’s chats in the workspace are already busy. Only the chat’s owner can read or write it. Approval buttons, email Send buttons, confirmations, and sign-ins work only in the web app: give the person the chat_url the result carries. An MCP read does not mark the chat read in the web app.

​

Fields every tool accepts

​

The Scenario a call uses

​

Shape each call as one action block

{ "read": { "target": "Operating Plan", "rows": ["Revenue"] }, "scenario": "Main" }

• Each tool’s input schema says, in its description, which blocks exist and which fields sit beside them: “Fill exactly one action block: list, read. Fields beside the block apply to it: as_of_point, scenario.”
• An empty block selects an action that needs no fields, such as {"list": {}}. A block set to null counts as not filled.
• Fields beside the block apply to it: scenario on most model tools, as_of_point on inspect_pages and inspect_scenarios, validate on edit_canvas_blocks, target on edit_dimension_mappings, and idempotency_key on edit_memory. A block that takes such a field also accepts it inside; when both places carry it, the two values must match.
• Single-purpose tools take their fields directly at the root, as the table above shows. notify_user takes an email block, a slack block, or both.
• The schema root is a plain object, so every client can see the blocks. The rule that exactly one block is filled is enforced when the call runs.
• Unknown fields and retired request shapes are refused before anything runs. Nothing is translated from an older shape.

​

Refusals for a wrong shape

{
  "error": {
    "code": "invalid_input",
    "message": "the call takes exactly one action block; [\"list\" \"read\"] are filled",
    "transient": false,
    "validation": {
      "issues": [{ "path": "", "code": "invalid_value", "message": "..." }],
      "accepted_fields": ["..."],
      "required_fields": ["..."],
      "truncated": false
    }
  },
  "state_changed": "no"
}

​

Choose the workspace

{ "orgs": [{ "org_id": "4127", "name": "Example Co", "slug": "example-co", "role": "admin" }] }

​

References and links

• Selectors accept readable names, returned references, or IDs, unless a field says it takes less. Copy references from inspection results instead of building IDs.
• A returned reference has the form Name#hex, such as Revenue#a1b. The suffix is a prefix of the object’s identity, at least three hex digits, and unique among objects of its kind when the result was written. Later creates can lengthen it; an older reference keeps resolving while it stays unique, and a fresh inspection carries the current form. A reference also keeps resolving after its object is renamed, when exactly one object of its kind carries the suffix and the written name is one that object carried: Gusto#940 names the connection now called Acme Payroll#940, and Completion and final validation#6ca names a text block after an update_text changed its first line, with or without a page named. A suffix with a name the object never carried is refused as not a reference, with the object’s current reference. Scenario and Page references follow the same rule: Plan#725 names the Scenario since renamed Plan - No Series A#725, and SA26-18a#50c names a Page after edit_pages update renamed it, in edit_pages, inspect_pages, and the page a table create names. Main with the base Scenario’s suffix names the base Scenario.
• A name that is ambiguous or matches nothing is refused with error.candidates when alternatives are known: each with display_name, ref to pass back, kind, and, when ranked, score and match.
• A result names each object with ref, the selector to pass back, and url, the address that opens it in cfo.ai.
• A write also returns a resource link for each thing it created or changed, described “Open in cfo.ai” and meant for the user. End your reply with the link a tool returned, exactly as printed; a link you assemble yourself will not open.

​

Results

​

Write receipts

​

Refusals and failures

• A refusal carries error with code, message, transient, and, when known, candidates and hint, beside state_changed. Codes include ambiguous, not_found, invalid, blocked, conflict, stale_target, selection_too_wide, file_too_large, result_unavailable, and browser_validation_unavailable.
• result_unavailable reads The call’s outcome is unavailable. Read current state before repeating a write; repeating it could apply it again.
• A not_found for a name or Name#hex reference that only a removed connection or a deleted table carried says so, with the day in UTC: "Stripe#aa9" named a connection that was removed from this workspace on 2026-10-05. or "Vendor breakdown" named a table that was deleted on 2026-08-12. The table fact appears only when you could read that table just before it was deleted. A Scenario reference whose suffix belongs to a removed Scenario says "Disposable#a17" named a scenario that was deleted on 2026-10-19. or merged into its parent scenario, only for a user who could see that Scenario just before it was removed. Any candidates are objects that exist now, and the hint says each is a different object.
• A result with ok: false and an error_kind is an answer, not a crash. Use its message and hint to choose the next call.
• Refusals and fully rejected writes arrive with isError: true. A write that saved some items stays a success, with each item’s status.
• transient: true means the same call can succeed later without changes. A failure that knows whether it is retryable adds Transient: true. or Transient: false. to its text and {"error": {"message", "transient"}} to its structured content. The server never retries for you.

​

Pagination and truncation

• truncation.by says what cut it: response_budget (the next item did not fit one result), count_limit (the page reached the limit you set), row_limit, or depth.
• truncation.shown counts what came back, and truncation.total, when counted, what the selection matched. No truncation means the result is complete.
• next holds the values that continue the read. Pass a cursor back unchanged, with the same tool, action, target, filters, and snapshot.

​

Read the Model at an earlier point

​

Safety annotations

• readOnlyHint: true on every inspect_* tool, inspect_chats included, validate_code_blocks, and list_orgs.
• openWorldHint: true on tools that can reach outside cfo.ai, notify a person, send an invitation, or change an outside integration: edit_pages, edit_triggers, edit_profile, edit_integrations, edit_team, edit_org, call_connected_api, notify_user, and validate_code_blocks.
• destructiveHint: false only on notify_user. Every other write keeps the MCP default, which treats it as possibly destructive.

​

What the server does not publish