MCP tools and limits

The server exposes at most 17 tools per connection, all of them listed below. A workflow is never its own tool: an assistant finds the workflows you have exposed with find, reads one with describe, and runs it with run_workflow, passing the workflow's slug.

Each tool needs one permission — the Permission column below. A connection is only offered the tools whose permission it holds, on top of your plan, your role, and the connection URL (see Choose what a connection can do). Every connection holds Read.

Always-available tools

Available to sign-in connections and API keys, on every plan.

Details worth knowing:

• input is the trigger payload. Whatever the agent passes arrives at the workflow exactly as a webhook body would. describe({ id: "workflow:<slug>" }) shows the expected shape and one example input.
• idempotencyKey prevents double runs. The same key from the same connection within 24 hours returns the original run instead of dispatching again. Use it whenever an agent might retry.
• Outputs are capped at 256 KB. Larger outputs come back truncated with outputTruncated: true; the full result stays in the run detail view.
• Two workflows with the same name get distinct slugs suffixed with the workflow id's first 8 characters, so slugs never collide. Exposing a second workflow with the same name changes the first one's slug too.

The whoami result

Skills tools

Available when your plan includes managed skills. List the skills licensed to a connection with find({ type: "skill" }).

Authoring tools

Available only to sign-in connections, on a workspace URL or the whole-account URL, on plans that include authoring. A call about an existing workflow, draft or table works in that item's own workspace; making something new names its workspace with workspace (see One connection for every client).

The authoring tools read through describe and find:

• A draft: describe({ id: "draft:<workflowId>" }) returns its graph, its hash (the base for propose_changes), validation state (with any warnings, as validate_draft returns them), what a person still has to finish — app connections on the workflow's Setup page, the rest in the editor (see validate_draft), and the editor link.
• A node: describe({ id: "node:<canonical>" }) returns one node's configuration schema. An unknown canonical returns found: false with a hint — not an error. For the capability sub-nodes (capability-model, capability-tool, capability-memory) it returns their contract: which agent nodes accept them, the exact edge to add, and their config schema. capability-model also lists eligibleModels; pass host: "taskjuice.system.voice_agent" to get the realtime models a Voice Agent can run.
• The catalog: describe({ id: "app:<slug>" }) lists every step one app offers and whether it still needs a connection; find({ type: "node", query }) searches every app's steps, the built-in system nodes and the capability sub-nodes.

Agents propose, the platform validates — an invalid change never persists. Connecting accounts, attaching keys, and anything else that touches a credential always happens in the app, from the links the tools return.

Change a published workflow

Once a workflow is published it usually has no draft, so propose_changes and describe({ id: "draft:<workflowId>" }) answer not-found for it. Open one first:

1. create_workflow_draft({ workflowId }) opens a draft of the workflow. It is a copy of the live version, or, when the workflow is switched off, of its newest switched-off version. Leave name, description and workspace out: the workflow already has them. Each item find({ type: "workflow" }) returns carries the workflow's workflowId, and so does describe({ id: "workflow:<slug>" }). It is also the one create_workflow_draft returned when the workflow was first drafted, and once the workflow has run, its runs (find({ type: "run" })) carry it too.
2. The result has the same shape as a new draft's: created is true, sourceVersion is the version the draft was copied from, and version is the draft's own number. If the workflow already has a draft, you get that draft back with created: false and sourceVersion: null, and nothing new is made.
3. Read it with describe({ id: "draft:<workflowId>" }), change it with propose_changes, then preview_publish and publish. The live version keeps running until the publish replaces it.

A workflow with no draft and no version that ever went live has nothing to copy, so the call answers not-found and points to the editor. While a publish of the workflow is still running (compiling, or waiting on its evaluations), the call opens nothing and answers deploy-refused with refusalCode: "version-in-progress"; try again once describe({ id: "deployment:<workflowId>" }) shows it has finished. Opening a draft needs the Build permission and, like creating a workflow, a plan that allows it.

Publish and state tools

Available to the same connections as the authoring tools.

How the loop works:

• Preview, then publish with the hash. publish refuses with preview-stale if the workflow, your plan's headroom, or its evaluations changed after the preview — call preview_publish again and show the person what changed. Retrying a publish that already succeeded returns already_active, so a dropped connection never publishes twice.
• Setup steps are data, never secrets. Each setupRequired step has a stable id, plain-language instructions, and a humanLink that opens where a person finishes it: the workflow's Setup page for connecting an app, otherwise the exact node (or page) — attaching an LLM key to a Voice Agent's Model sub-node, picking a phone number or form, pasting a provider's key, or entering a webhook signing secret. Steps marked before_publish must be done first; publish refuses with refusalCode: "setup-required" until they are. Steps marked after_publish — such as registering the webhook URL with the sending system (the step carries the URL) — are for the person to do once it is live.
• Apps are connected on the Setup page. Each workflow has a Setup page that lists every app its draft still needs, and a person reaches it from a connection step's humanLink after signing in. Connecting an app there, or asking the client to connect it, fills every step of that app in the draft at once, so the person never opens the editor once per step. A connection the Setup page can't add, such as one for a tool attached to an AI Agent, keeps its link to the node in the editor.
• In-chat setup card. In assistants that support MCP Apps, validate_draft and preview_publish also show a small setup card in the chat, drawn from the setupStatus field of their result. It lists each app still to connect, with a Set up button that opens the workflow's Setup page for that app, the number of other items the assistant will walk the person through, and the apps waiting on your client, which never hold publishing back. While it is on screen and setup is not finished, the card checks again by calling validate_draft, first every 5 seconds and then less often, for at most 40 checks (about 17 minutes); these checks count against the usual limits. When the last item is done, it posts one message into the chat so the assistant can carry on and publish. Assistants without MCP Apps ignore the card, and setupStatus is in the result for any assistant to read.
• Irreversible effects need agreement. Registering a webhook with a provider, or emailing queued connection requests to your clients, cannot be undone by turning the workflow off. set_workflow_state asks for a previewHash before an activation with such an effect, or an expose or unexpose that changes another workflow's slug: without one it returns preview-required with details.mustConfirm, one sentence per effect to show the person. Turning a workflow off never needs one.
• Turning on runs the version that was last live. set_workflow_state with activate turns a workflow back on with the version that was running when it was turned off, not the newest saved one. If newer saved changes exist, the result's unpublishedChanges names both versions and carries a message to show the person, on both the dry run and the apply. Those changes stay unpublished until you call preview_publish, then publish.
• Deleting takes the confirm step. delete_workflow without previewHash deletes nothing: it returns preview-required with details.mustConfirm — the workflow's name, how many versions go with it, that its run history will no longer be viewable, and, if it was ever published, that its triggers (schedules and webhooks) are removed for good — and details.freshHash. Show the person those sentences; if they agree, call delete_workflow again with previewHash set to details.freshHash. If the workflow or any of its versions changed in between, the second call returns preview-stale with the new hash and deletes nothing. A workflow that is turned on, or still being published, is refused with deploy-refused and refusalCode: "workflow-live": turn it off first with set_workflow_state and { "kind": "deactivate" }, which needs Admin, then delete it.
• Who may do what. Publishing a workflow follows the editor's rule: the person who created the version (or a platform admin). Deleting a workflow follows the app's rule too: only the person who created it (or a platform admin) can delete it; anyone else gets refusalCode: "not-workflow-creator". Turning workflows on and off, and exposing them, needs a workspace admin. Creating, editing and publishing a form need a workspace admin somewhere in the account. These role rules apply on top of the tool's permission (Build to create and edit, Admin to publish): a connection needs both.

Build a form

An assistant can make a form, fill in its fields, and publish it, with the same four tools it uses for workflows, each called with type: "form":

1. create_workflow_draft({ type: "form", name: "Lead Intake" }) makes a draft form with one starter field, exactly like New form in the app. It returns the form's formId, its fields, its formHash and the form builder link.
2. propose_changes({ type: "form", formId, baseFormHash, changeSet }) edits the draft. Every change set is checked against the same rules the form builder uses, all or nothing: if anything is wrong, nothing is saved. A malformed change set comes back as invalid-arguments naming the field; an op that can't apply is reported on its own, so fix it and send again; problems with the finished form (its rules and its size) are listed together.
3. preview_publish({ type: "form", formId }) shows what going live means: anything still blocking it, the public link, and the fields added, removed or changed since it was last published.
4. publish({ type: "form", formId, previewHash }) makes the public page start taking submissions and returns outcome: "published". It is refused with preview-stale if the form, or anything blocking it, changed since that preview.

A workflow then starts from the form with a Form Submission trigger whose formId is the new form. The workflow can't be published until the form is.

A form change set is a summary and a list of ops, applied in order. Fields are addressed by their key and pages by their number, as describe returns them; each op sees the form as the ops before it left it, so page numbers and positions shift as pages and fields are added or removed:

• Field types: short_text, long_text, email, number, date, single_select, multi_select, checkbox, radio, file, signature, rating, address, phone and hidden, each with the settings the form builder offers for it. A new or renamed field's key is snake_case: a lowercase letter, then lowercase letters, digits or underscores, at most 64 characters. A key built in the app in another shape still works for addressing the field.
• Conditions: a field's showIf and a page's branch rules are one comparison, such as { "==": [{ "var": "budget" }, "over_20k"] }, or an and / or list of up to 20 comparisons — the shape the form builder can show, so a person can still edit every rule. A comparison's value is text (up to 200 characters), a number, true, false or null. A field's showIf can't use the field itself, and a branch rule may also be true (always go there).
• Size: a change set can leave a form with at most 200 fields and 50 pages, so describe can always show every field. A larger form built in the app can still be edited, as long as the change doesn't raise a count that is already over its limit.
• Drafts only. An assistant edits draft forms only. A published form's page shows its saved fields straight away, so a person changes a live form in the form builder (or unpublishes it first). On a published form, propose_changes answers form-status-refused with a link to the form builder.
• Reload an open form builder. The form builder saves the whole form. If you have the form open while an assistant edits it, reload the page before you change anything, or your save replaces the assistant's changes.

Check whether a workflow is live

describe({ id: "deployment:<workflowId>" }) answers for any workflow the connection reaches — published or not, exposed or not. It returns the active and last-active version ids, the newest version's status (for example pending-eval), whether it is exposed and under which slug, the setup steps still outstanding, and one entry per trigger with its phase:

settled is true once no trigger is provisioning. While it is false, recheckAfterSeconds says when checking again is useful — poll until settled is true.

Read forms, tables, templates and app connection health

A connection that can author also reads the things a person builds with, so an assistant can wire a workflow to them without asking for every field key or column id:

• Forms: find({ type: "form", query? }) lists the account's forms (draft and published) with each one's slug and status. describe({ id: "form:<id>" }) returns its fields: key (what a Form Submission trigger emits), label, type, required, page, a field's condition as showIf, and for a dropdown, multi-select or radio field its option values as options and each choice's label and value as choices. It also returns pages (each page's number, title, field count, whether it is the last step, and its branch rules) and formHash, the base for editing it with propose_changes (see Build a form). Up to 200 fields come back; omittedFieldCount says how many more there are.
• Tables: find({ type: "table" }) lists the tables this workspace can use: its own, and the account's. describe({ id: "table:<id>" }) returns the columns (id, label, type, required, unique, indexed, and options on select columns), the primary key column and the time-to-live setting.
• Templates: find({ type: "template" }) lists the account Library's templates: the agency's own (source: "account") and the built-in ones (source: "platform"). Templates other agencies share on the public gallery are not included. describe({ id: "template:<id>" }) returns the latest revision's steps, the apps and app connections it needs, and its variables.
• App connections: find({ type: "connection" }) lists every app connection this workspace can reach, broken ones first, each with status, healthy and a plain reason. An account connection appears only once it is shared with this workspace, and only to account admins, the same as on the Apps page. describe({ id: "connection:<id>" }) adds token-refresh timing and humanLink, the connection's page in the app, where a person reconnects it or finds where to re-enter the credential. It never returns a secret or a token.

reason says what happened, then what a person does next:

When healthy is false, show the person the reason and the humanLink.

Build and fill tables

With Build, an assistant can create a table, change its columns, and read and change its rows. Tables have no draft: every change is live as soon as it saves, and the table editor's own save rules decide what a change may do.

A typical exchange:

1. edit_table({ create: { name: "Leads" }, changes: [...] }) adds Email (the primary key), Name (required) and Status (a dropdown of new, contacted and won, indexed). The answer is the table with each column's id.
2. table_rows({ tableId, action: { kind: "insert", rows: [{ values: { "<Email column id>": "ada@example.com", ... } }] } }) adds rows. Each row comes back with its rowId — the Email, because Email is the primary key.
3. table_rows({ tableId, action: { kind: "query", where: { columnId: "<Status column id>", equals: "new" } } }) finds the rows still marked new.
4. table_rows({ tableId, action: { kind: "update", rows: [{ rowId: "ada@example.com", values: { "<Status column id>": "contacted" } }] } }) changes one.
5. table_rows({ tableId, action: { kind: "delete", rowIds: ["bob@example.com"] } }) answers preview-required and lists the row. The assistant shows the person, then calls again with previewHash set to details.freshHash, and the row is deleted.

Values are always keyed by column id, never by label, so renaming a column breaks nothing.

How it behaves:

• The confirm step. Deleting rows or removing a column first answers preview-required with details.mustConfirm, one sentence per row or column that will be lost, and changes nothing. Only a second call carrying previewHash set to details.freshHash goes ahead. If a row or the table changed in between, the second call answers preview-stale with the new hash and changes nothing.
• Filter on indexed columns only. where matches one indexed column's exact value. A column that is not indexed answers invalid-arguments naming the indexed columns you can use; without where, query pages through every row (limit up to 50, default 20, and cursor from the previous page). A column can be indexed only while the table has no rows — with edit_table, or in the table editor.
• Writes stop at the first failure. Rows are written one at a time, in order. The answer lists the rows written, the one that failed (its index, code and message), and how many were notAttempted. Nothing before the failure is undone, so fix the failed row and send it and the rest again.
• Create-only settings. required and primaryKey can be set only when creating a table. An indexed or unique column can be added or removed only while the table has no rows.
• Account tables. create: { scope: "account" } makes a table every workspace of the account can use. Creating or changing one, or writing its rows, needs an account admin or owner.
• Archived tables can still be read with query, but not changed.

Retired tools

These tools were removed. A client that still lists one can call it, and gets entitlement-denied (not retryable) with a message saying the tool was retired and a hint naming its replacement. A retired call is not counted against your budget. If the replacement is not in the assistant's tool list either, reconnect the connector to refresh it.

A per-workflow tool name was your account's prefix (taskjuice_, or your own with a connector domain) followed by the workflow's slug, so taskjuice_send_invoice is answered with run_workflow({ workflowSlug: "send_invoice", … }).

Errors

Every tool failure is a structured result with a code, a message, a retryable flag, and usually a hint naming the fix.

A missing permission comes back as entitlement-denied with a details object, so an assistant can explain it without parsing the message. Permission names in details are lowercase: read, run, build, admin.

{
  "ok": false,
  "code": "entitlement-denied",
  "message": "publish needs the Admin permission, which this connection was not granted.",
  "hint": "Ask the person to reconnect this assistant and tick Admin on the Authorize access screen. Call whoami to see what this connection can do.",
  "retryable": false,
  "details": { "requiredPermission": "admin", "grantedPermissions": ["read", "run", "build"] }
}

For an API key the hint says instead that a key's permissions are fixed when it is created, and to ask for a new key. A tool the connection doesn't have at all answers Tool "<name>" is not available. with no details, the same as a name that doesn't exist (a retired name answers that it was retired instead). That covers a tool your plan, role, or credential doesn't include (API keys never reach Build or Admin tools). whoami says which of those applies.

deploy-refused codes an assistant can clear in the conversation (by changing the draft, waiting, or finishing setup steps) come back with retryable: true. Codes that need a person with another role, a plan change, or a reconnect come back false. One of those is mfa-step-up-required: your account requires two-factor authentication, and the assistant's connection was made before you verified it. Remove the TaskJuice connector in the assistant (Claude: Settings → Connectors; ChatGPT: Settings → Apps & Connectors), add it again, and complete the two-factor check when sign-in asks — then publish again.

table-refused codes:

row-limit, storage-frozen, duplicate-key and unique-conflict only ever arrive as a write answer's failed.code, never as a refused call, and so can cell-invalid (one row of an insert or update) and row-not-found (one row of an update): the rows before the failed one are saved.

Limits

Tool calls are counted per account per day, shared across every connection and key — adding credentials never adds budget. Stopping or resuming a run with control_run is never counted against it, so an account that has used up its day can still stop runs.

On top of the daily budget, hourly bounds protect against runaways: 10,000 calls per account, and per-credential class caps (3,000 reads, 600 runs and step tests, 600 authoring calls including edit_table and table_rows, 300 mapping previews, and 60 publish calls — preview_publish, publish, set_workflow_state and delete_workflow share that one budget). control_run has no class cap and is not counted against the daily budget or a key's daily call cap; only the 10,000-per-account bound, which every call shares, applies to it. A call refused for a missing permission still counts, against the daily budget and these hourly bounds in the refused tool's class (for control_run, the 10,000-per-account bound only), so an assistant retrying a refused tool is capped like any other. Form calls count in their tool's own class: creating and editing a form as authoring calls, previewing and publishing one as publish calls. find and describe are counted in the class of the type they read: drafts, nodes, apps, forms, tables, templates and app connections as authoring calls, everything else as reads. A find or describe call for a type this connection can't read is refused and still counts, in that type's class. A call to a tool that isn't available at all is not counted. An API key's optional daily call cap bounds that key's share of the account budget — it lowers what one key can spend, never raises the total.

Authoring availability by plan: Starter includes the always-available tools only; Growth and Scale include authoring.

A table_rows call reads or writes at most 50 rows, and a query page returns at most 256 KB.

Workflow runs started through MCP are normal runs — they appear in run history and count toward your plan's usage like any other run.

Next steps

• Connect an AI agent with MCP — setup, exposing workflows, API keys
• Usage and overage — how runs are metered and billed