Tally

Create or update logic rules using DSL syntax: WHEN <condition> THEN <action>. <uuid_references> All UUIDs come from the ledger. Use the correct column: - **Condition LHS** → questionUuid column - **Condition RHS for choice fields (Dropdown, MultipleChoice, Checkboxes)** → optionBlockUuid (NOT the option text) - **Condition LHS for Matrix** → row blockUuid (MATRIX_ROW) - **Condition RHS for Matrix** → matrix column blockUuid (NOT the option text) - **SHOW/HIDE a full question** → questionUuid column - **SHOW/HIDE a single block (e.g. one option)** → blockUuid column - **REQUIRE** → questionUuid column - **JUMP TO PAGE** → page number column </uuid_references> <conditions> Each condition compares a field to a value, e.g. `<priceUuid> > 100`. Don't apply math to the field, and don't compare two fields to each other (for choice fields, the comparison value can still be an optionBlockUuid). To check a calculated value (like price × qty > 100), store the result as a calc field first and use that: - Choice fields (Dropdown, MultipleChoice): `<questionUuid> IS <optionBlockUuid>` / `IS NOT <optionBlockUuid>` - Text/Email/Link/Phone fields: `<questionUuid> IS "literal text"` / `IS NOT "literal text"` - Empty check (any field): `<questionUuid> IS EMPTY` / `IS NOT EMPTY` - Number/Rating/LinearScale: `<questionUuid> > 5` (any of `> >= < <= = !=`) - Text matching: `<questionUuid> CONTAINS "text"` / `DOES NOT CONTAIN "text"` - Text matching: `<questionUuid> STARTS WITH "text"` / `ENDS WITH "text"` - Text matching: `<questionUuid> DOES NOT START WITH "text"` / `DOES NOT END WITH "text"` - Checkboxes/MultiSelect (arrays): `<questionUuid> IS ANY OF (<blockUuid>,<blockUuid>)` / `IS NOT ANY OF` / `IS EVERY OF` - Checkboxes/MultiSelect: do NOT use IS/IS NOT — use CONTAINS or IS ANY OF instead - Matrix: `<matrixRowBlockUuid> IS <matrixColumnBlockUuid>`; use CONTAINS / IS ANY OF when multiple selection is enabled - Date fields: `<questionUuid> IS BEFORE "2024-01-01"` / `IS AFTER "2024-01-01"` - Combine: `<cond1> AND <cond2>` or `<cond1> OR <cond2>` (parentheses required when mixing) </conditions> <actions> - `SHOW <questionUuid>` / `HIDE <questionUuid>` (comma-separate for multiple) - `SHOW <blockUuid>` / `HIDE <blockUuid>` to target a single block within a question - `REQUIRE <questionUuid>` - `JUMP TO PAGE <pageNumber>` — jump to a specific page (use the page number from the ledger's page column). Check the Page flow section for current page order. - `JUMP TO END` — end the form early (jump to the default thank you page). If a custom thank you page exists, it will target that page instead. - `CALCULATE <calcFieldUuid> = <expression>` — assign a formula expression to a calculated field. See <calculated_fields> below. - `DISABLE SUBMISSION` — hide the submit button so the form can't be submitted while the condition holds (eligibility gate). Takes no target. - Multiple actions: `SHOW <questionUuid>, REQUIRE <questionUuid>` </actions> <calculated_fields> Group calc field writes that share a condition into one rule's THEN clause; only split into separate rules when the conditions differ (e.g., per-event accumulators). - **Target** (left of `=`): the UUID of a calculated field from a `CALCULATED_FIELDS` block. The ledger lists them in the properties column as `<calcFieldUuid>=<name>(<TYPE>)` — use the UUID. Create the block via create_blocks before writing CALCULATE rules. - **Expression** (right of `=`): `+ - * /` for NUMBER, `+` only for TEXT concat. Parens for precedence. Number and string literals allowed. Field refs are bare uuids – questionUuid for inputs, the calc field's own uuid (properties column) for cross-calc / self-reference. No blockUuid, no `{{ }}`, no functions. - **Multiple writes per rule**: a single `THEN` can contain any number of CALCULATEs (and other actions). Comma-separated. - **Sequential evaluation**: CALCULATEs run top-to-bottom — each reads values left by earlier rules. Place dependent CALCULATEs in dependency order (e.g. compute `subtotal` before `tax`), or group them under one THEN to lock the order. - **Defaults**: NUMBER calc fields start at 0, TEXT at `""` when no `value` is set on the field. - **Constants on the field, not in rules**: For values that never change (e.g. `taxRate = 0.21`, `greeting = "Hi "`), set `value` on the calc field at creation time via create_blocks. Don't write a CALCULATE rule whose right-hand side is just a literal — CALCULATE is for expressions with field references. - **Calc fields are never empty** – they always carry the default (0 or `""`). IS [NOT] EMPTY on a calc field is rejected. To gate a calculation on user input completion, use IS NOT EMPTY on the INPUT field driving the calc (not on the calc itself). To check the calc value, use a numeric comparison (`> 0`, `!= 0`) for NUMBER or `IS` / `IS NOT` for TEXT — but only when the default specifically means "not yet answered" (e.g. quiz score), not when 0 / `""` is a legitimate result (e.g. an opt-out fee). - **Self-reference works** — the target can appear in its own expression. Use this for accumulators (quiz scoring, running totals) instead of creating per-question intermediate fields. - **No cycles between calc fields** — if rule A writes `<X>` using `<Y>`, no other rule should write `<Y>` using `<X>`. Cycles produce stale values, not an error. Example patterns (replace `<...Uuid>` with real UUIDs from the ledger): <example>WHEN <priceUuid> IS NOT EMPTY THEN CALCULATE <totalUuid> = <priceUuid> * <qtyUuid></example> <example>WHEN <amountUuid> > 100 THEN CALCULATE <discountUuid> = <amountUuid> * 0.1</example> <example>WHEN <firstUuid> IS NOT EMPTY THEN CALCULATE <greetingUuid> = "Hello " + <firstUuid> + " " + <lastUuid></example> <example> Multi-step under one condition — derive subtotal, tax, and total in a single rule: WHEN <priceUuid> IS NOT EMPTY THEN CALCULATE <subtotalUuid> = <priceUuid> * <qtyUuid>, CALCULATE <taxUuid> = <subtotalUuid> * 0.21, CALCULATE <totalUuid> = <subtotalUuid> + <taxUuid> </example> <example> Accumulator — one rule per event because the WHEN differs (quiz: +1 per correct answer): WHEN <q1Uuid> IS <correct1Uuid> THEN CALCULATE <scoreUuid> = <scoreUuid> + 1 WHEN <q2Uuid> IS <correct2Uuid> THEN CALCULATE <scoreUuid> = <scoreUuid> + 1 </example> </calculated_fields> <defaults> The tool handles these — do NOT do them manually: - SHOW auto-hides the target (isHidden: true). Do NOT call configure_blocks to hide it first. - REQUIRE auto-marks the target optional (isRequired: false). Do NOT call configure_blocks to unset it first. </defaults> <no_if_else> There is no if-else — do NOT add HIDE as the "else" for a SHOW rule. Logic rules are NOT if-else. All SHOW targets start hidden by default. When a SHOW condition is false, the target simply stays hidden — no HIDE needed. <example> WRONG — adds useless HIDE actions: WHEN score <= 6 THEN SHOW feedback, HIDE review WHEN score >= 9 THEN SHOW review, HIDE feedback RIGHT — each rule only SHOWs its target: WHEN score <= 6 THEN SHOW feedback WHEN score >= 9 THEN SHOW review </example> The HIDE in the wrong example is a no-op: - fields that are marked as SHOW are automatically hidden by default - fields that are marked as REQUIRE are automatically optional by default </no_if_else> <verb_matches_user> Match the action to the verb the user used. Don't invert by negating the condition. - User says "hide X when Y" → `WHEN <Y> THEN HIDE <X>` (target stays visible by default). - User says "show X when Y" → `WHEN <Y> THEN SHOW <X>` (target hidden by default, revealed when condition fires). <example> User: "Hide the company name field when the role is Student" WRONG — inverted into SHOW + negated condition: WHEN role IS Professional THEN SHOW companyName WHEN role IS Academic THEN SHOW companyName RIGHT — direct HIDE matching the user's verb: WHEN role IS Student THEN HIDE companyName </example> </verb_matches_user>

apply_logic

Configure block's properties. Use the current form ledger to find blocks and their properties. IMPORTANT: - Those are partial (incremental) updates - only properties you include will be changed - Set a property to null to unset it - To change the type of a question, use the change_type operation once on ONLY 1 option block in the group. This will change the entire group to that type. - To hide entire question, update the TITLE block and all question blocks will be hidden automatically - For hidden_fields_settings: provide the complete list of hidden fields (add new, remove by exclusion, rename by keeping UUID and changing name) - For calculated_fields_settings: provide the complete list of calculated fields (add/remove/rename/change-value/retype). Keep an existing field's UUID to update it (rename, change type, change value), omit UUID for new entries, exclude an entry to remove it. CALCULATE rules referencing a removed field are auto-cleaned. To remove a single calc field while keeping others, remove_blocks works too — pass that field's UUID directly.

configure_blocks

Creates new blocks in the form. Blocks default structure with examples: - Name question: [TITLE, INPUT_TEXT] (short text) - Message question: [TITLE, TEXTAREA] (long text) - Country question: [TITLE, DROPDOWN_OPTION, DROPDOWN_OPTION, ...] (compact single-select) - Interests question: [TITLE, CHECKBOX, CHECKBOX, ...] (multi-select checklist) - Satisfaction question: [TITLE, LINEAR_SCALE] (numeric scale with labels) - Quality rating: [TITLE, RATING] (star rating) - Payment collection: [TITLE, PAYMENT] (collect payment with Stripe) - Yes/No question: [TITLE, MULTIPLE_CHOICE_OPTION, MULTIPLE_CHOICE_OPTION] (radio buttons) - Skills multi-select: [TITLE, MULTI_SELECT_OPTION, MULTI_SELECT_OPTION, ...] (dropdown multi-select) - Priorities ranking: [TITLE, RANKING_OPTION, RANKING_OPTION, ...] (drag to reorder) - Matrix table: [TITLE, MATRIX, MATRIX_COLUMN, MATRIX_COLUMN, ..., MATRIX_ROW, MATRIX_ROW, ...] (columns first, then rows) - Bot protection: [CAPTCHA] (no TITLE needed) - Location detection: [RESPONDENT_COUNTRY] (auto-detects from IP, no TITLE needed) - URL tracking: [HIDDEN_FIELDS] (captures query params like ?utm_source=email&campaign=summer, no TITLE needed) - Calculated fields: [CALCULATED_FIELDS] (named targets for CALCULATE logic rules, no TITLE needed) - New page: [PAGE_BREAK, ...content] (creates a new page with content) - New section: [HEADING_2, TEXT, ...content] (creates a new section with content) PAGE BREAK SEMANTICS: - PAGE_BREAK starts a new page - All blocks on a page share the same page number in the ledger IMPORTANT: - Groups with the same insertAfterBlockUuid = auto-chain groups (only first group uses it, rest chain). - All questions are REQUIRED by default. The user sees a required indicator automatically in the UI. If you need to make a question optional, use configure_blocks tool after creating the question. Examples with ledger: # | text | blockUuid | type | questionUuid | page | insertAfterBlockUuid_BEFORE | notes PAGE 1 ─────────────────────────────────────────────────────────────────────────────────────────────────────── 1 | Contact | aaa | FORM_TITLE | - | 1 | - | Form start 2 | Name | bbb | TITLE | xxx | 1 | aaa | Name question starts 3 | | ccc | INPUT_TEXT | xxx | 1 | bbb | Name question ends 4 | Country | ddd | TITLE | yyy | 1 | ccc | Country question starts 5 | US | eee | DROPDOWN_OPTION | yyy | 1 | ddd | Country question 6 | UK | fff | DROPDOWN_OPTION | yyy | 1 | eee | Country question ends PAGE 2 ─────────────────────────────────────────────────────────────────────────────────────────────────────── 7 | | ggg | PAGE_BREAK | - | 2 | fff | Page break (creates new page) 8 | Email | hhh | TITLE | zzz | 2 | ggg | Email question starts 9 | | iii | INPUT_EMAIL | zzz | 2 | hhh | Email question ends Add phone after name: // AFTER a question: copy the row's "blockUuid" you want to insert after (last block of the question) {"groups":[{"blocks":[{"type":"TITLE","html":"Phone"},{"type":"INPUT_PHONE_NUMBER"}],"insertAfterBlockUuid":"ccc"}]} Add company before country: // CRITICAL: BEFORE a question means DIRECTLY BEFORE the question. Use the row immediately preceding the question; there should be NO other rows between! // Find "Country" in the current form ledger and copy its "insertAfterBlockUuid_BEFORE" into insertAfterBlockUuid {"groups":[{"blocks":[{"type":"TITLE","html":"Company"},{"type":"INPUT_TEXT"}],"insertAfterBlockUuid":"ccc"}]} Add subtitles/descriptions/hints to each question: // WITHIN a question: use question's TITLE blockUuid // Execute in one atomic tool call: a group per subtitle. {"groups":[{"blocks":[{"type":"TEXT","html":"Your full legal name"}],"insertAfterBlockUuid":"bbb"},{"blocks":[{"type":"TEXT","html":"Select your country"}],"insertAfterBlockUuid":"ddd"},{"blocks":[{"type":"TEXT","html":"Your business email"}],"insertAfterBlockUuid":"hhh"}]} Add welcome text at the top: // AT THE TOP: use FORM_TITLE's blockUuid {"groups":[{"blocks":[{"type":"TEXT","html":"Welcome!"}],"insertAfterBlockUuid":"aaa"}]} Add birthdate, birth place and website after name: // Execute in one atomic tool call: sequential blocks together in one group. {"groups":[{"blocks":[{"type":"TITLE","html":"Birthdate"},{"type":"INPUT_DATE"},{"type":"TITLE","html":"Birth place"},{"type":"INPUT_TEXT"},{"type":"TITLE","html":"Website"},{"type":"INPUT_LINK"}],"insertAfterBlockUuid":"ccc"}]} Add new Page 1 with welcome text: // AT THE TOP: use FORM_TITLE's blockUuid {"groups":[{"blocks":[{"type":"PAGE_BREAK"},{"type":"TEXT","html":"Welcome!"}],"insertAfterBlockUuid":"aaa"}]} Add page 3 with phone question: // After last block on page 2 {"groups":[{"blocks":[{"type":"PAGE_BREAK"},{"type":"TITLE","html":"Phone"},{"type":"INPUT_PHONE_NUMBER"}],"insertAfterBlockUuid":"iii"}]} Split the first page into two pages after name: // Use blockUuid where page should split // PAGE_BREAK is the only block in the group, no other blocks allowed {"groups":[{"blocks":[{"type":"PAGE_BREAK"}],"insertAfterBlockUuid":"ccc"}]} Add hidden fields to capture UTM parameters: // Hidden fields capture values from URL query string (e.g., ?utm_source=email&utm_campaign=spring) // Can not have a TITLE - these fields are invisible to users {"groups":[{"blocks":[{"type":"HIDDEN_FIELDS","hiddenFields":[{"name":"utm_source"},{"name":"utm_campaign"},{"name":"utm_medium"}]}],"insertAfterBlockUuid":"iii"}]} Add thank you page with thank you message: // Use the last block's blockUuid {"groups":[{"blocks":[{"type":"PAGE_BREAK","isThankYouPage":true},{"type":"TEXT","html":"Thank you for submitting!"}],"insertAfterBlockUuid":"iii"}]} FIELD REFERENCES IN TEXT (Mentions): Use {{questionUuid}} or {{Field Title}} in TEXT, TITLE, or HEADING html to display a field's answer dynamically. Only reference existing fields — create the field first, then reference it. Example: {"type":"TEXT","html":"Hello {{2c1674f6-843d-4fca-bddd-6598f0040ca7}}!"} This is NOT for default answers — use configure_blocks with defaultAnswer for that.

create_blocks

Create a new form with the specified title and optional styling. This will clear any existing blocks and start fresh. MUST call SaveForm after building the form to publish it.

create_new_form

Extract colors, fonts, and images from a website URL. Use when users want to match their website, copy brand colors, or style forms like an existing site. Automatically extracts primary/accent colors, button styling, and fonts for use with update_styling tool.

extract_brand

Fetch form analytics and performance insights. Returns metrics (views, completions, conversion rate), visitor time-series, submission time-series, traffic dimensions (sources, browsers, countries), and question drop-off data. Use the include parameter to request only specific sections.

fetch_insights

Fetch submissions for a form. Returns paginated results with question labels and response data. Use the page parameter to navigate through results when hasMore is true.

fetch_submissions

Return Tally's CSS selector reference and this form's current custom CSS. Call before writing a value for update_custom_css so you can merge with existing rules instead of overwriting them.

inspect_custom_css

Retrieve the current form structure as a ledger. The ledger shows all blocks with their UUIDs, types, positions, and properties.

list_blocks

List forms the user has access to. Returns paginated results with form metadata including name, status, submission count, and timestamps. Use the page parameter to navigate through results when hasMore is true. Optionally filter by workspace IDs.

list_forms