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

On this page