GoFormz MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description's job is lighter. It adds real value by spelling out the consequence of non-idempotency ('Each call adds another row' — duplicates accumulate) and naming the endpoint, though it omits duplicate-key error behavior and permission requirements.

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?

Four short lines with the WRITE marker front-loaded, the key semantic constraint second, the duplication warning third, and the endpoint last. No sentence is 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?

A mutation tool with no output schema and full schema coverage; the description covers purpose, key/value semantics, and the column-order prerequisite. It stops short of stating what the call returns or how an existing key_column is handled, which are the remaining gaps.

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 3 is the baseline. The description earns a bump by cross-referencing goformz_get_datasource as the source of column order and restating key_column's role as the lookup key, adding workflow meaning beyond the field-level 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 and resource ('WRITE: add a row to a data source') and reinforces scope with 'Each call adds another row', which separates it from the update/get/list row siblings. 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?

Gives clear usage context by directing the agent to goformz_get_datasource for column order before supplying values. It does not explicitly say when to use this instead of goformz_update_datasource_row, so the exclusion is left 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 already declare write, non-idempotent, non-destructive, open-world semantics. The description reinforces non-idempotency ('Each call creates another form'), clarifies the result is a draft, and states that assignment cannot be applied later — genuinely useful context beyond annotations. Return payload is not described, but no output schema exists and the create result shape is not critical to invocation correctness.

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?

Front-loaded with the WRITE verb and core action, then constraints. Dense but every clause (draft, assignment-only-at-creation, field key semantics, non-idempotent repetition) carries information. The trailing 'POST /v2/formz' is minor noise but 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 6-parameter write tool with nested objects and no output schema, the description covers the mutation effect, assignment timing constraint, and the trickiest part (field value shape). An agent can invoke it correctly. It stops short of describing the returned form id/reference, a minor gap given no output schema.

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% (baseline 3), and the description adds real value on top: field keys are template field names/ids, values are field objects like {"text": "Acme"}, plus a pointer to goformz_get_form for exact field shapes. This resolves ambiguity about the nested 'fields' object that the schema only loosely explains.

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 new draft form from a template) with leading WRITE marker and scope qualifiers (draft, optionally pre-filled, optionally assigned). An agent can distinguish it from the read-only siblings like goformz_get_form and from goformz_update_form without opening schemas.

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?

Adds concrete context: assignment is only possible at creation, each call creates another form, and it points to goformz_get_form to learn field shapes before calling. It lacks an explicit 'use update_form instead when…' contrast, but the creation-vs-later distinction is clearly conveyed.

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 readOnlyHint=false and destructiveHint=false; the description resolves the tension by explaining the form itself is not changed and only a PDF artifact is produced. It also discloses the asynchronous job model and the queue/redirect indirection needed to retrieve the result, which annotations cannot convey.

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, zero waste: intent first, then the retrieval chain, then the endpoint. Every sentence carries operational information an agent needs.

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 compensates by telling the agent what the reply contains (queue_id) and where the file id lives (redirectUrl). Combined with the polling instructions, an agent has everything needed to complete the full export flow.

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%, with both form_id (GUID) and pages ("1-5,7,9" pattern) fully documented in the schema. The description adds nothing about parameter semantics, 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 ("start a PDF export of a form") plus the exact endpoint POST /v2/formz/{formId}/exports. The explicit "WRITE:" prefix separates it from the sibling reader goformz_get_pdf_export 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?

Gives an explicit downstream workflow: poll goformz_get_queue_item until Completed, then fetch via goformz_get_file using the id in redirectUrl. It does not say when to prefer goformz_get_pdf_export or goformz_get_form instead, so it falls just short of full alternative-routing 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description's value-add is limited to naming returned fields and the underlying GET endpoint. It does not describe behavior on a missing/invalid ID, which is the main unknown for a fetch-by-ID 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?

Two short sentences, no waste; the payload content is front-loaded and the endpoint reference is relegated to a trailing clause.

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 summarizes the returned shape (name, columns, indexed columns) and the endpoint. What's absent — error/not-found behavior and whether columns include metadata — is minor for a simple read-by-ID tool.

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 is fully documented as a GUID with a pattern, so the schema does the heavy lifting. The description only echoes it via the path template '{id}' and adds no format or sourcing 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 and resource ('Get one data source') and enumerates what is returned (name, columns, indexed columns), which distinguishes it from goformz_list_datasources by implying single-record retrieval. It's clear, though the distinction from list_datasources is only 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?

Usage is implied by 'one data source' versus the sibling list tool, but no explicit when-to-use or when-not-to-use guidance is given. An agent can reasonably infer it needs an ID from a list call first, but that is left 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 already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the REST path, with no information about failure behavior (e.g., missing row), permission requirements, or what the returned row representation looks like.

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 action and scope; nothing is wasted. The endpoint path is supplementary rather than essential, but it costs little.

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, fully documented read tool this is adequate to invoke correctly, and annotations cover safety. With no output schema, however, the description gives no hint of the returned row shape, leaving a real gap for an agent consuming the result.

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 both GUID parameters are documented in the schema with format patterns, so the baseline of 3 applies. The description's path template restates the parameter roles but adds no meaning 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 ('Get one data source row by id'), which clearly distinguishes it from the batch sibling list_datasource_rows. It does not explicitly name a sibling, but the 'one row by id' framing makes the scope unambiguous.

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 'by id' phrasing: fetch a single row when you have both a data source id and row id. There is no explicit statement of when to prefer this over list_datasource_rows or get_datasource, and no prerequisites mentioned.

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 and destructiveHint=false, so the safety profile is covered; the description adds the non-obvious behavior that the returned link is temporary and expires (pointing at linkExpiration) and that no file bytes are transferred. That is real behavioral context beyond the annotations, though it doesn't mention auth scope or whether the link is single-use.

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 clauses, front-loaded with the purpose, then the call-site guidance, then the critical caveat ('not downloaded here') before the endpoint. Every sentence carries information an agent would otherwise have to guess.

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 enumerates the returned fields (type, created date, link, linkExpiration), which is exactly what an agent needs to chain into a download. It is close to complete for a one-parameter read tool; only the expiry duration or link lifetime 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?

Schema description coverage is 100% and the single file_id parameter is fully documented as a GUID, so the schema carries the burden. The trailing 'GET /v2/files/{id}' confirms the id is a path segment, which is marginal added value; 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 and resource ('Get a file summary') and immediately enumerates what the summary contains (type, created date, temporary link). The line 'The file itself is not downloaded here' distinguishes it from an actual download/export operation, so an agent knows exactly what this returns.

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?

Names the concrete use cases ('an exported PDF or a form image/signature'), which gives an agent clear trigger conditions and implicitly links to the pdf-export siblings. It stops short of explicitly saying 'use goformz_get_pdf_export for the export record itself', so the routing is inferred 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing what the response contains — typed field values including table rows and signature/image references, plus status, assignment and template version. It does not mention how a not-found or deleted form is handled in the response, which keeps 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?

One dense sentence front-loads the resource and payload contents, with the endpoint appended. The 'GET /v2/formz/{id}' fragment is marginally useful for mapping to the REST API but is the least essential element; otherwise there is no wasted text.

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 carries the burden of describing return content and does so explicitly, and the deleted-form behavior is documented in the schema. What is missing is response-side edge behavior (not-found, deleted form excluded by default) and any pointer to how an id is obtained.

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 both parameters carry their own descriptions, so the baseline is 3. The description adds no additional semantics — notably it never mentions the include_deleted toggle or the GUID format — leaving the schema to do all 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 and resource ('Get one form') and enumerates the payload it returns: field values by type, status, assignment, and template version. Cardinality ('one form') plus the explicit field inventory cleanly separates it from goformz_list_forms and the other get_* siblings that target different resources.

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: an agent infers it should call this when it has a single form id in hand, versus goformz_list_forms when it does not. There is no explicit when-to-use, no prerequisite statement (e.g., obtaining an id), and no named alternative, so this stays at the minimum-viable 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying REST path, and does not describe the returned group shape or failure behavior (404, permission errors), which matters since there is no output 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?

Two short sentences with zero filler, and the core action ('Get one group by id') is front-loaded before the endpoint reference.

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 annotated single-record getter with one fully documented parameter, this is largely sufficient. The only real gap is the absence of any return-value or error-behavior note, which is unaddressed by the missing output schema.

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 single parameter is fully documented as a GUID with a regex pattern, so the schema does the heavy lifting. The description's 'by id' phrasing merely restates the parameter without adding format or validation 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 and resource with scope ('one group by id'), which implicitly distinguishes it from the sibling goformz_list_groups. It does not explicitly name the sibling, so it falls just 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: fetch a single group when you already have a valid group id. There is no explicit statement about what to do without an id (e.g., use goformz_list_groups) or any preconditions such as group access permissions.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful behavioral context: the tool returns metadata and a temporary download link that is only available once the PDF is ready.

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 definition is two sentences and front-loads the key behavior: metadata retrieval plus temporary link availability. The endpoint reference is compact and no sentence 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 two-parameter read-only retrieval with full schema coverage and no output schema, the description gives the essential return context: export metadata and the temporary download link once ready. It leaves some gaps around response fields and not-ready behavior, but the core call semantics are 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%, and the schema already documents both form_id and export_id as GUIDs with patterns. The description does not add parameter syntax or usage detail beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource: get metadata of a PDF export, including the temporary download link when ready. It distinguishes metadata retrieval from the actual export creation implied by sibling goformz_export_form_pdf, though it does not explicitly name that 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?

The phrase 'once the PDF is ready' implies this is used to check export status or retrieve the download link after an export has been initiated. However, it does not explicitly say when to use this versus goformz_export_form_pdf or goformz_get_file, nor does it state what to do if the export is not ready.

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 and destructiveHint=false, but the description adds meaningful behavioral context: it returns status and progressIndicator, and when Completed, redirectUrl points to a /v2/files/{id} result. This tells the agent what to expect and how to proceed, which is exactly the kind of detail annotations do not provide.

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 compact and front-loaded: it starts with the core action, gives the async-job example, explains the return fields and completion behavior, and ends with the endpoint reference. Every sentence adds useful 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?

With no output schema, the description compensates by naming the key return fields (status, progressIndicator, redirectUrl) and explaining how to consume redirectUrl. It also links the tool to the export and file-retrieval workflows, giving enough context to call it correctly.

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 single queue_id parameter is already documented as a GUID in the schema. The description does not add syntax or format details beyond the schema; it only restates the /v2/queue/{id} endpoint shape. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 ('Check a queued job') and identifies the originating operation ('the PDF export started by goformz_export_form_pdf'), so an agent can distinguish it from siblings without reading the schema. It also maps the next step to goformz_get_file when the job completes.

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 gives a clear usage context: checking an async job such as a PDF export, and directs the agent to goformz_get_file when the job is Completed. It does not explicitly state exclusions or alternatives for checking job status, but the workflow is clear.

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, non-destructive behavior, and openWorldHint=true, so the description carries a reduced burden. The endpoint path ('GET /v2/templates/{id}') adds minor confirmation of the read operation, but no permission, error, or response-shape context beyond that.

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 action and immediately followed by the endpoint. There is no wasted language and the key retrieval scope is clear.

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-resource GET with complete schema coverage and annotations covering safety, the description is sufficient to select and invoke the tool. It could add a small amount about what a template represents or expected failure behavior, but that is a minor gap for this complexity level.

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 sole parameter is already documented as a GUID template id. The description adds only 'by id', which is already captured by 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 and resource ('Get one template by id') and makes the singular lookup-by-id scope clear. It distinguishes retrieval from listing implicitly, but does not name a sibling such as list_templates, 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?

The phrase 'by id' implies the tool is used when a template GUID is already known, but there is no explicit guidance on when to use this versus list_templates or other retrieval tools. Usage is only implied.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the REST endpoint, not error behavior (e.g., not-found handling), auth requirements, or return shape.

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, zero waste, purpose front-loaded, endpoint appended as a useful locator. Nothing could be removed without losing 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 single-param read operation with full annotations and complete schema coverage, this is nearly sufficient. The notable omission is what the user object contains, since no output schema exists, but that is a minor gap for such a simple getter.

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%: the single user_id parameter is documented as a GUID with a regex pattern. The description's 'by id' adds no format detail beyond the schema, fitting 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?

The description states a specific verb and resource: fetch a single user by id, and adds the underlying REST endpoint. It implies a contrast with list_users via 'one user by id,' but never names the sibling tool 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 'by id' – call this when you already have a user GUID and need that single record rather than a list. No explicit when-to-use guidance, prerequisites, or alternative (list_users) is 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?

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint true), so the bar is lower, and the description still adds genuinely non-obvious context: each row carries an id, a keyColumn used for lookups, and a value that is a JSON-encoded array of column values rather than a plain object. It does not mention pagination totals or rate limits, which keeps it below 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?

Three tight sentences with zero padding: purpose first, then the row shape, then the endpoint. Nothing is buried and nothing is 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?

With no output schema, the description usefully explains what a returned row looks like, which is the single most important unknown for this tool. It could say more about whether paging metadata (next_page) is returned alongside rows, but that is a minor gap given the schema's page description references next_page.

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 every parameter (name prefix filter, page, page_size, datasource_id) is documented in the schema itself, so the baseline of 3 applies. The description adds nothing about the prefix-filter semantics or the next_page handoff that the schema does not already state.

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 rows of a data source") and immediately describes the shape of a row, which makes it directly distinguishable from the singular goformz_get_datasource_row and goformz_create_datasource_row siblings. It stops short of naming those siblings explicitly, so it is clear but not maximally differentiated.

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 "List" — an agent can infer this is the enumeration tool versus the single-row getters, but the description never says when to prefer it, when not to (e.g. when you already know the row id), or what a reasonable page size workflow looks like.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered without the description. The description adds useful domain context (what a data source is) and names the underlying endpoint, but says nothing about pagination flow, result volume, or how filtering behaves — areas the agent may still care about.

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, front-loaded with the resource and its definition. The trailing 'GET /v2/datasources' is slightly redundant implementation detail but arguably useful for developers debugging the API.

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 no-required-parameter list tool with full schema coverage and annotations, the description is adequate to invoke it correctly. However, with no output schema present, it gives no hint about what a returned data source record contains (id, name, fields), leaving the agent to discover the response shape empirically.

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%; name prefix filtering, page, and page_size (1-100, default 25) are all documented in the schema with defaults and ranges. The description adds no parameter meaning beyond that, which is acceptable at this coverage level but earns only the 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 (List) and resource (data sources), and adds a parenthetical definition — lookup tables feeding dropdown and database fields in templates — that tells an agent what a data source actually is. It does not explicitly contrast with siblings like goformz_get_datasource or goformz_list_datasource_rows, so it falls short of full 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 statement of when to use this versus goformz_get_datasource (single item) or goformz_list_datasource_rows (rows within a source), nor any preconditions or exclusions. An agent must infer usage from the tool name and the sibling list alone.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: the response omits field values, includes assignment and status, and the underlying endpoint is GET /v2/formz. It stops short of describing pagination behavior or result-set size expectations.

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?

Four short sentences, each carrying distinct information: identity/contents, the field-value exclusion with a redirect, the filter set, and the endpoint. Themost decision-relevant facts (what it returns and what it does not) are 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 7 optional params, no output schema and a safe read-only annotation set, the description covers the essentials by enumerating returned fields and the excluded field values, which substitutes for a missing output schema. Pagination and sorting behavior are left entirely to the schema, a minor remaining gap rather than a blocking one.

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 every one of the 7 parameters is already documented, including enum values, defaults and the next_page paging hint. The description only restates three filters (name prefix, status, last-updated date) without adding format or interaction details, so the schema does the heavy lifting and 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 forms') and immediately disambiguates the domain term: forms are 'filled-in instances of templates', which separates it from the template-listing siblings. It also enumerates what each item contains (name, status, last update date, assignment), so the agent knows exactly what this call 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?

Explicitly routes the agent away from over-relying on this tool: 'Field values are NOT included: call goformz_get_form for those' gives a clear when-not plus a named alternative. It also names the supported filter axes. It does not address the nearest listing sibling (goformz_list_template_forms) or say when listing forms per template is preferable, so it falls short of a full 5.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds only the raw endpoint (GET /v2/groups) and the group/forms relationship note; it says nothing about result volume, ordering, or pagination behavior beyond what the schema documents.

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 clauses, zero filler, with the resource and the parenthetical clarification front-loaded. Every element 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 zero-required-parameter list tool with a fully documented schema and annotations covering the safety profile, the description is nearly sufficient. The remaining gap is that it doesn't sketch the return shape (group objects with ids) needed to chain into goformz_get_group.

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%, with name, page and page_size all documented in-schema, including the next_page continuation hint. The description adds no parameter detail, 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 user groups") and adds the domain note that forms can be assigned to a group, which explains what a group is. It doesn't distinguish itself from the sibling goformz_get_group (single-group retrieval), leaving that inference to the name.

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 "List" versus the sibling get_group, but the description never says when to call this instead of goformz_get_group or goformz_list_users, nor does it mention prerequisites or the pagination workflow.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful disclosure beyond that — that field values are omitted from the response — plus the underlying endpoint, but says nothing about pagination behavior or result limits beyond what the schema carries.

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: what it lists and which fields come back, the key exclusion, and the endpoint. It is front-loaded and every sentence carries information an agent can act on.

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 responsibly names the returned fields (name, status, last update date) and flags the omission of field values, which is the main ambiguity for a forms-listing tool. Pagination and filtering are fully covered by the schema, so only a brief note on result-set behavior would improve it.

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 every parameter, including the filter/sort/page options and the GUID pattern for template_id, is documented in the schema itself. The description adds no parameter-level meaning beyond the templateId appearing in the path, 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 and resource with a clear scope qualifier: 'List the forms created from one template', plus the endpoint. That scope phrase implicitly separates it from goformz_list_forms, but the description never names that sibling or states the distinction outright.

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 scope and the note that field values are excluded, which hints that goformz_get_form is the tool for field data. There is no explicit when-to-use or when-not-to-use statement, and no mention of prerequisites such as needing a valid template id.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the result is a lightweight (id, name) projection, which is useful, but says nothing about pagination behavior or ordering. Against an annotated tool, a 3 is appropriate.

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 purpose and followed by the routing hint. The trailing 'GET /v2/templates' is mildly redundant but harmless context.

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, and the description compensates by naming the returned fields (id, name). Pagination and filtering are covered by the schema. Adequate for a simple read-only list tool, though it could note that results are paginated.

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 name prefix filter, page, and page_size semantics are already fully documented in the schema. The description adds no parameter meaning beyond that, which matches the baseline for complete schemas.

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+resource: 'List the form templates of the account' plus the returned fields (id, name). It distinguishes itself from goformz_list_template_forms by clarifying that a template id is needed to list that template's forms. It does not explicitly separate itself from goformz_get_template, though the scope difference is implied.

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 a template id to list its forms or to create a form' routes the agent toward goformz_list_template_forms and goformz_create_form after a lookup, which is a clear usage pattern. No explicit when-not-to-use or mention of paginating vs. fetching a single template by id.

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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful context beyond annotations by naming the GET /v2/users endpoint and listing the fields returned, though it does not discuss pagination or auth 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?

Two compact sentences with zero waste; the purpose and the practical reason to call it are front-loaded, and the endpoint is appended cleanly.

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 complete schema descriptions and rich annotations, this is complete enough. The lack of an output schema is offset by the description's summary of returned 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?

All three parameters have complete schema descriptions, so the schema already documents filtering and pagination. The description adds no parameter-level detail, which matches the baseline 3 when schema coverage is 100%.

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 users') and adds the returned fields (id, username, first and last name). It is clear but does not explicitly differentiate from the sibling get_user tool for retrieving a single user.

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 gives a clear use case: a user id is needed to assign a new form, which explains why an agent would call this list tool. It does not name alternatives or exclusions, such as using get_user for a single known user.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description restates "Read-only" (redundant) but does add genuinely new context: the webhook fires on the form.complete event for a template, and the underlying endpoint. It says nothing about pagination limits or what a webhook record contains, so it adds moderate rather than rich 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?

Three short sentences: the resource and event first, then the mutation profile, then the endpoint. Every sentence 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?

With no output schema and full schema coverage on the three pagination/filter parameters, the description covers what an agent needs to call it correctly for a read-only list. The one soft spot is slight ambiguity about whether the tool returns only form.complete webhooks or all webhooks, which it never resolves.

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/page_size/template_id are already fully documented, and the baseline is 3. The description still adds meaning by explaining that a webhook is tied to a template (clarifying what template_id filters on) and by implying the list is scoped to form.complete events.

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 webhooks") plus the triggering event (form.complete on template completion), which no sibling tool covers. The GET /v2/webhooks reference pins the exact operation, so an agent can distinguish it from the list_* form/template/user tools 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: an agent should call this when it needs to inspect webhook registrations, and the event description scopes what those webhooks are. However, there is no explicit when-to-use/when-not-to-use statement and no alternative named, so the routing guidance is left 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 already declare destructiveHint=true and idempotentHint=true, but the description adds material context: completing a form can trigger the template's completion workflows and webhooks, and re-opening returns it to draft for editing. This is a meaningful side-effect disclosure beyond the structured hints; only permissions and error behavior are left 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 with zero waste. The write nature and the two actions are front-loaded, and the endpoint is appended efficiently.

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 mutation with rich annotations and no output schema, the description covers what the tool does and its key side effects. It does not mention what a successful response contains or any permission requirements, but those are minor given the annotation coverage.

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 both form_id and status are already documented, including the enum meanings. The description reinforces the purpose of each status but adds no syntax or format detail beyond what the schema provides, 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 states a specific verb (mark complete or re-open) and resource (a form), plus the exact endpoint. It distinguishes lifecycle status change from generic edits by explaining that re-opening makes the form editable, though it never names the sibling edit tool 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 two enum values: use it to finish a form or to re-open a completed form so it can be edited. However, it does not explicitly say when not to use it or route the agent to goformz_update_form for editing fields, leaving alternatives 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?

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds important behavioral detail beyond those annotations: replacement is whole-row, so omitted columns are not preserved. It does not discuss permissions, rate limits, or response behavior, but the critical destructive semantics are disclosed.

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 a single compact sentence with zero waste. The WRITE marker and replacement rule are front-loaded, and the endpoint is included 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 destructive write tool with no output schema, the description gives the essential replacement semantics and endpoint. It is complete enough to call correctly, though it does not describe the expected response or error behavior.

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 all four parameters are already documented. The description adds meaningful semantics beyond the schema by clarifying that the entire row is replaced and every column must be supplied, which reinforces the correct interpretation of the values array and key_column.

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: replace a data source row's key and values. It explicitly flags this as a WRITE operation and names the API endpoint, which distinguishes it from read-oriented siblings such as goformz_get_datasource_row and goformz_list_datasource_rows.

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 clearly explains the operational context: the whole row is replaced and every column must be sent. This gives strong guidance for when this tool is appropriate versus a partial update. However, it does not explicitly name sibling alternatives such as goformz_create_datasource_row or state when not to use this tool.

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 flag the call as destructive and idempotent, and the description goes further by explaining partial-update semantics, that null clears a field, that status/workflows are untouched, and the exact remediation path for workflow re-runs. That is the kind of consequence detail an agent needs before a destructive mutation.

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?

Front-loads the mutation marker and primary effect, then layers the exclusion, the alternative workflow, and the endpoint in roughly decreasing priority. Three sentences, none of them 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 destructive, nested-object mutation with no output schema, the description covers effect scope, partial-update behavior, side-effect exclusions, and the correct alternative route. Nothing an agent needs to call it safely 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%, so the baseline is 3; the description adds meaning by stating that only supplied fields change (partial-update semantics) rather than replacing the whole field map. The null-clears behavior and GUID keying are already in the schema, so it does not fully double the value.

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 ('WRITE: change a form's name and/or field values') and immediately scopes it as a partial update. It explicitly distinguishes itself from goformz_set_form_status, so an agent can route between the two mutation tools without opening either 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 an explicit when-to-use ('change a form's name and/or field values') and when-not-to-use ('Does NOT change the status and does not trigger workflows'), plus a concrete alternative sequence using goformz_set_form_status for workflow re-runs. No inference required.

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