What you need to know
- Read-only tools are safe to call at any time.
create_formmakes a new form on every call. If its reply is lost, look for the form withlist_formsbefore you try again.save_form_draftandpublish_formchange saved data, but repeating an identical call has no further effect.- Every tool works inside the signed-in person's organization. Form IDs come from
list_formsorcreate_form. - A failed call returns a tool error with a
codeand amessage. The codes are listed in Limits and errors. - Lists return a page of results and a
next_cursor. Pass it back ascursorto get the next page; it is null on the last page.
Tools
read_docs
Read trulyform’s docs for building forms, as Markdown. Call without a page for the list of pages; start with building-a-form. A page may name one section, such as question-types#file_upload.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
string | No | A page name, optionally with a section after #: index, connect, tools, building-a-form, form-definition, question-types, logic, calculations-and-piping, design, examples, validation, responses. A docs URL works too. Leave it out to list the pages. |
list_forms
List forms in your organization, newest IDs first. Returns draft revisions and publication status. Follow next_cursor to retrieve another page.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
string | No | The next_cursor from the previous page. Omit for the first page. |
limit |
integer | No | Maximum records to return, from 1 to 50. |
get_form
Read the complete current draft definition, revision, validation issues, and publication information. Read this before save_form_draft; a saved draft may differ from the published version.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_id |
string | Yes | Form UUID returned by list_forms or create_form. |
list_field_types
List every question kind with its settings, logic operators, answer shape and a ready-to-edit template, plus the rich-text shape and definition limits. Pass id_count to get fresh UUIDv7 identifiers for new questions, choices, rows, rules and calculations.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
id_count |
integer | No | How many fresh UUIDv7 identifiers to return in ids, from 0 to 200. |
create_form
Create an unpublished form in your organization and return its full initial draft. Optionally provide its name, then edit with save_form_draft. Each call creates a new form: inspect list_forms before retrying if a reply is lost.
Creates new data. Not safe to repeat blindly.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | No | Optional name of the new unpublished form. |
save_form_draft
Replace a form’s entire draft definition and name, preserving draft history. Read get_form first and use its draft_revision as base_revision. Send a new UUIDv7 mutation_id per edit; retries must reuse the exact same payload and ID. Existing publication stays unchanged. Re-read and reconcile on draft_conflict. read_docs explains the definition format and every error.
Changes saved data. Repeating the same call has the same effect.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_id |
string | Yes | Form UUID returned by list_forms or create_form. |
base_revision |
integer | Yes | Current draft_revision from get_form. |
mutation_id |
string | Yes | New UUIDv7 per edit. Reuse only for an identical retry. |
name |
string | Yes | Complete form name. An empty string uses Untitled form. |
definition |
object | Yes | Complete draft definition object from get_form, including unchanged properties; not a partial patch. |
publish_form
Publish the exact reviewed draft revision for new respondents. Only call when the user requests publication. Rejects stale revisions and invalid drafts; previously saved responses keep their original version. Republishing identical content creates no duplicate version. A closed form stays closed.
Changes saved data. Repeating the same call has the same effect.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_id |
string | Yes | Form UUID returned by list_forms or create_form. |
revision |
integer | Yes | Exact draft revision the user reviewed and wants to publish. |
list_responses
List response IDs, status, version, and timestamps for a form, newest IDs first. Use get_response for answers. Partial responses require the organization’s existing plan entitlement; otherwise only completed responses are returned. Follow next_cursor for another page.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_id |
string | Yes | Form UUID returned by list_forms or create_form. |
cursor |
string | No | The next_cursor from the previous page. Omit for the first page. |
limit |
integer | No | Maximum records to return, from 1 to 50. |
status |
string | No | Optional response status. Started responses need a plan that includes partial responses. |
get_response
Read one private response with resolved question labels, display answers, active-path indicators, calculations, and file names/sizes. Uses the response’s original published version. Only retrieve answers needed for the user’s request. Partial responses require the existing plan entitlement. No respondent credentials, metadata, or download links are returned.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_id |
string | Yes | Form UUID returned by list_forms or create_form. |
response_id |
string | Yes | Response UUID returned by list_responses for this form. |
form_stats
Count currently stored completed responses and, when your plan permits partial responses, started responses. Started means an existing incomplete response, not a page visit. Deleted responses are excluded. These are response counts, not unique visitors, billing usage, or conversion analytics.
Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_id |
string | Yes | Form UUID returned by list_forms or create_form. |