Skip to content
Elicitly

elicit_form

Fire a form elicitation with your own JSON schema; returns the raw {action, content}.

When to use

Section titled “When to use”

You need several typed answers — text, numbers, toggles, selections — from the person at the host, in one dialog, right now. For a single yes/no, elicit_confirm is simpler; for a decision that must survive the session or reach another reviewer, use the Pro approval tools — see Choosing a tool.

Input

Section titled “Input”
Parameter Type Required Description
message string yes The prompt shown above the form.
requestedSchema object yes A JSON Schema in the MCP elicitation subset: a flat object with primitive properties only.
timeoutSeconds number no Default 300, clamped 60–3600 — how long the request waits for an answer. The default 5 minutes is deliberately more generous than a typical tool call — a form takes longer to read and fill out than a machine round-trip — but a form with several fields (like the rollout example below) may still need more; raise it accordingly. It’s capped at 1 hour rather than allowed to run indefinitely, since the request stays open on the live connection the whole time. 
{
  "message": "Enter release details",
  "requestedSchema": {
    "type": "object",
    "properties": {
      "version": { "type": "string" },
      "prerelease": { "type": "boolean" }
    },
    "required": ["version"]
  }
}

Output

Section titled “Output”

On accept, content holds the collected fields:

{ "action": "accept", "content": { "version": "1.2.0", "prerelease": false } }

On decline, cancel, or error, content is null:

{ "action": "decline", "content": null }

(action is "accept", "decline", "cancel", or "error".)

Every field type at once

Section titled “Every field type at once”

A single form can collect every kind of input the spec supports — free text, numbers, toggles, and single- or multi-choice selections. For example, asking the user to configure a staged rollout:

{
  "message": "Configure the v2.1.0 rollout",
  "requestedSchema": {
    "type": "object",
    "properties": {
      "releaseName": {
        "type": "string",
        "title": "Release name",
        "description": "Shown in the changelog",
        "maxLength": 50
      },
      "rolloutPercent": {
        "type": "integer",
        "title": "Initial rollout %",
        "minimum": 0,
        "maximum": 100,
        "default": 10
      },
      "notifyCustomers": {
        "type": "boolean",
        "title": "Email customers",
        "default": false
      },
      "channel": {
        "type": "string",
        "title": "Channel",
        "oneOf": [
          { "const": "stable", "title": "Stable" },
          { "const": "beta", "title": "Beta" },
          { "const": "canary", "title": "Canary" }
        ],
        "default": "beta"
      },
      "regions": {
        "type": "array",
        "title": "Regions",
        "minItems": 1,
        "items": { "type": "string", "enum": ["us-east", "eu-west", "ap-south"] },
        "default": ["us-east"]
      }
    },
    "required": ["releaseName", "channel", "regions"]
  }
}

On accept, content carries one value per property:

{
  "action": "accept",
  "content": {
    "releaseName": "Halley",
    "rolloutPercent": 25,
    "notifyCustomers": true,
    "channel": "beta",
    "regions": ["us-east", "eu-west"]
  }
}

Notes on the field types:

  • String (releaseName) — supports minLength/maxLength/pattern and the formats email, uri, date, date-time.
  • Number (rolloutPercent) — "integer" or "number", with minimum/maximum.
  • Boolean (notifyCustomers) — renders as a checkbox/toggle.
  • Single-select enum (channel) — shown here with titled options (oneOf + const/title); a plain "enum": [...] array works when the values are their own labels.
  • Multi-select enum (regions) — an array with minItems/maxItems; shown here with a plain enum, and items.anyOf + const/title gives the titled flavor.
  • All types accept a default, which capable hosts pre-fill.

How faithfully each field renders varies by host — run elicit_doctor with probeElicitation: true in yours, and check the Support Matrix.

Capturing a lead

Section titled “Capturing a lead”

Forms collect business data as readily as engineering decisions. A sales skill logging a new lead:

{
  "message": "New lead from the demo call — capture the details",
  "requestedSchema": {
    "type": "object",
    "properties": {
      "fullName": { "type": "string", "title": "Full name" },
      "email": { "type": "string", "title": "Work email", "format": "email" },
      "company": { "type": "string", "title": "Company" },
      "teamSize": { "type": "integer", "title": "Team size", "minimum": 1 },
      "subscribe": {
        "type": "boolean",
        "title": "Subscribe to product updates",
        "default": true
      },
      "interest": {
        "type": "string",
        "title": "Primarily interested in",
        "enum": ["Free", "Pro", "Enterprise"]
      }
    },
    "required": ["fullName", "email", "company"]
  }
}
{
  "action": "accept",
  "content": {
    "fullName": "John Doe",
    "email": "john.doe@acme.com",
    "company": "Acme",
    "teamSize": 25,
    "subscribe": true,
    "interest": "Pro"
  }
}

Note "format": "email" — capable hosts validate the field before submitting — and the plain untitled enum, which fits when the values are their own labels.

Section titled “Related”