# MCP tools > Every tool the trulyform MCP server offers, with its parameters, what it returns, and whether it changes anything in your forms. ## What you need to know - Read-only tools are safe to call at any time. - `create_form` makes a new form on every call. If its reply is lost, look for the form with `list_forms` before you try again. - `save_form_draft` and `publish_form` change 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_forms` or `create_form`. - A failed call returns a tool error with a `code` and a `message`. The codes are listed in [Limits and errors](https://trulyform.com/docs/validation.md#error-codes). - Lists return a page of results and a `next_cursor`. Pass it back as `cursor` to 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. | --- Previous: [Connect](https://trulyform.com/docs/connect.md) · Next: [Building a form](https://trulyform.com/docs/building-a-form.md) All pages: https://trulyform.com/llms.txt. Connected over MCP? Call read_docs with a page name instead.