Agent Instructions

A single page any AI agent can read and immediately know how to use all 57 ProForms MCP tools without making mistakes.

Last updated: 2025-03-18 · Also available as raw markdown at /docs/agents.md or via the get_agent_instructions MCP tool.

Quick Start

5 steps to your first form

1. list_sites()                              → see existing sites
2. find_or_create_site({ domain: "x.com" })  → get or create a site
3. create_form({ siteId, name, fields })     → create form (starts as DRAFT)
4. publish_form({ formId, publish: true })   → make it live
5. get_embed_code({ formId })                → get the embed snippet

⚠️ Critical Rules

⚠️ Fields = FULL REPLACE

update_form with fields replaces ALL fields. To add one: get_form → append → update_form with complete array.

⚠️ Settings = DEEP MERGE

Safe to send partials like { settings: { thankYou: { message: "Thanks!" } } }.

⚠️ Theme = DEEP MERGE

Send only what you want to change. Send null to reset.

⚠️ Notifications = FULL REPLACE

update_notifications replaces ALL rules. Get existing first.

⚠️ Forms start as DRAFT

Always call publish_form after creation.

⚠️ Options need label AND value

{ label: "Display", value: "stored" } for select/radio/checkbox.

⚠️ Multi-step forms

Set settings.multiStep: true, define settings.steps, set field.step on each field.

All 57 Tools by Category

🔍 Discovery (2)

describe_schema — Get docs for features/settings (topic param)

get_agent_instructions — Get this complete guide. No params.

🌐 Sites (6)

list_sites — List all sites. search?, limit?

get_site — Get site details + forms. siteId

create_site — Create a site. name, domain?, notificationEmail?

find_or_create_site — Find by domain or create. domain, name?

update_site — Update site. siteId, name?, domain?

delete_site — Archive a site. siteId

📝 Forms (8)

list_forms — List forms. siteId?, status?, search?

get_form — Get full form details. formId

create_form — Create form with fields. siteId, name, fields[]

update_form — Update form (fields=replace, settings=merge). formId

publish_form — Publish or unpublish. formId, publish

delete_form — Archive form. formId

restore_form — Restore archived form. formId

duplicate_form — Clone a form. formId, targetSiteId?

📥 Submissions (6)

get_submissions — List with filters. formId?, status?, search?

get_submission — Get one submission. submissionId

update_submission — Mark read/starred. submissionId

update_submission_status — Set lead status. submissionId, status

bulk_submissions — Bulk action on multiple. action, ids[]

export_submissions — Export CSV/JSON. format?, formId?

🔔 Notifications (2)

get_notifications — Get form notification rules. formId

update_notifications — Replace all notification rules. formId, notifications[]

📄 Templates (2)

list_templates — Browse templates. category?

create_from_template — Create form from template. templateId, siteId

📎 Embed (1)

get_embed_code — Get embed snippets. formId

📊 Insights (1)

get_insights — Form analytics. formId, range?

🎨 Theme Presets (2)

list_theme_presets — List saved themes. No params.

create_theme_preset — Save a theme. name, theme

📁 Uploads (2)

list_uploads — List file uploads. siteId?, formId?

delete_upload — Delete an upload. id

⚙️ Settings (5)

get_profile — Get current user profile. No params.

update_profile — Update name/avatar. name?, avatar?

update_password — Change password. currentPassword, newPassword

get_email_settings — Get org email settings. No params.

update_email_settings — Update BCC settings.

🔑 API Keys (3)

list_api_keys — List all API keys. No params.

create_api_key — Create key (secret shown once). name

delete_api_key — Revoke a key. id

👥 Team (4)

list_team_members — List members + invites. No params.

invite_team_member — Send invite. email, role

remove_team_member — Remove member. userId

resend_invite — Resend invite email. userId

📈 Dashboard (2)

get_dashboard_overview — Stats summary. period

get_dashboard_chart — Submission chart data. period, siteId?

👤 Clients (Agency) (5)

list_clients — List with stats. search?, archived?

create_client — Create client. name, contactName?

update_client — Update client. clientId, name?

archive_client — Toggle archive. clientId

assign_sites_to_client — Assign sites. clientId, siteIds[]

🔗 Inbound Webhooks (4)

list_inbound_webhooks — List webhooks for site. siteId

create_inbound_webhook — Create webhook. siteId, name, source?

update_inbound_webhook — Update webhook. siteId, webhookId

delete_inbound_webhook — Delete webhook. siteId, webhookId

22 Field Types

Input

text — Single-line text

textarea — Multi-line text

email — Email with validation

phone — Phone number

number — Numeric input (min, max)

date — Date picker

time — Time picker

url — URL with validation

name — Full name

company — Company name

Choice

select — Dropdown (options[{label, value}])

multiselect — Multi-select dropdown

radio — Radio buttons (supports score, calcValue)

checkbox — Checkboxes (supports score, calcValue)

rating — Stars or numbers (ratingMax: 5|10)

scale — Numeric scale (scaleMin, scaleMax, scaleLabels)

nps — Net Promoter Score (0-10)

Special

file — File upload (accept, maxFileSize)

hidden — Hidden field (defaultValue)

address — Full address

signature — Signature pad

matrix — Grid/table (matrixRows, matrixColumns, matrixType: radio|checkbox)

Layout (no data)

heading — Section heading

paragraph — Descriptive text

divider — Visual separator

Advanced

calculated — Auto-calculated (formula: "price * quantity", numberFormat, currencySymbol)

Common Workflows

Contact form from scratch

find_or_create_site({ domain: "example.com" })
create_form({
  siteId: "...", name: "Contact Form",
  fields: [
    { type: "name", label: "Full Name", required: true },
    { type: "email", label: "Email", required: true },
    { type: "phone", label: "Phone" },
    { type: "textarea", label: "Message", required: true }
  ],
  settings: { emailNotifications: { enabled: true, recipients: ["owner@example.com"] } }
})
publish_form({ formId: "...", publish: true })
get_embed_code({ formId: "..." })

Add a field to existing form

get_form({ formId: "..." })  // Get current fields
update_form({ formId: "...", fields: [...existingFields, newField] })

Calculator form

create_form({
  siteId: "...", name: "Price Calculator",
  fields: [
    { type: "number", label: "Quantity", key: "quantity" },
    { type: "select", label: "Size", key: "size", options: [
      { label: "Small", value: "small", calcValue: 10 },
      { label: "Large", value: "large", calcValue: 25 }
    ]},
    { type: "calculated", label: "Total", key: "total",
      formula: "quantity * size", numberFormat: "currency", currencySymbol: "$" }
  ]
})

What NOT To Do

❌ Don't send partial fields arrays — you'll lose fields

❌ Don't assume a form is published after creation

❌ Don't guess field types — use the 22 types listed above

❌ Don't skip options.value — both label and value are required

❌ Don't send notifications without getting existing ones first

❌ Don't hardcode the MCP URL — use the one from your config

❌ Don't create duplicate sites — use find_or_create_site

📄 Raw Markdown

Agents can fetch the full instructions as raw markdown at https://proforms.io/docs/agents.md or call the get_agent_instructions MCP tool.