Formstep

Update form settings

formSettings_update

Update form settings. Only provide fields to change. Use this for form BEHAVIOR — email notifications, scheduling/limits, redirects. For the form's name/folder/cover/logo use form_update; for colors/fonts/visual theme use formTheme_set; for questions and content use the editor_* tools.

Three independent email flows: self-notification (form owner/team on submit), respondent notification (confirmation to respondent), respondent reminder (when respondent abandons mid-form, Pro tier). Each is gated by its own *Enabled flag and accepts a custom subject + body. Respondent-targeted flows require *To to point at an email-input field ID (find via editor_getDocument). A fourth, the request invitation (requestInvitationSubject/Body), has no switch: request_create decides per request whether it is sent.

Localization: customizing a respondent confirmation/reminder subject or body makes it translatable — the keys appear in translationDraft_get immediately (no form publish needed); localize via translationDraft_get → translationDraft_update. Self-notification (owner) emails are NOT translatable; write them directly in the target language here.

Custom From domain: pass emailDomainId from formSettings_get → availableEmailDomains; null resets to noreply@formstep.io.

{{variable}} placeholders for subjects/bodies: {{email.formName}}, {{email.submittedAt}}, {{email.submissionId}}, {{email.submissionType}}, {{metadata.formId}}, {{metadata.authorizedEmail}}, {{metadata.pin4|pin6|code4|code6}}, plus any answer as {{}} (the field key fields_list shows; the input node id from form_get questions[].id also works). Keys read back as {{}}. load_skill("form-settings") describes each.

Input Schema

Name	Required	Description
`formId`	Yes	Form ID to update settings for
`language`	No	BCP-47 language tag (e.g. "en", "en-US", "pt-BR"). Defaults to "en".
`maxEdits`	No	Max post-submit edits allowed per submission (requires editAfterSubmit). 0 = unlimited on Pro and Business, 3 on Free.
`password`	No	Form access password. Setting a string implies passwordEnabled:true. Pass null to clear the gate (sets passwordEnabled:false).
`redirectUrl`	No	http(s) URL respondents land on after submission. null or empty string clears. Mutually exclusive with allowAnotherResponse:true.
`showBranding`	No	Show Formstep branding on the form.
`emailDomainId`	No	Verified email domain ID for custom From address. Read availableEmailDomains from formSettings_get for valid IDs. null resets to default.
`reminderSteps`	No	Idle offsets from the respondent's last activity, e.g. ["1d","3d","1w"]. Max 5, sorted and deduped on save; [] = none. Applies to abandoned public-link responses and requests.
`captchaEnabled`	No	Enable Turnstile bot protection.
`editAfterSubmit`	No	Allow respondents to edit a submission after sending.
`passwordEnabled`	No	Gate form with a password. Auto-set to true when `password` is provided. Setting true requires a stored password.
`draftRetentionDays`	No	Days to keep abandoned drafts. null reverts to runtime default.
`notificationEmails`	No	Email addresses receiving submission notifications. Duplicates are collapsed case-insensitively.
`notifyOnSubmission`	No	Email form owner/team on new submissions.
`redirectQueryParams`	No	Map form field values as query parameters on the redirect URL. Each entry maps a URL param name to a field ID.
`allowAnotherResponse`	No	After submitting, loop respondents back to a fresh empty form. Mutually exclusive with a non-empty redirectUrl.
`pdfGenerationEnabled`	No	Attach submission PDF to self-notification emails. Pro tier.
`respondentReminderTo`	No	Field ID of an email-type question. Set to null to clear.
`requestInvitationBody`	No	Custom body for the request invitation email. Same placeholders as the subject; newlines become paragraphs. Pro tier.
`requireAuthentication`	No	Require respondents to be logged in.
`respondentReminderBody`	No	Custom body for the reminder email. Plain text with optional {{variable}} placeholders; newlines become paragraphs.
`selfNotificationSubject`	No	Custom subject for self-notification emails. Plain text with optional {{variable}} placeholders.
`submissionRetentionDays`	No	Days to keep submissions. null = runtime default. Also clears a fixed deletion date set in the builder (the two modes are exclusive). Business plan.
`requestInvitationSubject`	No	Subject of the request invitation email (request_create delivery "email"). Plain text with {{variable}} placeholders; context and prefill keys resolve, submission metadata does not. Pro tier.
`respondentNotificationTo`	No	Field ID of an email-type question. Respondent email is extracted from their answer to this field. Set to null to clear.
`showViewSubmissionButton`	No	Show "View Submission" button in self-notification emails.
`respondentReminderEnabled`	No	Enable reminder email to respondents who started but did not complete the form. Pro tier.
`respondentReminderSubject`	No	Custom subject for the reminder email. Plain text with optional {{variable}} placeholders.
`selfNotificationEmailBody`	No	Custom body for self-notification emails. Plain text with optional {{variable}} placeholders; newlines become paragraphs.
`respondentNotificationBody`	No	Custom body for respondent confirmation email. Plain text with optional {{variable}} placeholders; newlines become paragraphs.
`maxSubmissionsPerRespondent`	No	Max submissions per respondent via "Submit another response" (requires allowAnotherResponse). 0 = unlimited. Enforced for signed-in respondents, client-gated for anonymous.
`respondentReminderIdleWindow`	No	Single-step form of `reminderSteps`, kept for older forms. Ignored when `reminderSteps` is set.
`respondentNotificationEnabled`	No	Enable confirmation email sent to the respondent after submission.
`respondentNotificationSubject`	No	Custom subject for respondent confirmation email. Plain text with optional {{variable}} placeholders.
`respondentNotificationPdfEnabled`	No	Attach submission PDF to respondent confirmation email. Pro tier.
`respondentReminderRequiredFieldIds`	No	Minimum fields a respondent must have answered for the reminder to fire. Each item is a field ID from editor_getDocument. Empty array = remind any partial response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed31 schema fields changedOct 16, 2026

changedInput schema / properties / draftRetentionDays / description

Previous value: -"Days to keep abandoned drafts (0–36500). null reverts to runtime default."New value: +"Days to keep abandoned drafts. null reverts to runtime default."

addedInput schema / properties / draftRetentionDays / maximum
```
Added value: +36500
```
addedInput schema / properties / draftRetentionDays / minimum
```
Added value: +0
```

changedInput schema / properties / draftRetentionDays / type

Previous value: -[
-  "number",
-  "null"
-]New value: +[
+  "integer",
+  "null"
+]

addedInput schema / properties / formId / minLength
```
Added value: +1
```

changedInput schema / properties / maxEdits / description

Previous value: -"Max post-submit edits allowed per submission (requires editAfterSubmit). 0 = unlimited on Pro and Business, 3 on Free; max 3."New value: +"Max post-submit edits allowed per submission (requires editAfterSubmit). 0 = unlimited on Pro and Business, 3 on Free."

addedInput schema / properties / maxEdits / maximum
```
Added value: +3
```
addedInput schema / properties / maxEdits / minimum
```
Added value: +0
```

changedInput schema / properties / maxEdits / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / maxSubmissionsPerRespondent / description

Previous value: -"Max submissions one respondent may make via \"Submit another response\" (requires allowAnotherResponse). 0 = unlimited; max 1000. Hard-enforced for signed-in respondents; client-gated for anonymous."New value: +"Max submissions per respondent via \"Submit another response\" (requires allowAnotherResponse). 0 = unlimited. Enforced for signed-in respondents, client-gated for anonymous."

addedInput schema / properties / maxSubmissionsPerRespondent / maximum
```
Added value: +1000
```
addedInput schema / properties / maxSubmissionsPerRespondent / minimum
```
Added value: +0
```
changedInput schema / properties / maxSubmissionsPerRespondent / type
```
Previous value: -"number"New value: +"integer"
```

changedInput schema / properties / notificationEmails / description

Previous value: -"Email addresses receiving submission notifications. At most 10; duplicates are collapsed case-insensitively."New value: +"Email addresses receiving submission notifications. Duplicates are collapsed case-insensitively."

removedInput schema / properties / notificationEmails / items / format
```
Removed value: -"email"
```
addedInput schema / properties / notificationEmails / items / pattern
```
Added value: +"^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
```

changedInput schema / properties / notificationEmails / type

Previous value: -"array"New value: +[
+  "array",
+  "null"
+]

changedInput schema / properties / password / description

Previous value: -"Form access password (≥4 chars). Setting a string implies passwordEnabled:true. Pass null to clear the gate (sets passwordEnabled:false)."New value: +"Form access password. Setting a string implies passwordEnabled:true. Pass null to clear the gate (sets passwordEnabled:false)."

changedInput schema / properties / redirectQueryParams / type

Previous value: -"array"New value: +[
+  "array",
+  "null"
+]

addedInput schema / properties / redirectUrl / pattern
```
Added value: +"^(https?:\\/\\/.+)?$"
```

changedInput schema / properties / reminderSteps / description

Previous value: -"Reminder schedule as idle offsets from the respondent's last activity, e.g. [\"1d\",\"3d\",\"1w\"]. Max 5 steps, sorted and deduped on save; [] = no automatic reminders. Applies to both abandoned public-link responses and requests."New value: +"Idle offsets from the respondent's last activity, e.g. [\"1d\",\"3d\",\"1w\"]. Max 5, sorted and deduped on save; [] = none. Applies to abandoned public-link responses and requests."

addedInput schema / properties / reminderSteps / items / minLength
```
Added value: +1
```

changedInput schema / properties / reminderSteps / type

Previous value: -"array"New value: +[
+  "array",
+  "null"
+]

changedInput schema / properties / requestInvitationSubject / description

Previous value: -"Custom subject for the request invitation email (request_create delivery \"email\"). Plain text with optional {{variable}} placeholders; context and prefill keys resolve, submission metadata does not. Pro tier."New value: +"Subject of the request invitation email (request_create delivery \"email\"). Plain text with {{variable}} placeholders; context and prefill keys resolve, submission metadata does not. Pro tier."

changedInput schema / properties / respondentReminderIdleWindow / description

Previous value: -"Single-step form of `reminderSteps`, kept for forms authored before multi-step schedules. Ignored when `reminderSteps` is set."New value: +"Single-step form of `reminderSteps`, kept for older forms. Ignored when `reminderSteps` is set."

addedInput schema / properties / respondentReminderRequiredFieldIds / items / minLength
```
Added value: +1
```
changedInput schema / properties / respondentReminderRequiredFieldIds / type
```
Previous value: -"array"New value: +[
+  "array",
+  "null"
+]
```

changedInput schema / properties / submissionRetentionDays / description

Previous value: -"Days to keep submissions (0–36500). null reverts to runtime default. Setting a value also clears any fixed deletion date configured in the form builder (the two retention modes are mutually exclusive). Business plan."New value: +"Days to keep submissions. null = runtime default. Also clears a fixed deletion date set in the builder (the two modes are exclusive). Business plan."

addedInput schema / properties / submissionRetentionDays / maximum
```
Added value: +36500
```
addedInput schema / properties / submissionRetentionDays / minimum
```
Added value: +0
```

changedInput schema / properties / submissionRetentionDays / type

Previous value: -[
-  "number",
-  "null"
-]New value: +[
+  "integer",
+  "null"
+]

Changed2 schema fields changedOct 15, 2026

addedInput schema / properties / requestInvitationBody

Added value: +{
+  "description": "Custom body for the request invitation email. Same placeholders as the subject; newlines become paragraphs. Pro tier.",
+  "type": "string"
+}

addedInput schema / properties / requestInvitationSubject

Added value: +{
+  "description": "Custom subject for the request invitation email (request_create delivery \"email\"). Plain text with optional {{variable}} placeholders; context and prefill keys resolve, submission metadata does not. Pro tier.",
+  "type": "string"
+}

First observedOct 8, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare only readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description adds substantial behavioral context: the three gated email flows plus the switch-less request invitation, tier gating (Pro/Business), and the non-obvious side effect that customizing a respondent subject/body makes it translatable immediately with keys surfacing in translationDraft_get, while owner self-notification text is NOT translatable. It also explains null-clearing semantics for emailDomainId and password.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and sibling routing in the first sentence, then layered by topic (email flows, localization, From domain, placeholders). For a 36-parameter tool the length is largely earned, but the placeholder enumeration and flow prose are dense and begin to duplicate what the referenced load_skill("form-settings") presumably expands.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 36 parameters, one enum, no nested objects and no output schema, the description covers the hard parts: which settings belong to this tool, how the email flows interlock, tier limits, and clear/reset semantics. It never states what the call returns or how partial updates are echoed back, and directs some depth to a skill rather than being self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still earns above baseline by explaining cross-parameter relationships the schema states only locally (respondent *To must point at an email-input field ID found via editor_getDocument, reminder flows vs. reminderSteps, the fourth invitation flow having no enable flag because request_create decides). The {{variable}} token list and field-key vs. node-id equivalence add real invocation guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Update form settings') and immediately scopes what the tool owns: form BEHAVIOR — email notifications, scheduling/limits, redirects. It names the sibling it is NOT for each adjacent concern (form_update for name/folder/cover/logo, formTheme_set for visual theme, editor_* for questions/content), so an agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use and when-not-to-use: 'Only provide fields to change' establishes partial-update semantics, and three named alternatives cover the overlapping areas (identity, theme, content). It even routes the deep-dive case to load_skill("form-settings"). The only omission is prerequisites like required permissions, which is minor.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Formstep tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Update form settings

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources