Tools reference

The MCP server publishes 25 tools, 21 read tools and 4 write tools. This page lists them by domain. For each one:

• the published name is what an MCP client calls (workflow_list); the internal name (workflow.list) is shown in the tool's title and in the rest of this documentation. Dots simply become underscores;
• the effect is read (looks at data, readOnlyHint: true) or write (changes something). No tool deletes anything: destructiveHint is always false;
• the required scope is <domain>:read for a read tool and <domain>:write for a write tool; see Scopes and tools. A key can also hold <domain>:*, or <domain>:write, which covers read;
• inputs give each field with its type; a field marked required has no default. Inputs are strict: an unknown field is refused with tool.invalid_input.

Every tool works within the member the key belongs to: their workflows, mailboxes, scope and the node policy of their role. A workflow, mailbox or execution of another member answers tool.resource_not_found.

Catalog and documentation

Scope workflows:read.

catalog_describe (catalog.describe), read

Describes the workflow nodes this member may use: type, name, effect, required connection and key parameters, plus a compact English text block for prompts.

Input	Type	Required
maxCharacters	integer, 1 000 to 200 000	no, no bound by default

Returns { nodes[], text }: one entry per node (type, names, description, effect, output ports, required connections, parameters) and the text block.

catalog_node (catalog.node), read

Describes one node type in full: every parameter with its type, options and display condition, its output ports, the data it produces, and whether the connections it needs are configured for this member. Use it before adding or configuring a node.

Input	Type	Required
type	string, a node type such as notion.api	yes

Returns { node, text, allowed, trigger, connections[] }, where each connection says configured: true/false with its label in the Connections page.

docs_search (docs.search), read

Searches the product documentation (concepts, nodes, integration connection guides) and returns the best pages with an excerpt, in the member's language.

Input	Type	Required
query	string, 1 to 200 characters	yes
limit	integer, 1 to 10	no, default 5

Returns { results: [{ path, title, lang, excerpt }] }.

docs_read (docs.read), read

Reads one documentation page (Markdown) by the path docs.search returned.

Input	Type	Required
path	string, a path from docs_search	yes

Returns { path, title, lang, content, truncated }; a long page is cut and says so.

Workflows

Scope workflows:read for the read tools, workflows:write for workflow_create_draft, workflow_update_draft and workflow_publish.

workflow_list (workflow.list), read

Lists the member's workflows with their status (draft, published, paused, archived).

Input	Type	Required
includeArchived	boolean	no, default false

Returns { workflows: [{ id, name, status, hasDraftChanges }] }.

workflow_read (workflow.read), read

Reads one of the member's workflows in full: the graph (nodes with their params, connections between ports), its validation as publication would judge it, the real output ports of each node, and the version history. Read it before proposing changes.

Input	Type	Required
workflowId	string	yes
version	draft or published	no, default draft

Returns { id, name, status, versionId, graph, validation, nodes[], versions[] }; the last 20 versions are listed.

workflow_describe (workflow.describe), read

Describes one of the member's workflows in short: status, triggers with their conditions, and steps with their effect. Lighter than workflow_read.

Input	Type	Required
workflowId	string	yes

Returns { id, name, status, triggers[], steps[] }.

workflow_validate (workflow.validate), read

Validates a workflow document against the node catalog, exactly as publication does, and returns its errors and warnings.

Input	Type	Required
graph	a workflow document	yes

Returns { ok, errors[], warnings[] }, each issue with code, message and nodeId.

workflow_compile (workflow.compile), read

Compiles a workflow proposal (trigger criteria, typed steps, JSON params, tables to create) into a valid workflow document, listing prerequisites and everything it refused or adjusted. Writes nothing. The proposal language and the compiler's guardrails are those of the analyzer.

Input	Type	Required
proposal	object: title, workflowName, description, minutesPerEmail, benefitRationale, confidence, trigger (senders, domains, subjectContains, hasAttachment, attachmentTypes, signals), steps[] (id, type, name, after, ports, params), tables[]	yes
observed	object: senders[], domains[], signals[], what was actually seen in the mailbox	no

Returns { ok: true, graph, steps, prerequisites, issues } or { ok: false, issues }.

workflow_propose_new (workflow.propose_new), read

Proposes a new workflow from a proposal. It is compiled into a valid draft document with its prerequisites and everything refused or adjusted; nothing is written, the member accepts or rejects the proposal. Same inputs as workflow_compile.

Returns { compiled, proposalId }; proposalId is null for an MCP client, since no conversation records the proposal.

workflow_propose_changes (workflow.propose_changes), read

Proposes changes to an existing workflow as atomic operations applied in order on a copy of its draft, then validated like publication. Nothing is written. Read the workflow first and use its node ids.

Input	Type	Required
workflowId	string	yes
summary	string, 1 to 600 characters, one sentence for the human	yes
operations	array of 1 to 40 operations: add_node, remove_node, set_params, rename_node, set_disabled, set_on_error, set_notes, connect, disconnect, set_trigger_conditions, rename_workflow	yes

Returns { ok, workflowId, baseVersionId, name, graph, operations[], validation, diff, proposalId }: the graph after the changes, the verdict of each operation (applied or rejected, with its reason), and a readable diff.

workflow_test_run (workflow.test_run), requires executions:write

Runs the draft of a workflow on a real email of the member in simulated mode: nothing is sent or written outside, AI nodes do call their model. The draft must be valid. Because it creates an execution and spends model calls, it requires executions:write like the REST route, not a read scope. An email whose sender is excluded from the member's scope is refused (workflow.message_out_of_scope): it is never processed. See Test runs.

Input	Type	Required
workflowId	string	yes
messageId	string, from mailbox_search	for an email trigger
triggerData	object, the test body of a webhook or called trigger	no
triggerNodeId	string	no
targetNodeId	string, stop at this node (included)	no

Returns { executionId, status, plannedNodes[], readAfterSeconds }; read the steps with execution_read after that delay.

workflow_create_draft (workflow.create_draft), write

Creates a draft workflow from a document; nothing is published. Tables listed as prerequisites are created first (administrators only) and the document is rewritten if a slug was taken.

Input	Type	Required
name	string, 1 to 200 characters	yes
graph	a workflow document, such as the one workflow_compile returned	yes
tables	array of { slug, name, columns[] } to create before the draft	no, default []

Returns { workflowId, versionId, name, status: "draft", tables[] }, each table with created: true/false.

workflow_update_draft (workflow.update_draft), write

Replaces the draft graph of one of the member's workflows, never a published version. Warning-only: an inconsistent graph is saved and its diagnostic returned; publishing is a separate step. An archived workflow is refused (workflow.archived).

Input	Type	Required
workflowId	string	yes
graph	a workflow document	yes

Returns { workflowId, versionId, validation }.

workflow_publish (workflow.publish), write

Publishes the draft of one of the member's workflows, exactly like the editor does: blocking on errors. Triggers become live.

Input	Type	Required
workflowId	string	yes

Returns { workflowId, ok, versionId, validation }. With ok: false, nothing is published, versionId is null and validation holds the blocking errors; this is a normal result, not an error.

Executions

Scope executions:read.

execution_list (execution.list), read

Lists the member's recent executions (test runs and real ones), newest first, with their status and error. Filter by workflow or status to find what failed.

Input	Type	Required
workflowId	string	no
status	queued, running, waiting, succeeded, failed or cancelled	no
simulated	boolean: true test runs only, false real runs only	no, both by default
limit	integer, 1 to 50	no, default 20

Returns { executions: [{ id, workflowId, workflowName, status, simulated, createdAt, finishedAt, error }] }.

execution_read (execution.read), read

Reads one execution step by step: each node's status, the output port taken, the data it produced (bounded), its effects and its error. This is how you debug a failed run or check a test run. An execution whose email comes from a sender now excluded from the member's scope is refused (workflow.message_out_of_scope): its data would reach the assistant's model.

Input	Type	Required
executionId	string	yes

Returns { id, workflowId, workflowName, status, simulated, triggerType, messageId, error, llmCost, steps[] }; a step's data is cut when large (dataTruncated: true) and never holds a full email body.

Mailboxes

Scope mailboxes:read. Every mailbox tool takes the id of one of the member's mailboxes and applies the member's scope.

mailbox_list (mailbox.list), read

Lists the member's connected mailboxes (id, address, provider, status). Call it first to get a mailboxId.

No input. Returns { mailboxes: [{ id, address, provider, status }] }.

mailbox_stats (mailbox.stats), read

Aggregates of a mailbox: volumes over 30, 90 and 365 days, distinct senders and domains, peak hours, journal counters, and the largest senders within the member's scope.

Input	Type	Required
mailboxId	string	yes

Returns { mailboxId, volumes…, peakHours[], journal30d: { unmatched, dispatched, excluded }, topSenders[] }.

mailbox_cluster (mailbox.cluster), read

Groups the recent emails of a mailbox by sender domain, ingestion signal and subject shape, over the analyzer's window rule, and returns the groups above the volume threshold with a sample of subjects and previews. No model is called.

Input	Type	Required
mailboxId	string	yes
windowDays	30, 90, 180 or 365	no, the analyzer's automatic window by default
minVolume	integer, 1 to 1 000	no, the analyzer's proportional threshold by default

Returns { windowDays, minVolume, clusters: [{ key, domain, signal, subjectShape, senders[], volume, unread, withAttachments, lastReceivedAt, samples[] }] }.

mailbox_search (mailbox.search), read

Searches incoming emails of a mailbox and returns their headers and previews, never a full body. query is free text matched against the subject, the sender name and the sender address; the other filters narrow further.

Input	Type	Required
mailboxId	string	yes
query	string, up to 200 characters	no
fromEmail	string	no
fromDomain	string	no
subjectContains	string, up to 200 characters	no
sinceDays	integer, 1 to 365	no, default 90
limit	integer, 1 to 50	no, default 20

Returns { messages: [{ id, fromEmail, fromName, subject, snippet, receivedAt, hasAttachments }] }; the id is what workflow_test_run takes as messageId.

journal_unmatched (journal.unmatched), read

The emails no workflow handled over the suggestion window, grouped by domain and turned into compiled automation proposals, exactly the continuous suggestions of the dashboard.

Input	Type	Required
mailboxId	string	yes

Returns { suggestions[] }, each with its compiled proposal.

coverage_simulate (coverage.simulate), read

Simulates which recent emails of a mailbox the member's published workflows would have handled, with the real trigger-condition engine and without executing anything; optionally broken down by groups of message ids.

Input	Type	Required
mailboxId	string	yes
sinceDays	integer, 1 to 365	no, default 90
groups	array of up to 500 { key, messageIds[] }	no

Returns { messages, covered, ratio, publishedWorkflows, workflows[], groups[], bodyApproximated }.

Connections

Scope connections:read.

connections_list (connections.list), read

Lists the connections nodes can require (Google and Microsoft capabilities, third-party services, HTTP keys), whether each is configured for this member, and the usable credentials.

No input. Returns { connections: [{ id, kind, label, credentialType, capability, configured, credentials: [{ id, name }] }] }. Only identifiers and names: no token, password or key ever appears.

Tables

Scope tables:read for tables_list, tables:write for tables_create.

tables_list (tables.list), read

Lists the data tables of the organisation with their columns, never their rows.

No input. Returns { tables: [{ id, slug, name, columns[] }] }.

tables_create (tables.create), write

Creates a data table with its columns. Administrators only: the key of an ordinary member is refused. The slug is derived from the name when not given.

Input	Type	Required
name	string, 1 to 120 characters	yes
slug	string, 1 to 60 characters	no
columns	array of { key, label, type, isKey }, at least one	yes

Returns the table: { id, slug, name, columns[] }.

Related pages

• MCP server and Connect a client
• Scopes and tools
• Workflows, Draft, published version and history, Test runs