dForms

Edit a form (save a draft)

update_form

DestructiveIdempotent

Save a new config as an unpublished draft (and optionally rename the form). The public form does not change until publish_form. It typically follows get_form, with that updated_at as expected_updated_at: if someone saved the form since, this answers STALE instead of overwriting their work. The config replaces the whole draft, so it carries every step, not only the changed one, and branding as read (leaving it out is refused when the form has one; null removes it). Webhooks and HubSpot destinations are not changed here. discard_draft throws a draft away instead.

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": {
      "form_id": "<form_id>",
      "expected_updated_at": "<expected_updated_at>"
    },
    "name": "update_form"
  }
}

Input Schema

Name	Required	Description
`name`	No	A new form name. Applies at once, no publish needed.
`config`	No	The whole new config: usually get_form `config` with only the requested change, every other step kept. A partial steps list deletes the steps left out. Saved as an unpublished draft.
`form_id`	Yes	The form id, from list_forms or get_form.
`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.
`expected_updated_at`	Yes	The updated_at you last read for this form (get_form, or the result of your last write).

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.8/5.0

Behavior5/5

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description carries the real behavioral load: the public form is untouched until publish, the config replaces the entire draft rather than patching, branding must be echoed back or the call is refused (null removes it), and conflicting writes return STALE. That is exactly the context an agent cannot get from the annotations.

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 the action and its effect, then the sequencing, then the failure mode, then the replacement semantics. Every sentence carries information, though the branding aside ('as read... null removes it') is compressed to the point of requiring a second read.

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 a mutation tool with five parameters, a nested object, a live output schema, and strong annotations, the description covers the safety profile (unpublished draft), the correct call ordering, the stale-write guard, and the non-obvious full-replacement behavior of config. Nothing an agent needs in order to invoke it safely 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 the schema already documents each field and the baseline is 3. The description still adds meaning the schema does not: expected_updated_at is tied to the get_form read and to the STALE outcome, and the config parameter's whole-replacement semantics are reinforced. It stops short of detailing name validation or workspace_id selection, which the schema covers anyway.

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 plus the exact effect: 'Save a new config as an unpublished draft (and optionally rename the form)'. It immediately distinguishes itself from publish_form and discard_draft by naming both, so an agent can route correctly without opening a 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?

Gives the calling pattern explicitly ('typically follows get_form, with that updated_at as expected_updated_at'), states the alternative outcome (STALE instead of overwriting), and names two siblings with their roles: publish_form for going live, discard_draft for throwing a draft away. It also scopes out webhook and HubSpot destination changes.

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?