Formstep

Create request

request_create

Create a request: one assignment of a published form to one named recipient, with its own link, prefilled answers, expiry and optional callback. Use it when you need answers from a specific person and want to know whether they answered; for a link anyone may fill, use formShareLink_create. Call fields_list(formId) first — prefill/context/readonly take field keys. Or pass form to build the form in the same call (keys come from your blocks). Returns { id, status, url, deliveryStatus, expiresAt, form?, next }. Track with request_get, withdraw with request_cancel. See load_skill("requests").

Input Schema

Name	Required	Description
`form`	No	Build the form in this call instead of formId. The same form again reuses the first one.
`test`	No	Dry run. No invitation or reminder email whatever delivery says; the link still opens and can be completed; the callback fires with "test": true; the request is hidden from the Requests page and analytics by default and its submission counts nowhere (no quota, no exports, no integrations).
`formId`	No	Published form to send. Call fields_list(formId) first for its keys. Or pass form instead.
`context`	No	Values for HIDDEN fields, keyed by field key: { "crm_id": "A-42" }. Only hidden-field keys (fields_list context: true); use metadata for others. Recipient cannot edit them, but sees mentioned ones.
`prefill`	No	Starting answers for visible questions, keyed by field key. Shapes: string, number, "2026-03-01", "09:30", option KEY not label (see fields_list options), string[] of option keys (checkbox/ranking/picture-choice), { "row_key": "column_key" } (matrix), [{ "member_key": value }] (repeating group).
`delivery`	No	"none" (default) returns the link for you to deliver; "email" sends the invitation (needs recipient.email; Pro+, or one of Free's 10 free invitations, which go only to your own address).
`domainId`	No	Mint the link on this custom domain; formShareLink_list returns the ids as availableCustomDomains.
`language`	No	Published language tag the form opens in and the invitation is written in, e.g. "fr". Omit for the form default. The recipient can switch to any published language.
`metadata`	No	Opaque JSON echoed on request_get and in the callback.
`readonly`	No	Field keys the recipient may not edit. Each must also be in prefill.
`documents`	No	Files for this one recipient, added below the block’s authored documents. See document_create.
`expiresAt`	No	Epoch ms when the link dies. Default 30 days, max 365.
`recipient`	No	Who this is for, e.g. { "email": "ada@acme.com", "name": "Ada" }.
`reminders`	No	Idle-time offsets, e.g. ["2d","5d"] (max 5, units m/h/d, at least 1h). Omit to inherit the form schedule, [] for none. Needs recipient.email (Pro+).
`externalId`	No	Your own id; request_list filters on it.
`callbackUrl`	No	Public https endpoint POSTed on completion, expiry and cancellation, signed with X-Formstep-Signature. Private and loopback addresses are refused.
`workspaceId`	No	Workspace for form. Defaults to the token workspace.
`idempotencyKey`	No	Retry-safe key, workspace-scoped for 30 days. Same key + same body returns the original request; a different body is a conflict.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 17, 2026

changedInput schema / properties / form / properties / blocks / description

Previous value: -"1-200 blocks in form order: { type, key?, ...its editor_insert* tool's params }; load_skill(\"requests\") lists types."New value: +"1-200 blocks in form order: { type, key?, ...its editor_insert* tool's params }; load_skill(\"requests\") lists types and exceptions."

Changed11 schema fields changedOct 16, 2026

removedInput schema / properties / context / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```

removedInput schema / properties / form / properties / baseline

Removed value: -{
-  "description": "Form id to copy logo, cover, theme, settings and emails from.",
-  "type": "string"
-}

addedInput schema / properties / form / properties / cover

Added value: +{
+  "description": "{ type: \"color\", color: \"#rrggbb\" } or { type: \"image\", url, offsetY? }."
+}

addedInput schema / properties / form / properties / emoji

Added value: +{
+  "description": "One emoji, shown beside the name.",
+  "type": "string"
+}

changedInput schema / properties / form / properties / language / description

Previous value: -"UI language tag. Default: the baseline's, else \"en\"."New value: +"UI language tag. Default: \"en\"."

addedInput schema / properties / form / properties / logo

Added value: +{
+  "description": "{ type: \"icon\", name } (load_skill(\"requests\") lists names) or { type: \"image\", url }."
+}

removedInput schema / properties / form / properties / settings / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```

changedInput schema / properties / form / properties / theme / description

Previous value: -"{ light?, dark? }: preset id or whole formTheme_set theme per mode; wins over the baseline's."New value: +"{ light?, dark? }: preset id or whole formTheme_set theme per mode."

addedInput schema / properties / form / properties / translations

Added value: +{
+  "description": "{ \"<language>\": { \"<text as written>\": \"<translated>\" } }, every string of the form; see load_skill(\"requests\")."
+}

removedInput schema / properties / metadata / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
removedInput schema / properties / prefill / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```

Changed4 schema fields changedOct 15, 2026

addedInput schema / properties / form

Added value: +{
+  "additionalProperties": false,
+  "description": "Build the form in this call instead of formId. The same form again reuses the first one.",
+  "properties": {
+    "baseline": {
+      "description": "Form id to copy logo, cover, theme, settings and emails from.",
+      "type": "string"
+    },
+    "blocks": {
+      "description": "1-200 blocks in form order: { type, key?, ...its editor_insert* tool's params }; load_skill(\"requests\") lists types.",
+      "items": {},
+      "type": "array"
+    },
+    "language": {
+      "description": "UI language tag. Default: the baseline's, else \"en\".",
+      "type": "string"
+    },
+    "name": {
+      "description": "Dashboard name, max 100 chars. Same for every recipient: personalise through prefill and context.",
+      "type": "string"
+    },
+    "settings": {
+      "additionalProperties": {},
+      "description": "formSettings_update's settings, fields by key; see load_skill(\"requests\").",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "theme": {
+      "description": "{ light?, dark? }: preset id or whole formTheme_set theme per mode; wins over the baseline's."
+    }
+  },
+  "required": [
+    "name",
+    "blocks"
+  ],
+  "type": "object"
+}

changedInput schema / properties / formId / description

Previous value: -"Published form to send. Call fields_list(formId) first for its keys."New value: +"Published form to send. Call fields_list(formId) first for its keys. Or pass form instead."

addedInput schema / properties / workspaceId

Added value: +{
+  "description": "Workspace for form. Defaults to the token workspace.",
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "formId"
-]
```

Changed2 schema fields changedOct 14, 2026

changedInput schema / properties / delivery / description

Previous value: -"\"none\" (default) returns the link for you to deliver; \"email\" sends the invitation (needs recipient.email; Pro+, or one of Free's 10 free invitations)."New value: +"\"none\" (default) returns the link for you to deliver; \"email\" sends the invitation (needs recipient.email; Pro+, or one of Free's 10 free invitations, which go only to your own address)."

changedInput schema / properties / reminders / description

Previous value: -"Idle-time offsets, e.g. [\"2d\",\"5d\"] (max 5, units m/h/d). Omit to inherit the form schedule, [] for none. Needs recipient.email (Pro+)."New value: +"Idle-time offsets, e.g. [\"2d\",\"5d\"] (max 5, units m/h/d, at least 1h). Omit to inherit the form schedule, [] for none. Needs recipient.email (Pro+)."

First observedOct 8, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context beyond that: the cross-parameter constraint that prefill/context/readonly are keyed by field keys, the return shape, and the inline 'form' path whose keys come from one's own blocks. Much of the deepest behavior (test dry-run effects, quota-limited email delivery, callback signing) lives in the schema rather than the description, so it stops short of a 5.

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

Conciseness5/5

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

Five sentences, each earning its place and ordered by importance: what it is, when to use it vs the alternative, the prerequisite, the return shape, then lifecycle tools. The defining scope is front-loaded before the routing guidance.

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

Completeness5/5

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

For an 18-parameter tool with nested objects and no output schema, the description covers the missing return contract ('Returns { id, status, url, deliveryStatus, expiresAt, form?, next }'), the prerequisite, the sibling alternative, and follow-up lifecycle tools. An agent has everything needed to select and invoke it correctly.

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 coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics the schema does not: that prefill/context/readonly all take field keys obtained via fields_list(formId), and that the inline 'form' alternative derives its keys from your own blocks. That relationship is genuinely useful, though most individual field meaning is still schema-carried.

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?

The opening sentence gives a precise verb, resource and scope: 'one assignment of a published form to one named recipient, with its own link, prefilled answers, expiry and optional callback.' It explicitly distinguishes itself from formShareLink_create by contrasting the named-recipient/tracked-answer case against the open-link case, so an agent can route without opening either 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?

It states when to use it ('when you need answers from a specific person and want to know whether they answered'), names the alternative and its selecting condition ('for a link anyone may fill, use formShareLink_create'), and gives a prerequisite ('Call fields_list(formId) first'). It also names the follow-up tools (request_get, request_cancel) and a skill pointer, leaving nothing to inference.

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.

Create request

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources