Skip to main content
Glama
Sign In

asksteps

by co.asksteps
OverviewDiscussionsAdmin

asksteps: turn a described form into an openable draft

asksteps_create_draft

Turns a form you have designed with the user into a draft and returns a link. Opening the link shows the form in the asksteps builder, where the user can change it and save it — no account is needed to look at it. Use this once you and the user agree on what the form should ask; it is the step that turns the conversation into something they can actually use. It does NOT write into anyone's account: a human always saves it. Give the returned url to the user verbatim. For digitising an existing PDF, do not rebuild it here — the analysis only shows you part of a large form. Point the user at the PDF import in the product instead. If the draft is rejected, the note says exactly what to fix; correct it and call again.

Input Schema

NameRequiredDescriptionDefault
specYesThe form: a name and its steps with their fields.

Output Schema

NameRequiredDescriptionDefault
urlYesThe link to open the draft in asksteps. Give this to the user verbatim — it is the whole point of the tool. Absolute when this deployment knows its public base URL, otherwise a site-relative path; never invent the domain part.
noteYesOne sentence for the user. On rejection it says exactly what to fix.
statusYesOutcome. One of: "created", "invalid_spec" (the draft was rejected — see note).
stepCountNoNumber of steps and fields the draft ended up with, so you can tell the user what they will see.
fieldCountNoTotal number of fields across all steps.
validForDaysNoHow many days the link stays valid.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / spec / properties / steps / items / properties / fields / items / properties / display
      Added value: +{
+  "description": "For \"checkbox-group\": \"list\" (options listed one below the other, the default) or \"dropdown\" (a dropdown showing the picked options as tags). Optional.",
+  "type": "string"
+}
    • addedInput schema / properties / spec / properties / steps / items / properties / fields / items / properties / selection
      Added value: +{
+  "description": "For \"checkbox-group\": \"single\" (exactly one option may be picked, e.g. yes/no, gender, a membership class) or \"multiple\" (any number, the default). Optional.",
+  "type": "string"
+}
    • changedInput schema / properties / spec / properties / steps / items / properties / fields / items / properties / type / description
      Previous value: -"Field type. One of: \"text\" (single line), \"text-area\" (multi-line), \"number\", \"date\", \"time\", \"select\" (dropdown, needs options), \"checkbox-group\" (multiple choice, needs options), \"boolean\" (single yes/no checkbox), \"file\" (upload), \"signature\" (drawn signature), \"image-upload\" (the visitor uploads one photo, e.g. a passport photo), \"contact\" (the built-in contact block: name, email, phone — use this instead of building those three by hand), \"text-block\" (explanatory text, not an input), \"table\" (a grid to fill in), \"image-choice\" (a picture to pick), \"image\", \"video\"."New value: +"Field type. One of: \"text\" (single line), \"text-area\" (multi-line), \"number\", \"date\", \"time\", \"select\" (dropdown, needs options), \"checkbox-group\" (choice group, needs options; one or several answers, see Selection), \"boolean\" (single yes/no checkbox), \"file\" (upload), \"signature\" (drawn signature), \"image-upload\" (the visitor uploads one photo, e.g. a passport photo), \"contact\" (the built-in contact block: name, email, phone — use this instead of building those three by hand), \"text-block\" (explanatory text, not an input), \"table\" (a grid to fill in), \"image-choice\" (a picture to pick), \"image\", \"video\"."
  2. Changed1 schema field changed
    • changedInput schema / properties / spec / properties / steps / items / properties / fields / items / properties / type / description
      Previous value: -"Field type. One of: \"text\" (single line), \"text-area\" (multi-line), \"number\", \"date\", \"time\", \"select\" (dropdown, needs options), \"checkbox-group\" (multiple choice, needs options), \"boolean\" (single yes/no checkbox), \"file\" (upload), \"signature\" (drawn signature), \"contact\" (the built-in contact block: name, email, phone — use this instead of building those three by hand), \"text-block\" (explanatory text, not an input), \"table\" (a grid to fill in), \"image-choice\" (a picture to pick), \"image\", \"video\"."New value: +"Field type. One of: \"text\" (single line), \"text-area\" (multi-line), \"number\", \"date\", \"time\", \"select\" (dropdown, needs options), \"checkbox-group\" (multiple choice, needs options), \"boolean\" (single yes/no checkbox), \"file\" (upload), \"signature\" (drawn signature), \"image-upload\" (the visitor uploads one photo, e.g. a passport photo), \"contact\" (the built-in contact block: name, email, phone — use this instead of building those three by hand), \"text-block\" (explanatory text, not an input), \"table\" (a grid to fill in), \"image-choice\" (a picture to pick), \"image\", \"video\"."
  3. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description meaningfully extends them: it clarifies that the tool does not write into anyone's account because a human always saves the draft, and that the returned URL must be handed over verbatim. It does not disclose the non-idempotent behavior (each call presumably yields a new draft) or any auth requirements.

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-loads the action and return value, then when-to-use, then caveats and error recovery. Nearly every sentence carries operational value. The one soft spot is the rhetorical clause "it is the step that turns the conversation into something they can actually use", which is flavour rather than instruction.

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 single-parameter tool with a large nested schema and an output schema, the description covers the remaining burden well: what is produced, that no account write occurs, how to hand off the URL, when not to use it, and how to recover from rejection. Nothing an agent needs in order to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100% across the deeply nested spec object, so the schema already carries all field-level meaning. The description adds no guidance about the spec shape beyond restating that it is "a form you have designed", which lands at the baseline for a fully documented schema.

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

Purpose4/5

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

States a specific verb and resource: it turns an agreed form spec into a draft and returns a link, and adds that opening the link shows it in the asksteps builder. That is concrete and distinguishable from read/list siblings. It does not, however, clarify how this differs from asksteps_create_form or asksteps_create_funnel, which an agent would likely weigh against it.

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 a clear trigger ("once you and the user agree on what the form should ask") plus a genuine exclusion with a redirect ("For digitising an existing PDF, do not rebuild it here... Point the user at the PDF import"). It also covers the retry loop after rejection. The gap is that it never contrasts with the sibling asksteps_create_form, so the agent must guess which creation path applies.

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

All asksteps toolsInspect
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