MCP tools

Tool reference

Tool	Scope	Saves data?	Purpose
`list_workspaces`	read	No	List workspaces allowed by both the key grant and current membership
`list_forms`	read	No	List form metadata in one workspace
`get_form_draft`	read	No	Read a draft, validation errors, warnings, and editor URL
`compile_form_dsl`	read	No	Compile Pollaris DSL into canonical JSON
`validate_form_definition`	read	No	Validate canonical JSON without saving
`generate_form_preview`	generate	No	Generate a valid, unpersisted form preview
`create_form_draft`	write	Yes	Create a new editable form draft
`save_form_draft`	write	Yes	Replace an existing draft using a revision check
`create_form`	generate/write/publish as requested	Yes	Start a durable create job; OAuth agent grant only
`get_job`	read	No	Read job progress and its final public URL
`resume_job`	write	Yes	Resume a recoverable job after renewed authorization
`publish_form`	publish	Yes	Publish exactly an inspected draft revision; OAuth agent grant only

write and generate credentials also carry read access. Workspace viewers can read; creating, saving, or generating requires an editor or owner role.

Recommended workflow

list_workspaces
  → list_forms or generate_form_preview
  → compile_form_dsl / validate_form_definition
  → ask the user to review the proposed definition
  → create_form_draft or save_form_draft
  → open editor_url and publish manually

Generation and saving are separate. generate_form_preview never persists its result.

create_form_draft and save_form_draft require an idempotency_key between 8 and 100 characters. Use a new UUID or similarly unique value for each intended operation. Retrying the same operation with the same request returns the recorded result; reusing the key with different input is rejected.

Draft revisions

Before save_form_draft, call get_form_draft and copy its form.draft_revision into expected_draft_revision. If another person or agent saves first, Pollaris rejects the stale write. Reload the draft, reconcile the changes, and retry with a new idempotency key and the new revision.

Publishing

Draft tools do not publish. They return published: false and an editor_url. An OAuth connection with pollaris.forms.publish may use create_form or publish_form; existing API keys cannot receive this scope.

create_form returns a durable job. Poll get_job until it completes, then use result.form.public_url. Reuse the same idempotency key when retrying the original request.

Useful prompts

Read-only review:

Use Pollaris to inspect the draft for "Customer onboarding". Report validation
errors and improvement ideas, but do not save anything.

Generate, review, then save:

Generate a short onboarding feedback survey for my Product workspace. Show me
the title, questions, branches, and warnings before calling any write tool.
After I approve it, save it as a new draft and give me the editor URL.

Safe update:

Load the current draft first. Add an optional final comments question without
changing existing branches. Validate it, show me the proposed change, and wait
for approval before saving with the current draft revision.

Limits that matter to clients

Workspace and form list calls return at most 100 items.
Form-list search text is limited to 200 characters.
Generation intent is 10–2,000 characters; goal is at most 500; tone is at most 100.
DSL input is at most 100,000 characters.
A form title is at most 300 characters and description at most 2,000.
Write tools accept exactly one canonical definition source where applicable and reject unexpected fields.