# MCP tools (/docs/mcp/tools)



## Tool reference [#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 [#recommended-workflow]

```text
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.

## Write safety [#write-safety]

### Idempotency keys [#idempotency-keys]

`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 [#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 [#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 [#useful-prompts]

Read-only review:

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

Generate, review, then save:

```text
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:

```text
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 [#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.