formstack

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 adds the 7-day lookback cap and the per-day breakdown shape, which is useful, but says nothing about rate limits, pagination, or what happens when start_date and lookback_period interact.

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: the capability and window come first, then the API mapping. No filler and nothing buried.

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 usefully discloses the return shape ('per-day breakdown'), which is the key missing structured information. A little more on how start_date and lookback_period combine would make it fully self-sufficient.

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 three parameters are documented in the schema, including the max-7 constraint. The description only restates the 7-day window and adds no syntax or interaction detail beyond that baseline.

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 (count) and resource (a form's submissions) plus scope (per-day breakdown, lookback up to 7 days). The 'count' framing inherently separates it from formstack_list_form_submissions, though it 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 implied by the description — you call it when you need aggregate counts rather than raw submissions — but there is no explicit when/when-not statement or named alternative such as formstack_list_form_submissions or formstack_search_submissions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply destructiveHint=true, which is thin and arguably miscalibrated for an additive create operation. The description adds the endpoint (POST /folders) and the root/parent placement model, but says nothing about required permissions, name-collision behavior, or what is returned on success, leaving notable behavioral gaps.

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 with the core action front-loaded. The trailing 'Formstack: POST /folders' is lean but of limited use to an MCP caller, keeping it just below a perfect score.

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, single-resource creation tool with a fully documented schema, no output schema, and no nesting, the description covers what an agent needs to select and invoke it. The main omission is any hint about the created folder's identity for follow-up calls, but with no output schema that is not strictly required.

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 both 'name' and 'parent' (including 'omit for root level'). The description's phrasing about root vs parent restates that same idea rather than adding syntax, format, or constraint detail, 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 and resource ('Create a folder') plus scope ('at the root or inside a parent folder'), which cleanly separates it from the read-oriented siblings like formstack_get_folder and formstack_list_folders. It stops short of explicitly differentiating itself from other create_* tools, so it lands just under the top band.

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 mention of root vs parent folder hints at the parent-selection case, but there is no explicit guidance on when to use this instead of, say, creating a folder via other means, nor any prerequisite or conflict conditions. Adequate but with clear gaps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply destructiveHint=true, so the description does the explanatory work: it discloses that Formstack persists the prefill server-side and that the call returns prefilledUrl. That clarifies why the operation is marked destructive. It omits any note on permissions or rate limits, keeping it 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 economical sentences lead with the outcome and follow with the storage/return behavior; the trailing API mapping is terse and useful for API-oriented agents. No rephrasing of the title or 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?

With no output schema, the description correctly names the returned artifact (prefilledUrl), and the rich input schema covers the nested field-value formats. Nothing essential for a correct call is missing, though permission/auth context is absent.

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 field ID/value shapes, the form_id, and the optional incomplete_password, so the description adds no syntax beyond it. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (Generate) and resource (link to a live form with prefilled fields) in the first sentence, and the API mapping (POST /forms/{formId}/prefill) pins the operation down. An agent can distinguish this from formstack_create_submission or formstack_get_form without opening a 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?

Gives a concrete use case ('send a customer a form with their name and account number pre-entered'), which tells the agent when this tool is the right one. However, it never names an alternative or an exclusion (e.g. when to use create_submission instead), so it stops short of full when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only carry destructiveHint=true, so the description's disclosure that the submission counts toward the form and fires notification emails, webhooks, and integrations adds genuinely valuable behavioral context beyond the structured field. It stops short of stating permission/auth requirements or the return shape, so it is not exhaustive.

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 the API mapping; the side-effect warning (the most important fact) 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 mutation tool with only a destructiveHint annotation and no output schema, the description covers the critical consequence of calling it. It is largely complete, though a note on required permissions or whether the submission can be undone 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 nested field-value shapes are fully documented in the schema, so the description rightly does not repeat them. It contributes no additional parameter meaning of its own, which is the expected baseline when the schema already does the work.

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 ('Submit an entry to a form') and adds scope ('on someone's behalf'), which cleanly differentiates it from formstack_update_submission, formstack_get_submission, and formstack_list_form_submissions without needing 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?

The warning that this is a *real* submission with side effects implicitly tells the agent when this tool is appropriate, but it names no alternatives (e.g., when to prefer update_submission or partial submissions) and gives no explicit exclusions or prerequisites. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare destructiveHint=true, so the description carries most of the behavioral load. It discloses the meaningful persistent behavior (every future submission is POSTed to the URL) plus the underlying API route. It does not cover auth/permission requirements, retry or failure handling beyond the error_emails param, or what is returned.

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 user-facing effect and followed by the API route. Slightly extraneous implementation detail ('Formstack: POST /forms/{formId}/webhooks') but no wasted prose.

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 creation tool with full schema coverage and no output schema, the description covers the essential behavior. It does not mention what the call returns (e.g. a webhook ID needed for later updates/deletion) or any auth requirements, which would help an agent chain follow-up calls.

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 each of the 11 parameters, including enums and the HMAC option, is documented in the schema itself. The description adds no parameter-level 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 ('Add a webhook'), the resource, and the exact effect: POSTs each new form submission to a URL. This is unambiguously distinguishable from siblings like list_webhooks or update_form without opening any 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 create semantics and the description of what the webhook does, but there is no explicit when-to-use guidance, no prerequisites (e.g. form must exist), and no statement about when NOT to create a webhook versus using list_webhooks to inspect existing ones.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=true, so the description carries the load beyond that and usefully discloses the response shape: parent, permissions and direct subfolders, plus the underlying REST endpoint. That tells an agent this is a single-folder fetch that includes hierarchy context, not a flat list.

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 operation and its returned contents, with the API reference trailing. 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?

For a one-parameter read tool with no output schema, the description supplies the essentials: what is fetched and what the response contains. Only the distinction from the sibling list tool is left unstated.

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?

Single folder_id parameter is fully documented in the schema (100% coverage) including type and a positive-integer bound. The description adds no format or sourcing guidance beyond what the schema already gives, 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 (fetch) and resource (a folder), and even enumerates what the payload includes: parent, permissions, direct subfolders. It does not explicitly name list_folders, so the sibling distinction is only implied by the singular 'a folder'.

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 statement of when to use this versus formstack_list_folders (browse the tree) or formstack_create_folder. The singular phrasing hints at single-item retrieval, but there is no explicit routing guidance or precondition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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's added value is in disclosing the response composition (name, URL, submission counts, settings) and the conditional enrichment via with_fields. It stops short of covering auth requirements or error behavior, but for a read-only lookup it supplies meaningful extra context.

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?

A single sentence, front-loaded with the main action and its return contents, then the optional flag, then the endpoint. No filler or redundancy.

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, so the description correctly takes on the job of describing what comes back, and for a trivial two-parameter read it covers the essentials. Minor omissions (permissions scope, behavior when the form ID does not exist) keep 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 form_id and with_fields are already documented. The description reinforces with_fields by characterizing it as returning the 'full field list,' but adds no format, default, or edge-case detail beyond the schema, making the baseline 3 appropriate.

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 and resource ('Fetch a form's details') and enumerates the payload contents (name, URL, submission counts, settings), which separates it from formstack_list_forms and from formstack_list_form_fields. The 'GET /forms/{formId}' endpoint notation reinforces that this retrieves a single form by ID.

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 tool is for retrieving one known form, and the 'optionally with its full field list' clause hints at when to use with_fields. However, there is no explicit guidance on when to prefer this over formstack_list_form_fields or formstack_list_forms, and no prerequisites are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already establishes this is a safe read, so the bar is lower; the description still adds real value by detailing the shape of the returned payload (parsed vs display values, payment/approval/workflow status) and notes no auth or pagination behavior. With no output schema, this return-content disclosure is the main behavioral signal.

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, front-loaded with the action and result content, then the API mapping. No filler and nothing redundant.

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 2-parameter, read-only fetch with no output schema, the description covers the action, the inputs are fully documented in the schema, and the response contents are described well enough to call it correctly. Only minor gaps (no note on missing-ID behavior) remain.

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% — both submission_id and encryption_password (including the X-FS-Encryption-Password header detail) are documented in the schema. The description adds no parameter-specific semantics 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 (Fetch) and resource (a single submission) and enumerates what comes back: field label, type, display value, parsed value, plus payment, approval and workflow status. The word 'single' cleanly separates it from the list/count/search siblings.

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 fact that it retrieves one submission by ID; there is no explicit when-to-use, when-not-to-use, or naming of alternatives such as formstack_list_form_submissions or formstack_search_submissions. 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint=true declared by annotations, the safety profile is covered. The description adds useful return-payload information (sender, subject, message, delay) and names the underlying endpoint, going beyond what the annotations provide. Pagination and auth behavior remain unstated, keeping it from 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?

One sentence plus a compact endpoint reference, front-loaded with the core purpose and no wasted words.

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 full schema coverage and no output schema, the description compensates by naming the returned fields and the API route. It is nearly complete, though it omits details like pagination or ordering that could matter for list 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% and the single parameter (form_id) is already documented in the schema. The description adds no syntax, format, or constraint details beyond what the schema provides, so 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 confirmation emails') and clarifies the audience ('sent to the person who submits a form'), which distinguishes it from notification emails. An agent can tell what it 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?

The description implies when this tool is relevant by scoping it to submitter-facing confirmation emails, but it never names the alternative (e.g., formstack_list_notification_emails) or states explicit when/when-not conditions. 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.

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 adds that results include subfolders (nested traversal) and the backing endpoint (GET /folders), which is modest extra context, but it says nothing about pagination behavior or result size even though pagination params exist.

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, front-loaded sentences with no filler; the scope statement leads. The 'Formstack: GET /folders' line is somewhat redundant for an agent but is compact and harmless.

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 no output schema, the description covers what is listed but says nothing about the shape of returned folder records or ordering. It is adequate but leaves the return semantics to inference.

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 page and per_page are fully documented in the schema. The description adds no pagination syntax or defaults 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?

The description states a specific verb and resource ('List the account's form folders and their subfolders'), and the mention of subfolders conveys the hierarchy scope. It does not explicitly contrast with siblings like formstack_get_folder or formstack_list_forms, 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?

There is no explicit when-to-use guidance, no mention of when to prefer formstack_get_folder instead, and no note about pagination limits. The only usage signal is the implicit 'list all folders' reading of the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 adds meaningful behavioral context by enumerating the returned field attributes (id, label, type, required, options, logic) and disclosing the underlying endpoint GET /forms/{formId}/fields. Pagination or rate-limit behavior is not mentioned, keeping it from 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 tightly packed sentences with zero filler, front-loading the return contents before the usage guidance and closing with the endpoint. 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 correctly compensates by enumerating the returned fields, and it supplies both the usage context and the backing endpoint. The only omission is return shape details such as ordering or pagination for forms with many fields.

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 form_id parameter, so the schema already carries the semantics; per the rubric this establishes a baseline of 3. The description adds nothing about form_id format or acquisition beyond what the schema states.

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 ("every field on a form") and enumerates exactly what is returned (id, label, type, required flag, options, logic), which clearly differentiates it from siblings like formstack_get_form or formstack_list_forms. An agent knows precisely what this tool yields without opening a 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?

"Use this to learn field IDs before searching or creating submissions" gives an explicit when-to-use and even a prerequisite ordering relative to formstack_search_submissions and formstack_create_submission. It stops short of naming any when-not-to-use condition or a direct alternative, so it is strong but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already establishes this as a safe read. Because there is no output schema, the description's disclosure of the returned fields (submission counts, live URL, folder) is genuinely additive and tells the agent what to expect back, though it says nothing about pagination limits or rate behavior beyond what the schema implies.

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 with the core purpose and the filtering/sorting capability front-loaded; little waste. The trailing 'Formstack: GET /forms' is a minor endpoint reference that adds little for an agent but costs almost nothing.

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 six-parameter, all-optional list tool, the description covers scope, filters, sort, and returned fields, and the schema handles parameter detail. The absence of an output schema is partially offset by the field enumeration, leaving only pagination behavior and result-count expectations unstated.

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 six filters (search, folder, order, order_by, page_size, page_number) are already fully documented with defaults and ranges. The description's mention of filtering by name/folder and sorting maps to those parameters but adds no syntax or format detail beyond the schema, so 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 forms in the account') and even enumerates the returned fields (submission counts, live URL, folder), so the agent knows exactly what the tool yields. It does not explicitly contrast itself with singular siblings like formstack_get_form, so it stops 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?

The description notes that results can be filtered by name or folder and sorted, which implies when the tool is useful, but it never states when to prefer it over alternatives such as formstack_get_form for a single form or formstack_list_folders for folder enumeration. Usage is implied rather than specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=true, so the description adds genuinely useful behavior: the default ordering direction, and the crucial note that field answers are only returned when include_data is set. That default-returns-no-answers detail materially changes how an agent calls the tool. It stops short of covering pagination behavior or result volume, which matters given 13 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 plus an endpoint reference, front-loaded with the core action and the include_data caveat. Every clause carries information and nothing is 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?

For a read-only listing tool with a fully documented 13-parameter schema and no output schema, the description covers the essentials (filtering, ordering, the include_data requirement). The remaining gaps, sibling differentiation and pagination guidance, are modest but real against a crowded sibling set.

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 explains order, time bounds, page_size, field_filters, data_format, and encryption_password. The description only re-summarizes the filter categories and singles out include_data, adding little syntax or semantics beyond the structured fields; baseline 3 is appropriate.

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?

Names a specific verb and resource (list a form's submissions) and describes scope: ordering, keyword/date/field-value filtering, and the underlying GET endpoint. It is clear on its own, but it never distinguishes itself from the very close sibling formstack_search_submissions, leaving the agent to guess which listing/search tool to pick.

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 implies when the tool is useful (filtering by keyword, date range, or field values) and flags the include_data switch, but it gives no explicit when-to-use vs when-not, and does not route the agent to formstack_search_submissions, formstack_count_form_submissions, or formstack_list_partial_submissions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read, and the description reinforces it by naming the GET endpoint. It also discloses the shape of the payload (recipients, subject, sender, logic), which is useful context. However, it says nothing about pagination, ordering, or empty results — behavioral traits the annotations do not cover.

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 sentence of purpose followed by the endpoint — front-loaded, no filler, every element useful. The payload fields are packed economically into the first sentence.

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-only list tool with no output schema, the description names the returned fields (recipients, subject, sender, logic), which compensates well for the absence of a return schema. Minor gaps remain around pagination and result volume.

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 and schema coverage is 100%, so the schema already documents form_id fully. The description adds nothing beyond echoing it in the endpoint path (GET /forms/{formId}/notifications). Baseline 3 is appropriate.

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 (notification emails), and adds a functional gloss — emails that alert your team when a form is submitted — plus the underlying endpoint. It implicitly distinguishes itself from the sibling formstack_list_confirmation_emails by describing the audience (your team vs. presumably the submitter), but never names that sibling, so full differentiation is not explicit.

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 tells the agent what the emails do, which hints at when to fetch them, but there is no explicit when-to-use/when-not or named alternative despite the near-identical sibling list_confirmation_emails.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 adds useful domain context (these are abandoned/Save-&-Resume entries, not finished submissions) and cites the underlying endpoint, but says nothing about return shape, pagination, or the volume of abandoned records, which would be the valuable extra beyond annotations.

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 clauses front-load the resource definition and the conceptual disambiguation, then supply the API path. There is no filler, though the raw endpoint reference is of limited value to 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?

With 11 parameters and no output schema, the description identifies the resource but leaves return content and pagination unstated. It is adequate for selecting the tool, but for a high-parameter list operation it could say more about what each partial-submission record contains.

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 are already documented in the schema. The description adds only 'same filters as submissions,' which conveys parity but no parameter-specific syntax or defaults 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?

The description states a specific verb+resource ('List entries respondents started but did not finish') and defines the unusual domain term 'partial submission' via Save & Resume / abandoned, clearly distinguishing it from complete submissions. It does not name the sibling formstack_list_form_submissions directly, so it stops 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?

'with the same filters as submissions' gives implied usage context and tells the agent that filtering semantics carry over, but there is no explicit when-to-use / when-not-to-use guidance or a named alternative for retrieving completed entries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds value by describing what the actions represent (default processing, custom message, redirect URL, conditional logic), but omits operational behavior such as authentication, pagination, or response 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?

Two compact sentences: the first front-loads the purpose and enumerates the action types; the second gives the REST endpoint. Every element contributes, with no 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?

For a simple read-only list tool with one required parameter, the description provides sufficient context about what is returned and how it is scoped. Annotations and schema cover safety and parameter meaning, so nothing critical 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 coverage is 100% for the single form_id parameter, and the schema already documents it as 'The form ID.' The description's endpoint path reinforces the same parameter but adds no new semantic detail. Baseline 3 applies when the schema does the heavy lifting.

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 'what happens after a form is submitted', then enumerates the concrete action types (default processing, custom message, redirect URL) with conditional logic. This clearly distinguishes it from sibling list_* tools for webhooks, emails, and submissions without needing to name 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?

No explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The context is implied by the tool's purpose but never stated, which is the 'no guidance' level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds useful domain context (webhooks push submissions to external URLs, payload settings included), but says nothing about return structure, ordering, or permissions for the endpoint.

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 the core purpose front-loaded and the endpoint hint appended; 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 single-parameter read-only list operation with annotations covering the safety profile and full schema documentation of the parameter, the description is largely sufficient. It could mention pagination or the shape of returned webhook data, but no output schema exists to leverage either.

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), documented at 100% coverage by the schema itself. The description's phrase 'a form's webhooks' reinforces the scoping but adds no syntax or format detail beyond the schema, 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 (list) and resource (webhooks) scoped to a form, and clarifies what webhooks are (pushing submissions to external URLs with payload settings). This distinguishes it cleanly from the sibling formstack_create_webhook.

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 implies reading existing webhook configuration for a form, but gives no explicit when-to-use guidance, prerequisites, or reference to alternatives like formstack_create_webhook for creating them. Usage is inferable but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 adds the account-wide scope and the backing endpoint (GET /submissions), but says nothing about result volume, pagination behavior, or match semantics beyond the schema's parameter docs.

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 scope constraint before the example. The trailing 'Formstack: GET /submissions' is mildly redundant metadata but does not bloat the definition.

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, paginated search tool with a fully documented schema and no output schema, the definition covers scope, purpose, and an example. It is nearly complete; only pagination/result-set expectations are unaddressed, which the schema's page_size/page_number largely imply.

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 four parameters (search, order, page_size, page_number) are already documented in the schema. The description adds only that a search term can be an email or name, which is marginal beyond the schema text.

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 (search) and resource (submissions) with scope 'across every form in the account,' which implicitly contrasts with the per-form sibling formstack_list_form_submissions. It never names an alternative explicitly, so differentiation is inferred 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?

The description gives an example use case ('by a person's email or name'), which implies when it is useful, but offers no when-not conditions and names no alternative tools. An agent must infer that this is the cross-form search versus the form-scoped list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply destructiveHint=true, so the description usefully adds that the operation is 'Reversible' and that deactivating shows a message while inactive, which directly contextualizes the destructive hint. It still omits auth/permission requirements and whether omitted fields are preserved or reset on this PUT.

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 plus a compact endpoint reference; every clause names a distinct capability 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 an eight-parameter mutation flagged destructive, the description covers the changeable fields and reversibility but never states whether this PUT replaces the whole settings object or only patches supplied fields, nor what permissions are required. That ambiguity is material when a live form can be deactivated.

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 eight parameters are already documented in the schema; the description largely restates them. It does add the useful coupling of is_active with disabled_message, but nothing on format, ranges, or partial-update semantics.

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 (update) plus resource (form) with an explicit enumeration of the mutable settings: name, folder, submit-button text, timezone, language, and active state. It is trivially distinguishable from read siblings like formstack_get_form or formstack_list_forms.

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 enumeration implies usage (use this when you want to change any of those settings), but there is no explicit when-to-use guidance, no prerequisites, and no alternative named (e.g., create vs. update). 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, so the safety profile is already carried; the description adds the genuinely useful partial-update semantics ('Only the fields you pass are changed'), which tempers the destructive expectation. It omits irreversibility and permission/encryption requirements, but the partial-update clarification is real value beyond the annotations.

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 the primary mutation front-loaded, followed by the partial-update constraint and the API endpoint. No filler; every clause carries information.

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 mutation tool with full schema coverage and no output schema, the description covers the operation, the partial-update behavior, the read/unread side effect, and where to get field IDs. Auth/permission requirements and the effect of the encryption password are left to the schema, which 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 already documents all four parameters in detail (including the read toggle, field value shapes, and the encryption password header). The description only restates read/unread and adds no syntax beyond the schema, 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 ('Change field values on an existing submission') plus a secondary operation (mark read/unread), which cleanly separates it from formstack_create_submission and formstack_get_submission. An agent can identify the operation 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?

The description implies usage context (modify an existing submission rather than create one) and points to formstack_list_form_fields for obtaining field IDs, which is a useful cross-reference. However, it never states when to choose this over alternatives or any prerequisites beyond the field-ID lookup.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.