dForms

Create a form

create_form

Create a form from a full config. It is live at once at a public link: the result carries the public_url to give the user. Not idempotent: after a failure or a timeout, list_forms shows whether the form was created before a retry. Rules: steps run in order; every step has a unique key, a type and a non-empty question (message, reveal and scheduler steps may skip it); a name, email or phone is asked with the name, email or phone type, not text; only fields from the config schema in get_form_guide are accepted. Step types: name, email, phone, multiple_choice, dropdown, slider, text, textarea, url, file, message, reveal, scheduler. A minimal config: {"version":1,"title":"Talk to us","steps":[{"key":"name","type":"name","question":"What is your name?","required":true},{"key":"email","type":"email","question":"What is your work email?","required":true},{"key":"interest","type":"multiple_choice","question":"What are you interested in?","required":true,"options":[{"label":"A demo","value":"demo"},{"label":"Pricing","value":"pricing"},{"label":"Something else","value":"other"}]}]} A refused config answers VALIDATION_FAILED with every problem and its path, so you can fix them all in one retry. Unknown fields, repeated step keys or option values and references to steps that do not exist are refused, never silently changed. Without branding, dForms fills it in (the workspace brand kit, or the default look); get_form returns it, and update_form expects it back as read.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>",
      "config": "<config>"
    },
    "name": "create_form"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	The form name shown in the dashboard.
`slug`	No	The last segment of the public link. Optional: derived from the name when left out.
`config`	Yes	The whole form config, version 1: { "version": 1, "steps": [...], ... }. Its JSON Schema, the step types and worked examples are in get_form_guide.
`folder_id`	No	File the new form in this folder of the workspace.
`workspace_id`	No	The workspace this call acts in: an id from list_my_workspaces. Required for a person signed in with several workspaces and for staff of this deployment; optional with an API key or with only one workspace.

Output Schema

Name	Required	Description
`form`	Yes
`warnings`	No	What did not go exactly as sent, or what the user needs to know.
`workspace`	Yes	The workspace this call acted in, to compare with the one the user means.
`last_published_at`	Yes	When publish_form last made a draft live. Null when publish_form never ran: the form serves what it was created with, which is an empty form when is_live is false.
`previous_published_at`	Yes	When the version revert_form would bring back went live. Null when there is nothing to revert to.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 13, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare non-idempotent, non-destructive, open-world writes, and the description goes well beyond them: the form goes live immediately at a public link, the response carries a public_url meant for the user, branding is auto-filled by dForms rather than left blank, and refused configs return VALIDATION_FAILED with every problem and its path so all fixes can be made in one retry. It also states that unknown fields, duplicate keys and dangling references are refused rather than silently altered, which is exactly the kind of mutation contract an agent needs.

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: the action, the immediate-public-link consequence, then the non-idempotency warning, then the rules. The step-type enumeration and the inline minimal config are dense but justified for a nested config parameter that is otherwise only described via a pointer to another tool. Slightly heavy overall, but no sentence is empty.

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?

Output schema exists, yet the description still flags the one return field the agent must act on (public_url), which is ideal. For a nested-config write tool it covers the failure mode, the retry path, the validation contract, and the branding default — nothing essential is missing.

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 name, slug, folder_id and workspace_id are already documented; the description's value is in explaining what a valid config actually looks like — the per-step rules (unique key, type, non-empty question with message/reveal/scheduler exceptions), the allowed type list, and a complete worked example. It adds real meaning for the most complex parameter, though it partly duplicates material that get_form_guide also hosts.

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 ('Create a form from a full config') and immediately names the distinguishing outcome — a live public link with a public_url in the result. That separates it from update_form, duplicate_form and get_form without needing to open any sibling schema.

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

Usage Guidelines4/5

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

Gives clear contexts: point to get_form_guide for the accepted config schema, and use list_forms to determine whether a create actually landed after a failure or timeout before retrying. It also explains the branding round-trip with get_form/update_form. It does not explicitly state when to prefer duplicate_form over re-creating, but the creation context is unambiguous.

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

All dForms 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.

Resources

Need Help?