# 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|max:255`, `numeric|min:0`) |
| `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` 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.

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