Agent guide

Everything an AI agent needs to create, deploy, and manage Motivation Form forms and surveys via MCP or CLI — canonical syntax, copy-paste templates, and media embedding patterns.

This guide is written for AI agents. If you are a developer looking to set up the MCP server or CLI, start with MCP — Claude Code or CLI reference.

Mental model

One form = one .md file. The YAML frontmatter is the schema. The markdown body is the instructions shown above the fields. Deploy with one command or one MCP tool call. Responses arrive by email and are readable via the API.

You do not need a browser. Every operation — create, deploy, list forms, read responses — is available from the CLI or MCP tools.

Canonical `.md` structure

---
title: string                  # Required — display title shown to respondents
slug: string                   # Required — URL segment: form.gold/@{handler}/{slug}
type: form | survey            # Optional — default: form
branding:
  logo: string                 # URL to logo image (optional)
  primary_color: string        # Hex color (optional, default: #0f172a)
notifications:
  email:
    - string                   # Recipient addresses (at least one recommended)
  subject: string              # Supports {form_title}, {field:<id>}, {date}
  strategy:
    immediate_count: number    # First N get per-submission email (default: 10)
    target: number             # Enables % milestones (optional)
    milestones:
      percentage: [number]
      absolute: [number]
humanness: boolean             # Turnstile anti-bot (default: true)
settings:
  progress_bar: boolean        # Show progress bar (default: false)
  randomize_options: boolean   # Shuffle option order (default: false)
fields:
  - id: string                 # snake_case, unique within the form
    type: string               # see field type list below
    label: string
    required: boolean
    # ... type-specific properties
---

Markdown body — instructions above the fields.

All field types at a glance

Core types (always available)

Type	Response value	Best for
`text`	`string`	Name, company, short answer
`email`	`string`	Email address with format validation
`textarea`	`string`	Long-form answer, description
`number`	`number`	Budget, quantity, year
`radio`	`string`	Single choice from a list
`checkbox`	`string[]`	Multi-select
`select`	`string`	Single choice as a dropdown
`date`	`string` (ISO 8601)	Deadlines, dates of birth
`image`	`string` (Storage URL)	Logo, photo, screenshot upload
`file`	`string` (Storage URL)	PDF, document upload

Survey / extended types

Type	Response value	Best for
`rating`	`number` (1–max)	Star ratings, satisfaction
`scale`	`number`	Likert scale, agreement level
`nps`	`number` (0–10)	Net Promoter Score
`yes_no`	`"yes"` \| `"no"`	Binary decision, consent
`ranking`	`string[]` (ordered)	Priority ordering
`matrix`	`{ row_id: column }`	Multi-row ratings
`statement`	(none — display only)	Section headers, consent text

Templates

Copy these as starting points. Replace placeholder values.

Intake form

---
title: Campaign Brief
slug: campaign-brief
notifications:
  email:
    - owner@example.com
  subject: "New brief: {field:company_name}"
fields:
  - id: company_name
    type: text
    label: Company name
    required: true
  - id: contact_email
    type: email
    label: Work email
    required: true
  - id: campaign_type
    type: radio
    label: Campaign type
    required: true
    options:
      - Brand awareness
      - Product launch
      - Event promotion
      - Performance marketing
  - id: budget_usd
    type: number
    label: Budget (USD)
    placeholder: "50000"
  - id: brief
    type: textarea
    label: Campaign brief
    required: true
    placeholder: Describe your goals, target audience, and KPIs.
  - id: brief_pdf
    type: file
    label: Attach brief (PDF, optional)
    accept:
      - application/pdf
    max_mb: 20
---

Fill out this brief to kick off your campaign. We'll respond within 24 hours.

NPS survey

---
type: survey
title: NPS Survey
slug: nps-q2
settings:
  progress_bar: true
notifications:
  email:
    - team@example.com
fields:
  - id: nps
    type: nps
    label: How likely are you to recommend us to a colleague?
    low_label: Not at all likely
    high_label: Extremely likely
    required: true
  - id: reason
    type: textarea
    label: What's the main reason for your score?
    show_if:
      field: nps
      op: lte
      value: 8
  - id: highlight
    type: textarea
    label: What do you value most about the product?
    show_if:
      field: nps
      op: gte
      value: 9
---

Takes 2 minutes. Your responses are anonymous.

Visual A/B test

---
title: Design Preference Study
slug: design-ab
notifications:
  email:
    - designer@example.com
settings:
  randomize_options: true
fields:
  - id: preferred_design
    type: radio
    label: Which design direction resonates most with you?
    required: true
    options:
      - label: Minimal
        media:
          type: image
          url: https://cdn.example.com/design-a.png
      - label: Bold
        media:
          type: image
          url: https://cdn.example.com/design-b.png
      - label: Playful
        media:
          type: image
          url: https://cdn.example.com/design-c.png
  - id: reasoning
    type: textarea
    label: Why did you choose that direction?
---

3D model comparison

---
title: Product Concept Feedback
slug: product-3d
fields:
  - id: preferred_shape
    type: radio
    label: Which product shape do you prefer?
    required: true
    media:
      type: model3d
      url: https://cdn.example.com/concept-a.glb
      alt: Drag to rotate. Both concepts are shown in the options below.
    options:
      - Concept A — Rounded
      - Concept B — Angular
  - id: comfort_rating
    type: rating
    label: How comfortable does the chosen shape look?
    max: 5
---

Conditional logic quick reference

show_if:
  field: <field_id>
  op: eq | neq | gt | lt | gte | lte | includes | excludes
  value: <value>

Op	Use with	Example
`eq`	Any type	Show follow-up when `plan` equals `"enterprise"`
`neq`	Any type	Skip question when `country` is not `"US"`
`gt` / `lt` / `gte` / `lte`	`number`, `rating`, `scale`, `nps`	Show detractor question when NPS ≤ 6
`includes`	`checkbox`, `ranking`	Show detail field when `interests` includes `"Pricing"`
`excludes`	`checkbox`, `ranking`	Skip field when `platforms` excludes `"iOS"`

Hidden fields are excluded from the submitted response payload — you will never see a key for a field the respondent never saw.

Media embedding quick reference

media:
  type: image | youtube | video | model3d
  url: <url>
  alt: <optional text>

Type	`url` format
`image`	Any public image URL
`youtube`	Full YouTube URL (`https://youtu.be/…`) or 11-char video ID
`video`	Direct `.mp4` or `.webm` URL
`model3d`	`.glb` or `.gltf` URL

Attach media: directly to a field to show it above the input. Attach media: to an individual option (within radio or checkbox) to render a visual card grid.

Deploy workflow

Via MCP (recommended for agents)

deploy_form("path/to/form.md")

Returns { url, slug, form_id }.

Via CLI

mf deploy path/to/form.md
# → https://form.gold/@handle/slug

Verify deployment

mf list                         # shows all deployed forms with status

Reading responses

Via MCP

get_responses("slug", { limit: 50 })

Via CLI

mf submissions my-form           # prints JSON to stdout
mf submissions my-form --csv     # CSV format

Via REST API

GET /api/forms/{slug}/submissions
Authorization: Bearer mf_sk_...

Response shape:

{
  "responses": [
    {
      "id": "uuid",
      "submitted_at": "2026-05-01T12:00:00Z",
      "payload": {
        "company_name": "Acme Corp",
        "campaign_type": "Brand awareness",
        "nps": 9,
        "ease_of_use": 4
      }
    }
  ]
}

For ranking, the payload value is an ordered array:

"priority_order": ["Speed", "Price", "Reliability", "Customer support"]

For matrix, the payload value is a { row_id: column } map:

"satisfaction_grid": {
  "onboarding": "Satisfied",
  "performance": "Very satisfied",
  "docs": "Neutral"
}

Rules the agent must follow

slug must be URL-safe — lowercase letters, digits, hyphens only. No spaces, no underscores, no special characters. Example: campaign-brief-q2-2026.
id must be unique within the form — snake_case, letters and underscores only. Example: contact_email, budget_usd.
show_if.field must reference an id that appears earlier in the fields array — forward references are not evaluated.
media.url for youtube can be the full URL — the renderer extracts the video ID automatically. You do not need to pre-parse it.
type: survey + step: are mutually exclusive — survey mode is always one field at a time; step: groupings are ignored.
matrix row id values must be unique within the field — used as keys in the response payload.
ranking options must be a flat list of strings — no media: on ranking options.
statement fields are display-only — do not use them for consent capture that needs to be recorded; use yes_no instead.

Common mistakes

Mistake	Fix
Using `show_if` to reference a field that comes after the trigger field	Reorder fields — the trigger must appear earlier in the array
Setting `type: survey` and `step:` on the same form	Remove `step:` — survey mode ignores it
Using a `youtube` URL with `&list=...` or `&t=...` parameters	The renderer strips query parameters and extracts just the video ID
Using a `ranking` field with `required: false`	`ranking` is always considered answered once the respondent loads the page (items are pre-ordered); set `required: true` to ensure they consciously reorder
Generating a `slug` with spaces or uppercase	Slugify: lowercase, replace spaces with hyphens, strip special characters
Referencing a `media.url` that requires authentication	All media sources must be publicly accessible URLs — no signed or cookie-authenticated assets

Survey design guidance

This section teaches agents how to design surveys that collect useful signal rather than noise. Apply these principles whenever a user asks you to create a survey — especially when they have not specified the questions themselves.

Universal principles

Keep it short. 5–8 questions is the sweet spot for completion rate. Every question you add reduces the probability of getting to the next one. If you need more than 10 fields, split into pages with one topic per page.

One question, one thing. Never combine two ideas in one question: "How easy was setup, and are you satisfied with the docs?" is two questions. Split them.

Avoid leading questions. Bad: "How much did you enjoy using the product?" Good: "How would you describe your overall experience?" The first primes the respondent; the second does not.

Match field type to signal you need:

Signal needed	Field type
Ranked preference	`ranking`
Satisfaction, effort, or agreement on a scale	`scale` or `rating`
Recommendation likelihood	`nps`
Quick yes/no	`yes_no`
One of several options	`radio`
Multiple that apply	`checkbox`
Open-ended explanation	`textarea`
Comparison across dimensions	`matrix`

Always offer an optional follow-up contact field. Include a required: false email or text field at the end so interested respondents can continue the conversation. This turns aggregate signal into individual leads.

Engineering-context surveys

Use these questions when the audience is developers, engineers, or technical operators. Frame everything around workflow, not feelings.

Themes to cover:

Debugging and error-surfacing workflow
Perceived usefulness of specific tools or features
Repo and PR review pain points
Adoption blockers and time-to-value friction
Integration pain points (auth, SDKs, docs gaps)

Recommended structure:

---
title: Developer Experience Survey — {Product Name}
slug: dx-survey-{product}-{quarter}
type: survey
notifications:
  email:
    - team@example.com
fields:
  - id: role
    type: radio
    label: What best describes your role?
    required: true
    options:
      - Individual contributor (IC)
      - Tech lead / Staff engineer
      - Engineering manager
      - DevOps / Platform

  - id: usage_frequency
    type: radio
    label: How often do you use {feature or product}?
    required: true
    options:
      - Daily
      - Several times a week
      - A few times a month
      - Rarely

  - id: top_friction
    type: ranking
    label: Rank these pain points from most to least frustrating.
    required: true
    options:
      - Setup / onboarding
      - Debugging / error messages
      - Documentation gaps
      - API or SDK ergonomics
      - Performance

  - id: biggest_blocker
    type: textarea
    label: What is the single thing that slows you down the most?
    required: true
    placeholder: Describe a specific situation if you can.

  - id: missing_feature
    type: textarea
    label: What is one capability you wish existed?
    required: false

  - id: nps
    type: nps
    label: How likely are you to recommend this to a colleague?
    required: true

  - id: follow_up_email
    type: email
    label: Can we follow up with you? (optional)
    required: false
    placeholder: your@email.com
---

We are improving the developer experience and want your honest input. This takes about 3 minutes.

Design notes for engineering surveys:

Use ranking for pain points instead of checkbox — forced ordering reveals priority that checkboxes hide.
Keep textarea questions specific ("a specific situation") — open prompts like "any feedback?" yield noise.
Put NPS last — it closes the survey on a single number which is easier to answer than an open question.
Avoid matrix for self-reported proficiency (respondents anchor to middle values); use explicit radio instead.

Marketing-context surveys

Use these questions when the audience is buyers, prospects, or early users. Frame everything around goals, outcomes, and decision-making — not product features.

Themes to cover:

Persona and job context (Jobs-to-be-Done)
Value proposition fit — which benefits actually matter
Feature priority from the customer's perspective
Purchase and adoption intent
Competitive alternatives they considered

Recommended structure:

---
title: Early Adopter Survey — {Product Name}
slug: early-adopter-survey-{product}
type: survey
notifications:
  email:
    - founders@example.com
fields:
  - id: job_title
    type: text
    label: What is your job title?
    required: true
    placeholder: e.g. Head of Growth, Founder, Product Manager

  - id: company_size
    type: radio
    label: How large is your team?
    required: true
    options:
      - Solo / freelance
      - 2–10
      - 11–50
      - 51–200
      - 200+

  - id: primary_goal
    type: radio
    label: What are you primarily trying to accomplish with {product}?
    required: true
    options:
      - Save time on a recurring task
      - Replace a tool I currently pay for
      - Enable something I couldn't do before
      - Evaluate whether this fits my workflow

  - id: most_important_benefit
    type: ranking
    label: Rank these benefits from most to least important to you.
    required: true
    options:
      - Speed / time saved
      - Cost reduction
      - Quality of output
      - Ease of setup
      - Reliability

  - id: current_alternative
    type: text
    label: What do you use today to solve this problem?
    required: false
    placeholder: Tool name, spreadsheet, manual process, etc.

  - id: decision_factor
    type: textarea
    label: What would make you confident enough to use this in production?
    required: true

  - id: willingness_to_pay
    type: radio
    label: If this solved the problem well, which price range feels fair?
    required: false
    options:
      - Free only
      - Under $20/month
      - $20–$99/month
      - $100–$499/month
      - $500+/month or usage-based

  - id: follow_up_email
    type: email
    label: Can we follow up with you? (optional)
    required: false
    placeholder: your@email.com
---

We are building {product} and want to understand your needs. Your answers shape what we prioritize next. Takes about 3 minutes.

Design notes for marketing surveys:

Lead with role and context — it frames all subsequent answers and lets you segment results.
Use ranking for value props instead of "select all that apply" — knowing what ranks first is far more actionable than knowing what checked a box.
Willingness-to-pay questions should be optional and come late — they're uncomfortable and will drive drop-off if placed early.
Never ask "Would you pay for X?" (hypothetical intent is unreliable). Ask about the decision factors that would change their mind.
Avoid double-barrelled options like "Fast and affordable" — pick one dimension per option.

Reference template: Crosscheck user survey

This is the canonical reference for a user research survey sent to an existing user base. It covers persona, Jobs-to-be-Done, value fit, and qualitative signal in under 8 questions.

---
title: Crosscheck User Survey
slug: crosscheck-user-survey
type: survey
notifications:
  email:
    - research@crosscheck.ai
  subject: "New survey response — {date}"
fields:
  - id: role
    type: radio
    label: What is your primary role?
    required: true
    options:
      - Founder / CEO
      - Product manager
      - Engineer / Developer
      - Designer
      - Marketing / Growth
      - Other

  - id: team_size
    type: radio
    label: How large is your team?
    required: true
    options:
      - Solo
      - 2–10
      - 11–50
      - 51–200
      - 200+

  - id: primary_use_case
    type: textarea
    label: What problem were you trying to solve when you found Crosscheck?
    required: true
    placeholder: Describe the situation in your own words.

  - id: most_valuable
    type: textarea
    label: What has been most valuable to you so far?
    required: true

  - id: biggest_frustration
    type: textarea
    label: What is the one thing that frustrates you most, or that you wish worked differently?
    required: true

  - id: alternatives
    type: checkbox
    label: What else did you consider or try before Crosscheck?
    required: false
    options:
      - Manual testing / spreadsheets
      - A competitor tool (which one?)
      - Built something in-house
      - Nothing — this was a new workflow

  - id: nps
    type: nps
    label: How likely are you to recommend Crosscheck to a colleague?
    required: true

  - id: follow_up
    type: email
    label: Can we reach out to hear more? (optional — we read every response)
    required: false
    placeholder: your@email.com
---

We're doing user research to understand what's working and what to build next. This takes about 4 minutes and your input directly shapes our roadmap.

**All responses are confidential.**

On this page