Tool Reference

Flow Forms exposes 16 tools organized into five 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 and submissions. These are the string IDs returned by tools like list-forms and create-form. Form element IDs are numeric.

Form Management

list-forms

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

Parameter	Type	Required	Default	Description
`search`	string	No	-	Search forms by name
`limit`	integer	No	50	Max results (1-100)

Returns: Array of forms with ID, name, slug, submission count, and timestamps.

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.

Parameter	Type	Required	Default	Description
`form_id`	string	Yes	-	The form ID (sqid)
`include_workflow`	boolean	No	false	Include workflow steps with group info and graduated form requirements

Returns: Form metadata and a fields array with each field's ID, name, type, required status, help text, and options.

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

create-form

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

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	The form name
`is_anonymous`	boolean	No	false	If true, no login is required to fill out the form
`send_notifications`	boolean	No	true	Send email notifications on new submissions
`is_private`	boolean	No	false	When true, submission data is excluded from notification emails (use for sensitive data like SSN, financial info, etc.)

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'"

Form Element Management

create-form-element

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

Parameter	Type	Required	Default	Description
`form_id`	string	Yes	-	The form ID (sqid)
`type`	string	Yes	-	Field type (see supported types below)
`name`	string	Yes	-	The field label shown to users
`required`	boolean	No	false	Whether this field must be filled in
`help`	string	No	-	Help text shown below the field
`options`	array	No	-	Options for select, radio, checkbox, or autocomplete fields
`sort`	integer	No	-	Position in form (appends to end if omitted)
`props`	object	No	-	Advanced configuration (see below)
`element_group_id`	string	No	-	Add this element as a child of a group element
`rules`	string	No	-	Validation rules (e.g., `email
`placeholder`	string	No	-	Placeholder text, or static content for `content` type elements

Supported field types:

Type	Description	Requires Options
`text`	Single-line text input	No
`textarea`	Multi-line text input	No
`email`	Email address input	No
`telephone`	Phone number input	No
`checkbox`	Multiple choice checkboxes	Yes
`radio`	Single choice radio buttons	Yes
`select`	Dropdown selection	Yes
`autocomplete`	Searchable dropdown	Yes
`date`	Date picker	No
`time`	Time picker	No
`file`	File upload	No
`signature`	Signature capture	No
`html`	Rich text input (user enters formatted text)	No
`content`	Static display text (for instructions, headers)	No
`group`	Repeatable section container	No
`composite`	Template-based computed text	No
`calculated`	Math operations on other fields	No

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.

Composite fields: First create the source fields, then create the composite with props.template (e.g., "{firstName} {lastName}") and props.fields referencing the source element IDs.

Calculated fields: Set props.operator to sum, multiply, subtract, or divide, and props.fields or props.operands referencing the source elements.

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.

Parameter	Type	Required	Default	Description
`form_id`	string	Yes	-	The form ID (sqid)
`elements`	array	Yes	-	Array of element definitions (same fields as create-form-element)
`start_sort`	integer	No	-	Starting position (appends after existing fields if omitted)

Cross-referencing with @ref:INDEX: Use @ref:0, @ref:1, etc. to reference other elements in the same batch. This is useful for:

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

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.

Parameter	Type	Required	Default	Description
`element_gid`	string	Yes	-	The element gid to update
`name`	string	No	-	New field label
`required`	boolean	No	-	Whether this field must be filled in
`help`	string	No	-	Help text shown below the field
`options`	array	No	-	New options (replaces all existing options)

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.

Parameter	Type	Required	Default	Description
`element_gid`	string	Yes	-	The element gid to delete

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.

Parameter	Type	Required	Default	Description
`element_gid`	string	Yes	-	The element gid to move
`position`	string	Yes	-	`"first"`, `"last"`, or `"after:{target_gid}"`

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

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

Submission Management

create-submission

Submit data to a form. Use get-form first to discover the form's fields and their IDs.

Parameter	Type	Required	Default	Description
`form_id`	string	Yes	-	The form ID (sqid)
`elements`	array	Yes	-	Array of values. Each needs `form_element_id` (numeric) or `name` (field name), plus `value`.
`user_id`	integer	No	-	User to associate with the submission (required unless form is anonymous)
`approver_user_ids`	array	No	-	User IDs for the first approval step. Required for "one" and "multiple" flow types.
`parent_submission_id`	string	No	-	Parent submission ID (sqid) for graduated form submissions

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
multi (optional, boolean) - set to true for multiple selections
quantity (optional) - for quantity-based fields

All required fields must have values. If a field name is duplicated, use form_element_id instead.

Returns: The submission ID (sqid) and URL.

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.

Parameter	Type	Required	Default	Description
`submission_id`	string	Yes	-	The submission ID (sqid)
`include_elements`	boolean	No	true	Include field values
`include_notes`	boolean	No	true	Include notes/comments
`include_history`	boolean	No	true	Include approval history
`include_children`	boolean	No	true	Include child submissions (graduated forms)
`include_workflow`	boolean	No	false	Include current workflow step and graduated form requirements

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.

Parameter	Type	Required	Default	Description
`form_id`	string	No	-	Scope to a specific form
`search`	string	No	-	Full-text search across field values
`statuses`	array	No	-	Filter by status: `pending`, `approved`, `denied`, `info_requested`, `sent_back`
`forms`	array	No	-	Filter by multiple form IDs (sqids)
`submitters`	array	No	-	Filter by submitter user IDs
`start`	string	No	-	Start date (YYYY-MM-DD)
`end`	string	No	-	End date (YYYY-MM-DD)
`terms`	object	No	-	Filter by field values: `{"elementId": ["value1", "value2"]}`
`pending`	array	No	-	Filter by user IDs with pending approvals
`pending_on_user`	boolean	No	false	Show only submissions pending on you
`limit`	integer	No	50	Max results (1-100)
`include_elements`	boolean	No	true	Include field values
`include_notes`	boolean	No	false	Include notes
`include_history`	boolean	No	false	Include approval history
`include_children`	boolean	No	false	Include child submissions

Filtering logic: When using terms, AND logic applies between different fields, OR logic applies within values for the same field. For example, {"department": ["Sales", "Marketing"], "status": ["Active"]} finds submissions where department is Sales OR Marketing, AND status 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.

Parameter	Type	Required	Default	Description
`submission_id`	string	Yes	-	The submission ID (sqid)
`message`	string	Yes	-	The note text

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.

Parameter	Type	Required	Default	Description
`submission_id`	string	Yes	-	The submission ID (sqid)
`next_approver_user_ids`	array	No	-	User IDs for the next approval step (required for "one" and "multiple" flow types)
`group_id`	integer	No	-	Group ID for group_select flow types

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.

Parameter	Type	Required	Default	Description
`submission_id`	string	Yes	-	The submission ID (sqid)
`reason`	string	No	-	Reason for denial (automatically added as a note)

Returns: Updated submission status and confirmation message.

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

Access Control

set-form-access

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

Parameter	Type	Required	Default	Description
`form_id`	string	Yes	-	The form ID (sqid)
`group_names`	array	Yes	-	Exact group names that should have access

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.

Parameter	Type	Required	Default	Description
`search`	string	No	-	Filter groups by name

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

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