Browse Formstack forms, submissions and webhooks, search responses, and create submissions.
Scored across 20 tools
Each tool targets a distinct resource+action, and the descriptions explicitly differentiate the few near-neighbors (per-form list vs account-wide search_submissions; confirmation emails to submitters vs notification emails to the team; count vs list submissions). An agent can reliably pick the right tool without guessing.
Every tool follows the same formstack_<verb>_<noun> snake_case pattern with a small, stable verb set (count, create, get, list, search, update). No camelCase or stylistic deviations, making the surface highly predictable.
20 tools is on the heavier side, but the domain legitimately spans forms, folders, submissions, partial submissions, webhooks, and several email/action sub-resources, and no tool is redundant. It stops just short of feeling bloated rather than padded.
Read/write coverage for forms and submissions is strong (get/list/update/create/search/count), but lifecycle ops are missing: no delete for forms, folders, or submissions, and webhooks only have create+list with no update/delete. These are workable gaps that limit full lifecycle management.
Count a form's submissions, with a per-day breakdown over a lookback window of up to 7 days. Formstack: GET /forms/{formId}/submissions/count.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. | |
| start_date | No | Date to count from, e.g. 2026-09-01. | |
| lookback_period | No | How many days to count backwards (maximum 7). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry the safety profile (readOnlyHint=true), so the bar is lower. The description usefully discloses the 7-day maximum lookback and that results come as a per-day breakdown, but says nothing about permissions/scopes or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence that front-loads the verb, resource, and output shape, followed by a short endpoint reference. No filler, though the raw endpoint string is marginally redundant with the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only aggregate tool with a fully documented schema and no output schema, the description covers operation, scope limit, and return shape (per-day breakdown). Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents form_id, start_date, and lookback_period including the 7-day maximum. The description only restates the lookback constraint, adding no new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Count a form's submissions') and adds scope detail: a per-day breakdown over a lookback window capped at 7 days. This distinguishes it in spirit from list_form_submissions and search_submissions, though it never names the alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the aggregate nature of 'count' versus sibling listing tools. There is no explicit statement of when to prefer this over formstack_list_form_submissions or formstack_search_submissions, nor any stated prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a folder for organising forms, at the root or inside a parent folder. Formstack: POST /folders.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Folder name. | |
| parent | No | Parent folder ID (omit for root level). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are thin (only destructiveHint=true), so the description carries most of the load. It maps the operation to the API endpoint ("Formstack: POST /folders") and explains root vs nested placement, but says nothing about auth needs, duplicate-name behavior, or side effects of folder creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence plus a short endpoint tag; the core action is front-loaded and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter creation tool with no output schema and full schema coverage, the description covers what an agent needs to call it correctly. Minor gaps remain around failure/duplicate handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents both `name` and `parent` (including "omit for root level"). The description merely restates the root/parent distinction, so baseline 3 applies with no added syntax or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("Create a folder for organising forms") and adds the scope of where it can be created. It is implicitly distinguishable from siblings like formstack_get_folder and formstack_list_folders, though it never names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The mention of "at the root or inside a parent folder" gives useful placement context, but there is no explicit when-to-use versus alternatives and no prerequisites or permission requirements stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a link to a live form with some fields already filled in — e.g. to send a customer a form with their name and account number pre-entered. Formstack stores the prefill and returns prefilledUrl. Formstack: POST /forms/{formId}/prefill.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Field values to prefill. | |
| form_id | Yes | The form ID. | |
| incomplete_password | No | Optional password protecting the prefilled entry. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true already declared, the description adds that Formstack persists the prefill server-side and names the return field 'prefilledUrl' (valuable given no output schema). However, it frames the operation as benign link generation and never explains why it is flagged destructive, nor mentions permission/password implications, leaving a real gap against the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight, front-loaded sentences covering what it does, an example, and the return field, followed by a short endpoint reference. No filler, though the raw 'POST /forms/{formId}/prefill' line is marginally redundant for an agent-level caller.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description usefully names the returned 'prefilledUrl' plus the fact that the prefill is stored. Combined with 100% schema coverage on all three parameters, an agent has enough to invoke it correctly; only the destructive/persistence semantics are under-explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so form_id, fields, and incomplete_password are fully documented in the schema itself, including per-field-type value shapes. The description adds no parameter-level meaning beyond the example values, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Generate a link to a live form with some fields already filled in') and clarifies scope versus other create tools by specifying it produces a URL rather than submitting data. It does not name a sibling to contrast against, but the resource is distinctive enough to distinguish it from create_submission or get_form.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The customer example ('send a customer a form with their name and account number pre-entered') implies the use case but never states when to choose this over alternatives like formstack_create_submission or when-not to use it. The pointer to formstack_list_form_fields for field IDs lives in the schema, not the description, so the description itself gives only implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit an entry to a form on someone's behalf. This is a real submission: it counts toward the form and can fire its notification emails, webhooks and integrations. Formstack: POST /forms/{formId}/submissions.
| Name | Required | Description | Default |
|---|---|---|---|
| read | No | Mark the submission as read on creation. | |
| fields | Yes | Field values to submit. | |
| form_id | Yes | The form ID. | |
| user_agent | No | Submitter's browser user agent to record. | |
| remote_addr | No | Submitter's IP address to record. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations supply only destructiveHint=true, so the description carries most of the burden and delivers the key trait: the submission is real, counts toward the form, and fires notification emails, webhooks and integrations. It omits auth/permission requirements and whether the write is reversible, but the side-effect disclosure is exactly the context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the action and its consequence, followed by the underlying endpoint reference. No filler; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should cover what comes back, and it does not — an agent cannot tell whether the created submission ID is returned, which matters for follow-up calls like formstack_get_submission. The write semantics are well covered, but the return-value gap leaves this only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters, including the field-value shapes and the pointer to formstack_list_form_fields. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Submit an entry to a form") and immediately scopes it as "on someone's behalf," which distinguishes a real submission from the sibling create_prefill_url that only generates a link. An agent can tell what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the description makes clear this is a committing write, which helps an agent decide between it and non-committing options, but it never names an alternative (e.g. prefill URL, update_submission) or states prerequisites. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a webhook that POSTs each new submission of a form to your URL. Formstack: POST /forms/{formId}/webhooks.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | HTTPS URL that receives the submission data. | |
| name | No | Webhook name. | |
| form_id | Yes | The form ID. | |
| hmac_secret | No | Secret used to HMAC-sign each payload. | |
| content_type | No | Payload encoding. | |
| error_emails | No | Comma-separated emails to notify on delivery failure. | |
| file_transfer_type | No | How uploaded files are delivered in the payload. | |
| include_field_type | No | Include each field's type in the payload. | |
| standardize_values | No | Standardize field values for consistency. | |
| post_data_field_keys | No | How fields are keyed in the payload. | |
| include_subfield_names | No | Include subfield names in the payload. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations supply destructiveHint=true, so the safety profile is partly carried by structured data. The description adds functional behavior (each new submission is POSTed to the URL), but does not disclose auth/permission requirements or what happens to existing integrations; with annotations present this earns a moderate score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, behavior front-loaded with the API endpoint appended as supporting detail. No filler, though the endpoint reference is marginal for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool with no output schema, the description is thin on prerequisites, success behavior, and delivery-failure semantics, but the fully documented schema offsets much of this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 11 parameters including the enum options are already documented in the schema. The description only reiterates form and URL conceptually and adds no extra parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (add/create a webhook) and describes its function: POSTs each new submission of a form to your URL. It is distinguishable from formstack_list_webhooks by the 'Add' action, though it never names a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as formstack_list_webhooks for inspecting existing hooks. Usage is only implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a folder with its parent, permissions and direct subfolders. Formstack: GET /folders/{folderId}.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes | The folder ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description earns credit by disclosing the response shape (parent, permissions, direct subfolders), which is valuable since no output schema exists, though it omits error behavior and depth/recursion semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the payload description. The trailing 'Formstack: GET /folders/{folderId}' line is mild filler but does give an endpoint mapping.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers what the call returns, which is the main information gap. It stops short of explaining nested subfolder depth or failure modes, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single folder_id parameter, so the schema already documents it fully. The description repeats folderId only via the REST path template and adds no syntax, range, or lookup guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch) and resource (a folder) and goes further by naming what comes back: parent, permissions and direct subfolders. This distinguishes it from formstack_list_folders implicitly, but never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: a single-folder-by-ID retrieval, which naturally contrasts with the list tool. There is no explicit when-to-use statement, no mention of the list alternative, and no note on what happens if the folder is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a form's details — name, URL, submission counts, settings — optionally with its full field list. Formstack: GET /forms/{formId}.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. | |
| with_fields | No | Include the form's fields in the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations supply readOnlyHint=true, so the description needn't restate safety. It adds genuine behavioral value by disclosing the return payload contents and noting that fields are only included on request — important because no output schema exists. No auth or rate-limit context, so it stops short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact clauses, front-loaded with the resource and outcome, followed by the endpoint. No filler and nothing an agent must read past to reach the key meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with exhaustive schema coverage and a readOnly annotation, the description covers the essentials plus return-shape cues. Only the absence of any note on error cases (e.g. nonexistent form_id) keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented, and the baseline is 3. The description echoes 'with_fields' via 'optionally with its full field list' but adds no format, default, or effect detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Fetch a form's details') and enumerates the returned content (name, URL, submission counts, settings), which separates it from list_forms and list_form_fields without opening a schema. The endpoint reference (GET /forms/{formId}) pins the resource identity further.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'optionally with its full field list' implies the relationship to formstack_list_form_fields, but no when-to-use, when-not-to-use, or named alternative is stated. Usage is inferable from the name and purpose rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single submission with every field's label, type, display value and parsed value, plus payment, approval and workflow status. Formstack: GET /submissions/{submissionId}.
| Name | Required | Description | Default |
|---|---|---|---|
| submission_id | Yes | The submission ID. | |
| encryption_password | No | Only for forms with encryption enabled: the form's encryption password, sent as the X-FS-Encryption-Password header. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, and the description adds genuinely new behavioral context by describing what the response contains (parsed vs display values, payment/approval/workflow status) — valuable since no output schema exists. It omits error behavior (e.g., missing submission) and rate-limit/permission notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with the resource and payload contents front-loaded and zero filler. Every clause carries information an agent can use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately carries the return-value summary, and the schema plus readOnlyHint cover safety and inputs. A single-resource fetch needs little else, though a note on not-found/error behavior would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (submission_id, encryption_password) are fully documented in the schema, including the header mechanism for encryption. The description adds no parameter-level detail beyond restating the endpoint path, which matches the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a single submission') and enumerates the payload contents (field labels, types, display and parsed values, payment/approval/workflow status) plus the underlying endpoint. It contrasts implicitly with the sibling list/search tools via 'a single submission', but never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the required submission_id signals 'call this when you have one submission's ID'. There is no explicit guidance on when to prefer this over formstack_list_form_submissions or formstack_search_submissions, and no stated preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the confirmation emails sent to the person who submits a form — sender, subject, message and delay. Formstack: GET /forms/{formId}/confirmations.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description goes beyond that by enumerating the returned content (sender, subject, message, delay) and pinning the underlying endpoint, which is real value given there is no output schema. Auth requirements and pagination are still unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The resource and its scope come first, and the endpoint mapping is tucked at the end as supporting detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with annotations covering safety, the description pairs the resource definition with the shape of the returned emails, compensating for the missing output schema. Only auth/pagination behavior is left silent, a minor gap at this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, form_id, and schema description coverage is 100%, so the schema fully documents it. The description reinforces the formId placement via the endpoint path but adds no format or constraint detail beyond the schema's type and bounds. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (list) plus resource (a form's confirmation emails) and a definition of what those emails are — the ones sent to the submitter. That semantic definition implicitly separates it from the sibling formstack_list_notification_emails (admin-facing notifications), though the alternative is never named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the resource definition: use it when you need a form's auto-reply confirmations. There is no explicit when-to-use, no when-not, and no pointer to formstack_list_notification_emails for the other email type, which is the most likely confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's form folders and their subfolders. Formstack: GET /folders.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting at 1. | |
| per_page | No | Folders per page (minimum 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safe read profile, so the description needs only to add context. It contributes the hierarchical nature of the result (folders plus subfolders) and the API mapping, but says nothing about pagination behavior despite page/per_page parameters being present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the resource and scope, with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should ideally characterize the returned folder objects and pagination. It partially does so ('folders and their subfolders') but leaves the agent guessing about return shape and how to page through results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so page and per_page are fully documented in the schema itself. The description adds no format, default, or boundary nuance beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the account's form folders and their subfolders') and even names the underlying endpoint. An agent can distinguish it from formstack_get_folder, but the description never explicitly contrasts the single-folder sibling, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of when to prefer get_folder or list_forms over this tool. Usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every field on a form — id, label, type, required flag, options and logic. Use this to learn field IDs before searching or creating submissions. Formstack: GET /forms/{formId}/fields.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does: it enumerates the fields returned and maps the tool to the underlying endpoint (GET /forms/{formId}/fields), which helps an agent anticipate the payload shape. It omits pagination/completeness behavior, keeping it just below top marks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences plus an endpoint reference; the purpose and returned attributes lead, and the usage guidance follows. Nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, listing the returned attributes is exactly the compensation needed, and the endpoint reference closes most of the remaining gap. The only omission is whether the field list is paginated or always complete, which for a single-form read tool is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single form_id parameter, so the schema already carries the semantics. The description only echoes the notion of a form via 'on a form' and the endpoint path; it adds no format, range, or sourcing guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List every field on a form') and enumerates the exact attributes returned (id, label, type, required flag, options, logic). No sibling tool deals with form fields, so the resource alone separates it from list_form_submissions, get_form, and the rest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this to learn field IDs before searching or creating submissions' gives a concrete trigger and names the downstream tools it enables. It stops short of stating when-not-to-use (e.g., when you already have field metadata), so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the forms in the account, with submission counts, live URL and folder. Filter by name or folder and sort. Formstack: GET /forms.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort direction (default ASC). | |
| folder | No | Only forms in this folder ID. | |
| search | No | Match forms by name. | |
| order_by | No | Column to order by, e.g. name, created, updated. | |
| page_size | No | Items per page, 10-500 (Formstack default 50). | |
| page_number | No | Page number, starting at 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description does add value by naming the returned fields (submission counts, live URL, folder), but it says nothing about pagination behavior or result limits beyond what the schema's page_size default already conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the resource and the useful return-field summary. The trailing 'Formstack: GET /forms' is a minor redundancy but not enough to hurt readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, describing the returned fields is the right compensation, and pagination is covered by the schema parameters. An agent has what it needs to call this correctly; only pagination/limit semantics are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented with type, range and defaults. The description only gestures at filtering and sorting generically, adding no syntax or behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('forms in the account') plus the useful scope detail that results include submission counts, live URL and folder. It is clearly distinct from the singular formstack_get_form and the sibling list_* tools, though it never names an alternative to route between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Filter by name or folder and sort' implies the supported usage pattern and maps loosely onto the filter/sort parameters, but there is no explicit when-to-use statement or exclusion (e.g. use formstack_get_form when you already have an ID).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a form's submissions, newest or oldest first, filtered by keyword, date range or specific field values. Set include_data to get the answers. Formstack: GET /forms/{formId}/submissions.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort direction (default ASC). | |
| form_id | Yes | The form ID. | |
| keyword | No | Match submissions by content across all fields. | |
| max_time | No | Only entries created on or before this date/time: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (Eastern Time). | |
| min_time | No | Only entries created on or after this date/time: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (Eastern Time). | |
| page_size | No | Items per page, 10-500 (Formstack default 50). | |
| data_format | No | Shape of data: legacy (object keyed by field id) or standardized (array of field objects). | |
| expand_data | No | Include expanded field data with parsed values. | |
| page_number | No | Page number, starting at 1. | |
| pretty_name | No | Include a human-readable name per submission (from its name/email field). | |
| include_data | No | Include each submission's field data. | |
| field_filters | No | Search specific fields by value (up to 10 criteria, AND-ed). | |
| encryption_password | No | Only for forms with encryption enabled: the form's encryption password, sent as the X-FS-Encryption-Password header. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint already marks this as a safe read, and the description adds useful context that data is omitted unless include_data is set, plus ordering behavior. It says nothing about pagination interplay (page_size default 50, page_number), rate limits, or what the encryption_password header implies operationally, leaving clear gaps for a 13-parameter read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences: action + filters first, then the include_data tip, then the underlying API endpoint. It is front-loaded and free of padding, though the trailing endpoint reference adds marginal value for an agent choosing a tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full schema coverage and no output schema, the description covers the essential behavior: filtering modes, sort direction, and the data-inclusion switch. It is adequate, though a note on paging behavior would round it out given the 13-parameter surface.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter including timezones, ranges and formats; the baseline is therefore 3. The description's mentions of keyword/date/field filtering and include_data largely restate schema content without adding syntax or format detail beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ("List a form's submissions") and enumerates the available filtering modes (keyword, date range, field values) and ordering. It stops short of distinguishing this from the very similar sibling formstack_search_submissions, leaving the agent to infer the boundary between a filtered list and a search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers one practical usage tip ("Set include_data to get the answers"), which implies how to get useful output, but never states when this tool is preferable to formstack_search_submissions, formstack_list_partial_submissions, or formstack_count_form_submissions. Usage is implied rather than routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the notification emails that alert your team when a form is submitted — recipients, subject, sender and logic. Formstack: GET /forms/{formId}/notifications.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description doesn't need to argue safety. It adds modest value by naming the returned fields (recipients, subject, sender, logic), effectively disclosing the response shape in the absence of an output schema, but says nothing about ordering, pagination, or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence covering purpose and returned content, followed by the concrete API route. No filler, no redundancy, and the most important information (what is listed) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers what the tool does and what the records contain, which is enough to invoke it correctly. Minor omissions (result ordering, pagination, whether a form can have zero notifications) keep it short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter, form_id, and the schema documents it at 100% coverage, so the description has no gap to fill. It restates the path variable via the embedded endpoint (GET /forms/{formId}/notifications) but adds no format or constraint detail beyond the schema. Baseline 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('List the notification emails') and enumerates the payload it returns (recipients, subject, sender, logic), so the resource is unambiguous. It never names the closely related sibling formstack_list_confirmation_emails, so the agent gets no explicit differentiation from that near-identical tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'when a form is submitted' clause implies the scenario in which these emails fire, which gives an implicit sense of when the tool is relevant. There is no explicit when-to-use statement, no exclusions, and no routing to the confirmation-email or submit-action siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List entries respondents started but did not finish (Save & Resume / abandoned), with the same filters as submissions. Formstack: GET /form/{formId}/partialsubmission.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort direction (default ASC). | |
| form_id | Yes | The form ID. | |
| keyword | No | Keyword to search. | |
| max_time | No | Only entries created on or before this date/time: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (Eastern Time). | |
| min_time | No | Only entries created on or after this date/time: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (Eastern Time). | |
| page_size | No | Items per page, 10-500 (Formstack default 50). | |
| expand_data | No | Expand data with detailed field information. | |
| page_number | No | Page number, starting at 1. | |
| pretty_name | No | Include pretty names. | |
| include_data | No | Include each partial submission's data. | |
| field_filters | No | Search specific fields by value (up to 10 criteria, AND-ed). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already establishes this is a safe read operation, so the bar is lower. The description adds useful semantic context about what the records represent (abandoned / Save & Resume entries), but says nothing about pagination behavior, result ordering defaults, or data-volume expectations for a tool exposing 11 filter parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler; the core purpose and its distinguishing scope are front-loaded before the endpoint reference, which is useful for traceability but placed last.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with fully documented parameters and no output schema, the description covers what the records are and that filtering mirrors the submissions endpoint, which is enough to call it correctly. Return format is left unstated, but that omission is minor given the schema carries the parameter burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every one of the 11 parameters is already documented with type, range, and format details. The description's claim that filters mirror the submissions endpoint adds framing but no syntax or value semantics beyond what the schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (entries respondents started but did not finish), and clarifies scope with the parenthetical '(Save & Resume / abandoned)'. This cleanly distinguishes it from the sibling formstack_list_form_submissions, since partial vs. completed is the only difference an agent needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"With the same filters as submissions" implies the tool is invoked like the submissions listing, but there is no explicit when-to-use guidance, no mention of when to prefer this over search_submissions or count_form_submissions, and no stated prerequisites. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List what happens after a form is submitted — default processing, a custom message, or a redirect URL — with conditional logic. Formstack: GET /forms/{formId}/submitactions.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds useful behavioral color by noting that submit actions carry conditional logic and can be one of three kinds, but it says nothing about pagination, auth requirements, or whether actions are returned in evaluation order.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly written sentence that front-loads the core description of the return content, followed by a compact endpoint reference. Nothing is wasted, though the endpoint path is somewhat redundant with the tool's structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with a fully documented single parameter and annotations covering safety, the description is essentially complete: it explains what the returned actions represent and their varieties. Without an output schema it could optionally have described the response fields, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (form_id) and schema description coverage is 100%, so the schema fully documents the input with constraints (integer, >0). The description adds no syntax or semantic detail beyond the schema, which is the expected baseline for a single well-documented param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('List') plus resource ('submit actions' / what happens after submission) and an enumeration of the possible outcomes (default processing, custom message, redirect URL). It is clearly distinguishable from siblings like formstack_list_confirmation_emails and formstack_list_notification_emails, though it never names them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the resource and the included GET path, so an agent can infer this is the read-only way to inspect post-submit configuration. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the webhooks that push a form's submissions to external URLs, with their payload settings. Formstack: GET /forms/{formId}/webhooks.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read. The description adds useful scope (it returns payload settings and the underlying GET endpoint), but adds nothing about return format, ordering, or pagination behavior. With the safety profile already covered by annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loading the operation before the API path. The API endpoint reference is mildly redundant for an agent but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with no output schema and annotations covering safety, the description supplies enough to call it correctly. It could mention what a webhook entry contains or whether results paginate, but the gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is only one parameter (form_id), so the schema fully documents it. The description adds no additional parameter meaning, which is the baseline case for near-complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (a form's webhooks) with useful scope detail about payload settings. The verb 'list' cleanly separates it from the sibling formstack_create_webhook, though this differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives, nor any prerequisites or context. The agent must infer usage purely from the verb and resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search for submissions across every form in the account, e.g. by a person's email or name. Formstack: GET /submissions.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort direction (default ASC). | |
| search | Yes | Search term to match against submission content. | |
| page_size | No | Items per page, 10-500 (Formstack default 50). | |
| page_number | No | Page number, starting at 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already tells the agent this is a safe read operation. The description adds that it is an account-wide full-text GET search with example query fields, but it does not disclose pagination behavior, rate limits, authentication needs, or result format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two front-loaded sentences: the first states the action, scope, and examples; the second supplies the API endpoint. There is no filler or repetition, so every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool whose four parameters are fully documented in the schema and whose read-only nature is covered by annotations, the description supplies the missing scope and search examples. It omits any note about pagination or result structure, but with no output schema and complete parameter coverage this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all four parameters including order, page size, and page number. The description's example of searching by a person's email or name slightly enriches the 'search' parameter, but it adds no syntax or format details beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Full-text search'), resource ('submissions'), and scope ('across every form in the account'), with examples of searchable fields. This makes the tool's purpose clear, but it does not explicitly name or contrast with sibling tools such as formstack_list_form_submissions or formstack_count_form_submissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool versus alternatives, nor does it provide prerequisites or exclusions. The phrase 'across every form in the account' implies a cross-form search context, but that is part of the purpose statement, not explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a form, move it to a folder, change its submit-button text, timezone or language, or activate/deactivate it (with a message shown while inactive). Reversible. Formstack: PUT /forms/{formId}.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New form name. | |
| folder | No | Folder ID to move the form into. | |
| form_id | Yes | The form ID. | |
| language | No | Form language. | |
| timezone | No | Form timezone. | |
| is_active | No | Turn the live form on (true) or off (false). | |
| disabled_message | No | Message shown while the form is inactive. | |
| submit_button_title | No | Submit button text on the live form. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims the operation is "Reversible," which directly conflicts with the destructiveHint=true annotation. Destructive caveats are exactly what an agent relies on for a live-form mutation (turning a form off, retitling a submit button), so asserting reversibility without qualification risks the agent proceeding on a false safety premise.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences: the first front-loads the full range of editable fields, and the second carries the behavioral note and API mapping. No filler, nothing out of order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All 8 parameters are covered by a 100% schema, no output schema exists so return values need not be explained, and the description enumerates every meaningful operation. The only gap is that the reversibility claim is unqualified and there is no note on permissions or failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds light semantic framing for some fields (folder = move location, disabled_message = shown while inactive, submit_button_title = live form text), but does not go beyond what the schema already documents, so no uplift is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (update/rename/move/change/activate) and resource (form settings), and enumerates the exact editable fields so it is unmistakably distinct from siblings like formstack_get_form or formstack_list_forms. An agent can identify the tool's scope without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the field list (use it to change form settings), and the sibling set makes the read-vs-write split inferable. However, there is no explicit when-to-use statement, no when-not guidance, and no mention of prerequisites such as needing the form to exist or requiring ownership permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change field values on an existing submission, or mark it read/unread. Only the fields you pass are changed. Formstack: PUT /submissions/{submissionId}.
| Name | Required | Description | Default |
|---|---|---|---|
| read | No | Mark the submission read (true) or unread (false). | |
| fields | No | Field values to change. | |
| submission_id | Yes | The submission ID. | |
| encryption_password | No | Only for forms with encryption enabled: the form's encryption password, sent as the X-FS-Encryption-Password header. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry only destructiveHint=true, so the description must do real work here — and it does: 'Only the fields you pass are changed' clarifies this is a partial/patch-style update rather than a destructive overwrite, which directly softens an aggressive destructive hint. It still says nothing about auth, errors on invalid field IDs, or the encryption-password failure mode (that lives only in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: mutation scope, partial-update rule, and endpoint. No filler and the most decision-relevant fact (what gets changed) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the agent doesn't need return-value documentation, and the schema fully covers parameters. For a destructive update tool the description is nearly sufficient, though an explicit note that unlisted fields are untouched (already implied) plus behavior on invalid IDs would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema documents every parameter, including the field-value shapes and encryption_password header. The description adds the partial-update semantic tied to 'fields', but no syntax or format detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Change field values on an existing submission') and adds the read/unread variant, which is more than a restatement of the title. It implicitly separates itself from create_submission/get_submission via 'existing submission', but never explicitly names a sibling or an alternative, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the verb: an agent can infer you call this to modify rather than fetch a submission, but the description gives no when-to-use/when-not guidance, no prerequisites, and no explicit pointer to alternatives (create_submission, get_submission, formstack_list_form_fields).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
formstack_count_form_submissions1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_create_folder1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_create_prefill_url1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_create_submission1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_create_webhook1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_get_folder1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_get_form1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_get_submission1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_confirmation_emails1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_folders1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_form_fields1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_form_submissions1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_forms1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_notification_emails1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_partial_submissions1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_submit_actions1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_list_webhooks1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_search_submissions1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_update_form1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_update_submission1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"formstack_count_form_submissionsformstack_create_folderformstack_create_prefill_urlformstack_create_submissionformstack_create_webhookformstack_get_folderformstack_get_formformstack_get_submissionformstack_list_confirmation_emailsformstack_list_foldersformstack_list_form_fieldsformstack_list_form_submissionsformstack_list_formsformstack_list_notification_emailsformstack_list_partial_submissionsformstack_list_submit_actionsformstack_list_webhooksformstack_search_submissionsformstack_update_formformstack_update_submissionRead Fillout forms and submissions, export responses, and create submissions and webhooks.
Build, preview, edit, publish and analyze forms and surveys; read responses and manage webhooks.
Form backend for static sites: create forms, manage submissions, webhooks and exports.
Build, edit and publish forms and read their responses from your AI assistant.
Add one secure layer between your agents and this server.
