Tool Reference

Flow Forms exposes 25 tools organized into seven categories. Each tool listing shows its name, what it does, parameters, and an example prompt you can use with your AI assistant.

A note about IDs: Flow Forms uses "sqids" (short unique IDs) for forms, submissions, and reports. These are the string IDs returned by tools like list-forms and create-form. Form elements carry two identifiers, and different tools want different ones: the numeric id is what create-submission and calculated fields reference, while the string gid is what update-form-element, delete-form-element, reorder-form-element, and set-element-condition take. get-form returns both for every field.

#Account

#whoami

Returns the ID, name, and email of the authenticated user - you, as far as Flow Forms is concerned. Useful for discovering your own user ID when another tool needs it, such as approver_user_ids.

No parameters.

Example: "Who am I logged in as?"

#Form Management

#list-forms

List forms in your account with optional search and pagination. Private forms are excluded.

Returns: Array of forms with ID, name, slug, submission count, anonymous and disabled flags, and timestamps, plus a total count.

Example: "Show me all forms with 'expense' in the name"

#get-form

Get a complete form definition including all fields with their IDs, types, and configurations.

Returns: Form metadata and a fields array with each field's numeric id and string gid, name, type, required status, help text, options, sort position, placeholder, rules, mask, group and section membership, visibility rule, props, and calculation details - plus top-level field_sets and conditions arrays. File fields also include multiple (true or false) so create-submission knows whether more than one file is allowed. The gid values here are the inputs to the element-editing tools, so start most element work with this call.

Example: "Get the full definition of form ABC123 including its workflow"

#create-form

Create a new form in your account. Requires form creation permission.

Returns: The created form with its ID, sqid, name, slug, and a link to the form editor.

Example: "Create a new anonymous form called 'Customer Feedback'"

#update-form

Rename a form or change its flags. Only provided fields are changed. Changing name regenerates the public slug (/form/{slug}).

Returns: The updated form with its ID, sqid, name, slug, flags, editor link, and public URL.

Example: "Rename this form to Gear and make it public"

#Form Element Management

#create-form-element

Add a field to a form. Supports 18 field types.

Supported field types:

Repeatable groups: When you see numbered/indexed fields like "Member 1 - Name", "Member 2 - Name", use a group element instead. Create one group element, then add child fields using element_group_id. Users can dynamically add and remove rows. Cap the rows with props.max_rows.

Composite fields: First create the source fields, then create the composite with props.template using @-syntax (e.g., "@element(gid1) @element(gid2)"; also @submission(id|hash), @user(name|email|phone)). props.fields is derived from the template automatically - any value you supply for it is ignored. Legacy {id} tokens are rejected.

Calculated fields: Set props.operator to sum, multiply, subtract, divide, min, max, age (from a date field), time_difference (between two time fields), or date_offset (one date field plus props.days and props.direction of forward or back), and props.fields or props.operands referencing the source elements. props.format controls presentation: money, number, or the default plain number - and for time_difference, human (2 hours 3 minutes), minutes, or decimal. date_offset stores a calendar date (optional format: default Y-m-d, day, or american).

Returns: The created element with its ID, gid, type, name, sort position, and configuration.

Example: "Add a required email field called 'Work Email' to form ABC123"

#batch-create-form-elements

Create multiple fields in a single operation. More efficient than calling create-form-element multiple times.

Cross-referencing with @ref:INDEX: Use @ref:0, @ref:1, etc. to reference other elements in the same batch. This works in two places:

• Adding child fields to a group: set element_group_id to @ref:0 where index 0 is the group element
• Calculated fields: reference source fields in props.fields

It does not work for composite fields - a composite's template needs real gids, so create the source fields in one batch, then create the composite once their gids exist.

Returns: The count of created elements and details for each.

Example: "Add a Name, Email, and Department dropdown with options Sales, Engineering, and Marketing to form ABC123"

#update-form-element

Update an existing form element. Only the fields you provide are changed. Requires edit permission on the form.

Returns: The updated element with its current configuration.

Example: "Rename the 'Full Name' field to 'Legal Name'"

#delete-form-element

Remove a field from a form. Requires edit permission on the form.

Returns: Confirmation with the deleted element's name.

Example: "Remove the phone number field from my form"

#reorder-form-element

Move a field to a new position in the form.

Returns: Confirmation with the element's new sort position.

Example: "Move the email field to the top of the form"

#create-field-set

Create a section on a form - the tabbed groupings respondents work through one at a time. Returns the section's ID to use as field_set_id when creating or updating elements.

Sections hold top-level elements; fields inside a repeatable group cannot belong to one.

Returns: The created field set's ID and name.

Example: "Add a 'Contact Details' section to form ABC123 and move the name and email fields into it"

#set-element-condition

Control when fields are shown. Creates a show/hide rule from trigger clauses and attaches it to the target fields: the targets are visible only while the rule evaluates true.

Operators: is equal to, is not equal to, is greater than, is greater than or equal to, is less than, is less than or equal to, contains, does not contain, is empty, is not empty. A value is required except for the empty checks. For checkbox triggers use contains, since checkboxes store multiple values.

Connectives: each clause carries and (the default) or or. Clauses are not folded left to right: all the and clauses must be true together, and that result is OR'd with each or clause independently.

Returns: The rule's ID, name, clauses, and attached targets.

Example: "Only show the 'Other - please specify' field when Department is equal to Other"

#Submission Management

#create-submission

Submit data to a form. Use get-form first to discover the form's fields and their IDs. The submission is recorded as coming from you - the authenticated user - unless the form is anonymous. Note that this tool requires edit permission on the form, so it is for form editors and administrators, not general respondents.

Element values: Each element in the elements array should include:

• form_element_id (numeric) or name (field label) to identify the field
• value - the submitted value for non-file fields
• files (file fields only) - array of { filename, content }. content is raw base64 or a data:*;base64,... URL. Each file must be 300 MB or smaller. Send more than one file only when get-form reports multiple: true for that field. Do not send files on signature or other non-file fields.
• multi (optional, boolean) - set to true for multiple selections
• quantity (optional) - for quantity-based fields

All required fields must have values. A required file field needs at least one file — an empty files array does not count. If a field name is duplicated, use form_element_id instead.

Conditionally hidden fields: Visibility rules apply to tool submissions the same way they apply in the browser. A required field that is hidden by the submitted values is not required, and a value submitted for a hidden field is discarded rather than stored.

Returns: The submission ID (sqid) and URL - plus a notes array explaining any values that were discarded because their fields were hidden.

Example: "Submit the leave request form with start date Jan 5 and end date Jan 10"

#get-submission

Get a single submission with full details.

Returns: Submission details with user info, status, and optionally elements, notes, process history, children, and workflow context.

Example: "Show me submission XYZ789 with its approval history and workflow context"

#get-submissions

Search and filter submissions across forms.

Filtering logic: terms keys are numeric element IDs (from get-form), not field names - a field-name key is silently ignored. AND logic applies between different elements, OR logic within one element's values. For example, {"1234": ["Sales", "Marketing"], "5678": ["Active"]} finds submissions where element 1234 is Sales OR Marketing, AND element 5678 is Active.

Returns: Array of submissions with total count.

Example: "Find all pending expense submissions from the last month"

#add-submission-note

Add a comment or note to a submission.

Returns: The note with its ID, message, author name, and timestamp.

Example: "Add a note to submission XYZ789 saying 'Approved by finance team'"

#Workflow and Approval

#approve-submission

Approve a submission, advancing it through its approval workflow. You must have an active approval notification for the submission.

Graduated forms: If the current approval step requires a graduated form to be completed first, you must create the child submission using create-submission with parent_submission_id before approving.

Returns: Updated submission status and confirmation message.

Example: "Approve submission XYZ789"

#deny-submission

Deny a submission, ending its workflow. You must have an active approval notification for the submission.

Returns: Updated submission status and confirmation message.

Example: "Deny submission XYZ789 because the receipt is missing"

#Reporting and Analytics

#compute-aggregates

Compute counts, sums, averages, min/max, and per-column breakdowns over a form's submissions on the fly - the same semantics as a report, without saving one. Drafts and deleted submissions are excluded.

Returns: The computed values, plus a config_echo you can pass to create-report to save the same analysis as a report.

Example: "How many t-shirts of each size have been ordered on the merch form?"

#list-reports

List reports visible to you, each belonging to a form and holding filters, aggregations, columns, and charts.

Returns: Array of reports with ID, name, and form.

Example: "What reports exist for the expense form?"

#get-report

Get a report's full configuration plus the column vocabulary available on its form. Use before updating a report.

Returns: The report's filters, aggregations, columns, and charts, plus available_columns for the form.

Example: "Show me how the quarterly expenses report is configured"

#create-report

Create a report for a form, optionally with initial filters, aggregations, columns, and charts. Reports appear on the account's report pages.

Column names come from get-report on an existing report of the same form, or from available_columns in this tool's response.

Returns: The created report with its ID and a link.

Example: "Create a report on the expense form showing total amount by month, filtered to approved submissions"

#update-report

Update a report's name or configuration. Each config section you provide replaces that section entirely - read the current config with get-report first, and send an empty array to clear a section. Omitted sections are left unchanged.

Returns: The updated report configuration.

Example: "Add a chart of submissions per week to the intake report"

#Access Control

#set-form-access

Control which groups can access and fill out a form. This replaces all existing access settings.

Use list-groups first to see the available group names. All group names must match exactly.

Returns: The form ID and its updated list of groups with access.

Example: "Give the Sales and Marketing groups access to the feedback form"

#list-groups

List all groups in your account.

Returns: Array of groups with ID and name, plus total count.

Example: "What groups are available in this account?"