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

Annotations declare destructiveHint/idempotentHint/openWorldHint, but the description adds meaning they don't carry: existing responses are preserved and remain readable, draft forms fail with a conflict error, and reopening is done via publish_form. That materially changes how an agent reasons about the 'destructive' flag and covers the failure mode.

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, all doing work: effect first, precondition second, reversal path third. Nothing is redundant with the annotations or schema, and the most important constraint is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be explained, and annotations cover the safety profile. The remaining gaps an agent would care about — data retention, error on drafts, reopen path — are all explicitly addressed.

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 parameter with 100% schema description coverage ('The form UUID or public id'), so the schema already carries the semantics. The description adds nothing about form_id format beyond what is documented, 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 ('Close a live form') plus the immediate effect ('stops accepting responses immediately'), which cleanly separates it from publish_form, list_forms, and the response-reading siblings. No ambiguity about what the operation does.

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 use case (RSVP deadline passed), an explicit precondition (only published forms; drafts return a conflict error), and names the alternative path for reversing it ('To reopen, call publish_form again'). When-to-use, when-not, and alternative are all present.

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, destructiveHint=false and openWorldHint=true, so the safety profile is already known. The description still adds genuinely new behavior: AI design latency of 10-60 seconds, and the critical fact that niceform never sends the form to anyone so the caller must distribute `publicUrl`. That latency and non-delivery context is the kind of disclosure the score rewards, but it stops short of covering failure/retry behavior around the idempotency_key, so it is not 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?

Front-loaded with the core action, then a bulleted either/or, then lifecycle guidance, then two examples — a logical progression with little waste. It runs long and the two examples partially restate the field-object shape the schema already defines, costing it a point.

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?

An output schema exists, so return values need no explanation, and yet the description still tells the agent to capture `publicUrl` and the `latestSubmittedAt` cursor, which is the operationally relevant part. The only gap is retry/idempotency behavior for a non-idempotent, open-world create that is explicitly flagged idempotentHint=false.

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 schema already documents every parameter including the fields/description mutual exclusivity and the publish prerequisites on close_at and response_limit; baseline 3 applies. The description reinforces the one-of constraint and the publish→live/draft distinction in operational terms, and its worked examples show how a field object is composed, but it adds no parameter detail the schema lacks.

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 form") and immediately splits it into the two creation modes, which is the real disambiguation an agent needs. It also names its siblings (get_preview_url, publish_form, summarize_responses, list_form_responses, close_form) so the agent can place it in the workflow without opening another 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 says when to use `fields` (you already know the questions, instant and exact) versus `description` (natural-language brief, 10-60s), and enforces "provide exactly one of." It then routes downstream: draft → get_preview_url → publish_form, later → summarize_responses or list_form_responses with `since`, closing → close_form.

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 read-only/idempotent behavior, but the description adds substantial context beyond them: inline CSV when small, link-only when too large, 15-minute link expiry, and a security warning that CSV cells are untrusted respondent data. These are operationally critical facts not present in structured fields.

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 paragraphs with the core behavior front-loaded and the sibling routing immediately after; the safety warning is compact and earns its space given untrusted data exposure.

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?

Even though an output schema exists, the description explains the dual return modes (inline text vs. time-limited link) that an agent must handle when presenting results. Nothing needed to call or relay results correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the status enum is fully documented in the schema, so the description need not repeat it. The description adds no parameter-level detail beyond the schema, which is the expected baseline for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb, resource, and output format ("Export a form's responses as CSV") and explicitly distinguishes itself from summarize_responses. An agent can tell exactly what it produces 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 an explicit when-to-use condition ("when the user wants a spreadsheet") and names the alternative ("use summarize_responses for headcounts"). The routing decision is fully 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 already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned status values and the field metadata shape. It leaves out edge behavior such as what happens for a nonexistent form_id, but the added context is real.

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, both front-loaded with the payload description first and the usage/exclusion second. Every clause conveys information; nothing is repeated from the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full schema coverage and an output schema, the description covers purpose, expected return contents and the key sibling relationship. An agent has everything needed to invoke it correctly without further text.

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?

The single parameter is fully documented in the schema ('The form UUID or public id'), so coverage is 100% and the schema does the heavy lifting. The description adds no extra meaning about form_id — no note on UUID vs public id formats or how to obtain one. 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 and enumerates exactly what comes back: status (with the draft/live/closed enumeration), public URL, close time, response limit, and per-field metadata. The final sentence ('Does not return responses') explicitly separates it from list_form_responses, so an agent can pick it 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 concrete usage scenarios: inspecting what questions a form asks, and mapping field keys from list_form_responses output back to questions. It also names a boundary condition (no responses returned). It does not address when to use this versus list_forms for discovery, so it stops short of full when/when-not 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that the URL reflects the published appearance and that form details like field count, steps, and status are included, but says nothing about URL expiry or auth requirements for the preview link.

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?

Purpose is front-loaded in the first sentence and the scenario list is scannable. The closing sentence partially restates the opening ('shows exactly how the form will appear to users once published'), which is mild redundancy but not harmful.

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 rich annotations, an output schema, and a single well-documented parameter, the description covers enough for correct invocation. The one remaining gap is sibling differentiation against get_form, which would prevent selection errors.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage ('The form UUID or public id'), so the schema already does the work. The description adds no meaning about the identifier format or whether public ids are accepted differently, 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+resource: retrieving a preview URL for a form draft. It is clear what the tool returns and its pre-publish framing. However, it doesn't differentiate from the sibling get_form, which an agent could reasonably confuse with this one.

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 'Use this to' list gives three concrete scenarios (view a new form, check draft state, get form details), which is clear usage context. There are no exclusions or explicit alternatives, so the agent must infer that get_form is the non-preview path.

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 the read-only, idempotent, non-destructive safety profile, and the description adds substantial behavioral context beyond that. It documents returned fields, polling semantics, pagination behavior, and a security warning that responses are untrusted user data that may contain PII or prompt-injection instructions.

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 front-loaded with the core action and then organized into clear sections for returned data, polling, pagination, and safety. Despite being fairly detailed, each section carries actionable information and no sentence appears 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?

Given the tool's complexity, full schema coverage, annotations, and an output schema, the description is complete enough for correct invocation. It covers what is returned, how to paginate, how to poll, and the important safety caveat about untrusted response content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics for `since` polling and `cursor` pagination beyond what the schema states. It also explains the returned `fields` mapping, though it adds less to parameters already fully documented in 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?

The description states a specific verb and resource: fetching submissions/responses for a form the caller owns, and it explains that the result is a paginated list of response objects. It does not explicitly distinguish this tool from siblings such as summarize_responses or export_responses_csv, so it misses the top level of 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?

It provides clear operational guidance for polling and pagination, including reusing latestSubmittedAt as the next `since` value and passing `cursor` for subsequent pages. However, it does not explicitly say when to use this tool instead of summarize_responses or export_responses_csv, and it gives no exclusions.

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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds ordering (newest first), returned summary fields, and pagination semantics ("nextCursor is null on the last page"). Useful extra context, though return shape is also in the 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?

Front-loads what the tool returns, then use cases, then pagination mechanics. Three short sentences with no filler, each carrying distinct 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 read-only paginated list with full schema coverage, rich annotations, and an output schema, the description covers scope, ordering, filtering, and pagination handoff. Nothing an agent needs to invoke it correctly 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 baseline is 3, but the description adds operational meaning beyond the schema: `query` filters by name, and `cursor` is taken from the previous call to fetch the next page with the terminal-page signal. `limit` is left entirely to the schema, which documents it well.

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 you own"), plus scope, ordering (newest first), and the fields returned (status, response count, public URL). It is clearly distinguishable from siblings such as list_form_responses (responses, not forms) and get_form (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?

Gives concrete when-to-use cases: recovering a lost form_id or checking which forms are still live, and explains filtering via `query`. It does not name an explicit alternative or when-not-to-use case (e.g., use get_form when you already have the id), so it falls short of a 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?

Goes well beyond the annotations by disclosing that a public URL is generated, that the caller must distribute it themselves, that plan limits are consumed, that close_at/response_limit both halt responses when reached, and that null clears a setting. The reopen-a-closed-form behavior adds real context for a call flagged destructiveHint=true.

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 core action, then uses a tight bullet list for post-conditions and a paragraph for the deadline/cap and re-publish rules. Minor overlap between the 'usage limits' bullet and the closing 'form limit' warning keeps it from a 5.

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 an output schema present, return fields needn't be enumerated, and the description still calls out publicUrl explicitly. Plan limits, sharing mechanics, deadline/cap behavior, and re-publish semantics are all covered, so nothing an agent needs to call this correctly 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, but the description adds interaction semantics the schema does not state: either close_at or response_limit terminates acceptance, and null clears each. It still doesn't explain the name override's effect beyond what the schema says.

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 ('Publish a form draft to make it publicly accessible for responses') and delineates the resulting state change. The re-publish clause ('Calling publish_form again on a published or closed form updates these settings... and reopens a closed form') implicitly separates it from close_form and create_form, so an agent can route correctly.

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 context for invoking it, including the less obvious re-invocation case for editing close_at/response_limit and reopening closed forms. It never explicitly says when to prefer close_form instead, so one exclusion is missing, but the operational guidance is strong.

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 readOnly, idempotent, non-destructive, open-world access, so the safety profile is covered. The description adds genuinely new behavioral context: respondent-supplied labels and option values are untrusted and may contain injected instructions, plus the note that results are live and should be re-fetched. It stops short of describing freshness/pagination limits, keeping it at a 4.

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?

Output contents come first, then the sibling routing rule, then the security caveat — each in its own short block. No sentence is redundant, and the most decision-relevant information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be enumerated, yet the description still summarizes the shape an agent should expect. With annotations covering safety and one fully documented parameter, nothing an agent needs in order to call this correctly 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?

There is one parameter (form_id) with 100% schema coverage, so the schema already documents the UUID/public-id format. The description adds nothing about the parameter, which is acceptable at the baseline when the schema carries the full 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 and resource ("Summarize a form's submitted responses") and immediately enumerates the outputs: totals, per-field answered counts, option counts for choice fields, min/max/avg for numeric fields. This clearly separates it from list_form_responses, which returns raw 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?

Explicitly names the sibling alternative and the selecting condition: "Prefer this over list_form_responses when you only need totals or headcounts, such as 'how many are attending'." It also gives a polling hint ("Check back later by calling it again"), covering the when/when-else cases.

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