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.

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.

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.

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.

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.

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. Legacy {id} tokens are rejected.

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.

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.

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"

#Submission Management

#create-submission

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

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.

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: 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.

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"

#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?"