Walla

Register a ready_to_review build as a reusable custom field TYPE + immutable VERSION, after the member has reviewed the preview. This deploys and verifies the field, so it may take a minute; if it returns try_again or internal, call get_custom_field_build then approve again — it resumes safely without creating a duplicate. Returns customFieldTypeId + customFieldVersionId; then attach it with form_apply_edits (add_field, fieldType CUSTOM, that customFieldTypeId). Idempotent: re-approving returns the same version. Preconditions: state ready_to_review. This is where the per-plan cap on how many custom field types a team may OWN is finally enforced (Free 1, Pro 5, Enterprise unlimited): approving a build that would register a NEW type past the cap returns payment_required — the build stays approvable, so relay the upgrade nudge rather than starting over. A build with a targetTypeId only adds a version to an existing type and is never capped.

approve_custom_field_build

Cancel a custom field build you no longer intend to approve, freeing the in-flight build slot it holds. A team can have only a few builds in flight at once; an abandoned build keeps its slot until it is cancelled (or expires after ~24h), so start_custom_field_build fails with "too many in-flight builds" until one is freed. Use this to discard a build you started but will not finish, or to unblock start when all slots are taken. Do NOT use it to change a built field: to fix the code and rebuild, call submit_custom_field again; to keep the field, call approve_custom_field_build. An already-approved build CANNOT be cancelled — its registered field version stays live. Preconditions: a teamId from list_teams and a buildId from start_custom_field_build / get_custom_field_build. Cancelling an already-finished build (failed/expired) succeeds as a no-op. Cancelling does NOT free room under the per-plan limit on how many custom field types a team may own — that limit counts registered types, not builds; only deleting a type does. Side effect: marks the build terminal and tears down any deployed preview for it; this is not reversible — start a new build to try again. Returns { buildId, state } with state build_failed.

cancel_custom_field_build

Poll a custom field build. Returns a single member-facing state: preparing → awaiting_your_code → building → ready_to_review → approved (or build_failed). When awaiting_your_code, call get_custom_field_scaffold then submit_custom_field. When build_failed, read errors and re-submit. When ready_to_review, share previewUrl with the member — it is a ready-to-open link that renders the field for review (do not paste the raw build URL, which shows blank outside the host page) — then approve_custom_field_build. Preconditions: a buildId from start_custom_field_build.

get_custom_field_build

Create an automation that runs an action when the form receives a response. v1 supports one action type: a webhook (action.type:'webhook') that sends an HTTP request to an endpoint. By default the webhook sends the full response data as a JSON payload; optionally supply action.config.body to send a custom body with @[label]{{ID}} mentions that inject response values (field ids from get_published_form as res:<fieldId> or bare <fieldId>, hidden fields as hidden:<key>, or special variables responseKey/customerKey/projectKey/timestamp). The default payload also carries the response's hidden-field values (what the form captured from URL query parameters) — set action.config.includeHiddenFields:false to leave them out. Optionally attach conditions so it fires only when a response matches (e.g. a rating equals 5). Call it ONLY when the user explicitly asks to send responses to a webhook/their server — never as a side effect of reading. Do NOT use it for email or Google Sheets automations: those are not offered here (they require connecting a Google account in the dashboard first — tell the user to set them up there), so action.type accepts only 'webhook'. Do NOT use it to edit/delete/enable an existing automation (use update_automation, or the dashboard), nor to route different responses to different actions (multiple routes — dashboard). To edit the form's questions use form_apply_edits. Preconditions: a published formId from list_forms (a Live/Closed form — automations attach to the published form); the user must be a member of the form's workspace or the call returns forbidden. To add conditions or body mentions, first read the form (get_form / get_published_form) to get real field ids and, for choice fields, option ids — an unknown field id (in a condition or a body mention) returns invalid_args; the operator/condition shape matches walla://reference/branch-logic (readable via the read_reference tool if your client can't open resources). Consider list_automations first to avoid duplicates. Side effect: creates ONE automation (additive). It is created INACTIVE (isActive:false) — the user must enable it (in the dashboard or via update_automation) before it will actually fire, so tell them so. Returns the created automation summary (id, name, type, trigger, isActive:false, and the conditions you set). `actionTypes` is the ordered, de-duplicated list of action-node types; `actionSummary` is optional sanitized metadata emitted only for exactly one action node and omitted for multi-action graphs.

create_automation

Create a new TITLE-ONLY form shell in a workspace. It is a data-changing (write) tool; call it ONLY when the user explicitly asks to create a form, never as a side effect of reading. Use it to start a brand-new empty form. Do NOT use it to add questions/fields or to edit an existing form — it creates only an empty titled shell (a default submit step is added automatically); to add or change a form's questions, set descriptions, edit branch logic, or add a CUSTOM field, use form_apply_edits instead. To inspect what was created, re-read with get_form or list_forms. Preconditions: teamId and workspaceId, both taken from list_teams / list_workspaces, plus a title (1–255 characters); the user must have create permission in that workspace or the call returns forbidden, and bad/missing input returns invalid_args. Side effect: creates one new form (additive, not destructive) attributed to the calling user. Returns the newly created form record (the empty titled shell).

create_form

Apply a batch of edits to an EXISTING form's draft: add, update, delete, or reorder fields, set rich-text field descriptions (HTML), set or clear a field's conditional jump logic (set_field_logic / clear_field_logic), set the form's appearance (background/button colors + next-button, set_form_appearance), and set a question group's page-break boundary and label (set_group). Edits go through the live collaborative document, so changes appear to anyone currently editing and are saved to the draft (the user publishes separately). Read the form first with get_form to obtain real field ids and the current layout; never invent field ids. To add a field and set its conditional logic in ONE call, give the add_field a tempId (and each choice option a key) and reference them as @tempId / @key in the same batch's set_field_logic — the server resolves them to the assigned ids and echoes the mapping under the result's `added`, so no re-read is needed. For set_field_logic, pass option ids as choiceIds (the opaque option ids read from get_form, not labels or values) to match a choice answer, and a literal value for text/number/date answers; a rule's conditions use a per-condition connector ('and'/'or') that folds left-to-right with no precedence; see walla://reference/branch-logic and walla://reference/editing-contract for the full contract (readable via the read_reference tool if your client can't open resources). When building a multi-question survey, consider grouping related questions into labeled sections instead of leaving each in its own flat group: anchor follow-up fields to the section's first field with intoGroup:true, then set_group{groupId,label} to name each section (see the server instructions and walla://reference/editing-contract). Preconditions: a formId from list_forms and at least one op; the user must have edit permission on the form's team/workspace or the call returns forbidden, and bad input returns invalid_args. Side effect: mutates the form's questions (add is additive; delete/reorder can remove or reshuffle fields). Call ONLY when the user explicitly asks to change a form's questions, never as a side effect of a read. Returns { formId, applied, added } where applied is the number of operations applied and added has one entry per add_field op echoing the server-minted field/option ids (the receipt for any tempId/key alias).

form_apply_edits

Get a single form's editable DRAFT: the form record, a lean per-field projection in layout order, and the page/group view. Use when you need the working/editable version of a form — its questions, settings, and page structure — and to get real field ids and the current layout before editing with form_apply_edits. Do NOT use it for the live published version — use get_published_form instead; and do NOT guess a form id — take one from list_forms. Preconditions: formId, taken from a list_forms result; the user must have read permission on the form's team/workspace or the call returns forbidden, and an unknown id returns not_found. Read-only; no data is changed. Returns { form, fields, groups }: the draft form record; one lean object per field (id, label, fieldType, properties, validations, plus outputType and friendly logic when the field has any — CUSTOM fields also carry customFieldTypeId, customFieldVersionId, and outputSchema) in layout order; and the derived groups view (page sections with their chaining/label and fieldIds). fields is empty when the draft has no ordered fields.

get_form

Get a form's LIVE published version plus its form settings and a lightweight field list (each field's id, label, type, output type, and published option IDs). Use when you need the published/live form as respondents see it, or when you need fields' output types. Do NOT use it for the editable draft or full field rows — use get_form instead; a form that has no published version returns not_found (it does NOT return empty fields), so use get_form to read a draft that was never published. Preconditions: formId, taken from a list_forms result; the user must have read permission on the form's team/workspace or the call returns forbidden, and an unknown id returns not_found. Read-only; no data is changed. Returns { form, fields }: the published form with its settings, plus the lightweight field list.

get_published_form

Fetch the editable scaffold for a build started with start_custom_field_build: the SDK types, an example, the contract notes, and the current file tree. While the scaffold is still being prepared this returns { notReady: true, retryAfterMs } — wait that long and call again. Once ready, WRITE the field's code and send it with submit_custom_field. The contract notes define the root-level declaration files that drive registration (outputSchema.json, propertiesSchema.json, defaultProperties.json, observeFields.json) — read them before writing code. Preconditions: a buildId from start_custom_field_build.

get_custom_field_scaffold

List the automations wired to a published form as sanitized summaries: each automation's id, name, type, trigger, whether it is active, `actionTypes` (unique action-node types in first-seen order; legacy settings-based Google Sheets, Zapier, and basic-webhook rows derive this from `automationType`), optional `actionSummary` metadata only when exactly one valid action node exists (for a webhook: method + endpointHost — the URL's host only — whether it uses a custom body (bodyMode + hasCustomBody), and includeHiddenFields, the effective answer to whether the builder-generated payload (default/auto) carries the response's hidden-field values — omitted when a custom body decides the payload, because the flag does not shape it; never the body contents, URL, headers, or secrets), and a friendly summary of any router conditions. `actionSummary` is omitted for zero or multiple action-node graphs so multi-action automations are never presented as a single action. Use to survey what a form already does on submission, to get an id for update_automation, or to check for duplicates before creating a new one with create_automation. Do NOT use it to read the form's questions (use get_form / get_published_form), to read submitted responses (use list_responses), or to read automation RUN history/logs (not available here). Preconditions: a formId from list_forms (a Live/Closed form — automations attach to the published form; a never-published draft has none); the user must be a member of the form's workspace or the call returns forbidden. Read-only; nothing is changed. Returns { result }: an array of automation summaries. `conditions` is the router condition decompiled to the same friendly shape create_automation / update_automation accept (an empty array means it fires on every response); it is null with a `conditionsNote` when the automation's graph is too complex to summarize (multiple routes, an unsupported operand, or a hand-built custom graph) — open those in the dashboard.

list_automations