Skip to main content
Glama
Sign In

asksteps

by co.asksteps
OverviewDiscussionsAdmin

asksteps: create a new form in the connected account

asksteps_create_form

Creates a new form in the connected asksteps account from a structure of steps and fields. Requires "forms:write". The form is created but NOT published — publishing stays with the person who owns the account. Do not use this to rebuild a PDF: asksteps_analyze_pdf only shows you part of a document, so the copy would be silently incomplete. For a PDF, tell the user to import it in the asksteps studio, where the fields stay wired to the original document.

Input Schema

NameRequiredDescriptionDefault
specYesThe form to create: name, steps and fields.

Output Schema

NameRequiredDescriptionDefault
urlNoLink that opens the form in the asksteps studio. Give it to the user so they can look at the result. 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.
formIdNoThe id of the form. Keep it — it is how you read or change the form later.
statusYesOutcome. One of: "created", "updated", "not_connected", "not_found", "invalid_spec" (the structure was rejected — the note says exactly what to fix), "not_editable" (this form cannot be written from a spec), "unavailable", "error". Authorisation can also refuse before the tool runs: "plan_required" (the account's plan does not include agent access), "not_enabled" (the account owner has not switched agent access on), "owner_required" (only the account owner may do this), "mandate_required" (the owner has not granted a mandate for this). The note then says what the user has to do.
stepCountNoNumber of steps the form ended up with.
fieldCountNoTotal number of fields across all steps.

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.4/5.0
Behavior5/5

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

Annotations only cover safety flags (readOnly=false, openWorld=false, idempotent=false); the description goes well beyond them by disclosing the required 'forms:write' scope, the partial side effect (created but not published), and a concrete data-integrity warning about silently incomplete PDF rebuilds. These are the details an agent needs to avoid a harmful call, and they are not derivable from the structured fields.

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?

Four sentences, front-loaded with the action, then auth requirement, then publishing state, then the anti-pattern. Every sentence earns its place and the most decision-relevant facts come first.

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?

With an output schema present, return values need no explanation, and the description still covers auth, publication state, and a PDF misuse case. The one notable gap is that it never states the non-idempotent behavior (repeated calls create duplicate forms), which the annotations imply but the prose does not.

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% and the single 'spec' object is exhaustively documented down to nested field types, so the schema carries the load. The description only frames 'spec' as 'a structure of steps and fields' and adds no syntax, ordering, or validation detail beyond it — the correct baseline of 3.

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 ('Creates a new form in the connected asksteps account') plus the input shape ('from a structure of steps and fields'). It also carves out a distinct niche versus siblings such as asksteps_analyze_pdf and (implicitly) asksteps_import_pdf, so an agent can route correctly without opening schemas.

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 an explicit when-not: do not use it to rebuild a PDF, because asksteps_analyze_pdf only surfaces part of the document, and instead direct the user to the asksteps studio import. It also clarifies the follow-up state ('NOT published — publishing stays with the person who owns the account'), steering the agent away from assuming publication. It stops short of naming asksteps_publish_form or asksteps_import_pdf as the concrete alternatives.

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