QUESTIONSTAR

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

Annotations only declare the generic mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds substantive context: the reply is verified by readback and returns the rule as actually stored, plus the auth requirement and the explicit ordering error. That is real value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then packs constraints and parameter detail into one dense paragraph with no filler. It is long and somewhat run-on, but nearly every clause carries operational weight.

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?

Covers the ordering invariant, auth requirement, operator set, value formats, match modes, and verification behavior. With an output schema present, no return-value detail is needed. 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%, but the schema's condition sub-fields are undocumented. The description supplies the full operator vocabulary, the value convention (numeric option code for choice questions, literal for text/number, omitted for is_empty/is_not_empty/was_displayed), and confirms match semantics. It clearly adds 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+resource ('Adds a display-logic rule to a survey') and immediately defines the scope as SHOW/HIDE of a target question based on earlier answers. This distinguishes it from the sibling add_jump_logic_rule (which routes rather than reveals/hides).

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 strong conditions for correct use: source questions must come strictly before the target (a later source is an explicit error), and the edit-survey right is required. It does not, however, explicitly contrast when to choose this over add_jump_logic_rule, leaving that discrimination to inference.

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

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

Annotations declare a safe non-destructive mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds genuinely non-structural context: append-at-end behavior, a verified readback of the stored page number, the edit-survey right requirement, and the markComplete completion-counting effect. It does not discuss failure modes or what happens on repeated calls against non-idempotent behavior, which is the remaining gap.

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 definition and then packs distinctions, placement rule, and permission into a dense block with no filler sentences. It is on the long side and layers several concerns (routing, completion stats, placement, auth) into one paragraph, which slightly taxes scanning, but every clause carries information.

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

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

With an output schema present, the description need not explain return values, and it covers everything else an agent needs: the tool's role in branching, the markComplete effect, the prerequisite page ordering, and the required permission. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents code, message, and markComplete with their formats and defaults. The description largely restates markComplete's completion semantics and re-explains the message field, adding workflow linkage (using the returned pageNumber as a jump target) but little parameter meaning beyond the schema. 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 ('Adds a BRANCH-FINAL page to a survey') and immediately disambiguates it from the global-ending sibling set_end_message and from add_jump_logic_rule target='end'. An agent can identify exactly which page concept this creates 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 contrasts the alternative routing mechanism (global ending via set_end_message vs. a jump to THIS page's number) and names the condition that selects each. It also gives the placement precondition (branching source question must sit on an earlier, separate page) and the required permission, so when-to-use 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?

Goes well beyond the annotations: firing timing (on source page submit), a hard forward-only constraint, same/backward targets being an explicit error, readback verification of the stored rule, and the edit-survey right requirement. Crucially it clarifies that target='end' is a legitimate completed response, not a screen-out — semantics an agent could easily get wrong.

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 purpose, then constraints, then parameter behavior — dense and mostly waste-free. Slight redundancy with the schema's own target/operator descriptions, but nothing that misleads.

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

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

For a mutation tool with an output schema (readback), the description covers everything an agent needs: prerequisites (edit right, page ordering), edge cases (backward target error, 'end' semantics), and verification behavior. Return format is delegated to the output schema appropriately.

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 real meaning: operator/value mirror display-logic conditions (option code for choice, literal for text/number), and target must be strictly after the source page. It re-explains target's definition already in the schema, so it is not fully additive.

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 ('Adds a jump (branching/skip) rule to a survey') and immediately distinguishes itself from the sibling add_display_logic_rule by contrasting jump/skip vs display semantics. An agent can tell exactly what this creates and how it differs from the display-logic tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use guidance: place the branching question on an earlier, separate page (pointing to add_survey_page), forward-only targets, and what happens with target='end'. It also names the alternative (add_display_logic_rule) whose operator/value semantics this tool reuses.

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?

Beyond the annotations (readOnly false, openWorld true, idempotent false, destructive false), the description discloses that omitted fields keep type defaults, choice/dropdown/sorting/matrix types require explicit options/rows to avoid placeholder seeds, unsupported types return errors, and the reply is verified by re-reading through get_survey. This adds substantial behavioral context 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?

The description is front-loaded with purpose and is dense with necessary detail, but it reads as one long paragraph, making the extensive type list and conditional rules harder to scan than a bulleted structure would be. Every sentence is substantive, though the formatting could be improved.

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 a 9-parameter mutation tool with nested objects and many structural type variants, the description covers placement rules, default behavior, required explicit inputs, unsupported types, branching-logic constraints, permission requirements, and readback verification. With an output schema present, return-value details are appropriately left to the 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%, but the description adds meaningful semantics: it enumerates supported type keys, explains that fields apply by presence and otherwise keep type defaults, clarifies when options[] and rows[] must be supplied, and explains the page parameter's 1-based numbering and append-to-last-page default. This goes well beyond the schema's field-level descriptions.

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 opening sentence states a specific verb and resource: 'Adds a question to a survey and returns its variable code (Q1, Q2, …).' It distinguishes the tool from add_survey_page by noting add_question never creates pages, and from update_question by its creation-only scope.

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 explicit prerequisites: create pages with add_survey_page first, a non-existent page number is an error, and the edit-survey right is required. It also names unsupported types that must be set up in the QUESTIONSTAR UI and describes the branching-logic constraint that sources and targets must be on separate later pages.

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=false, destructive=false, idempotent=false, and openWorld=false. The description adds important behavioral context beyond those annotations: 'Verified by readback,' the edit-survey permission requirement, and the page-boundary timing rule for show/skip logic, though it does not fully cover error or reversibility 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?

The description is front-loaded with the core action and return shape, then proceeds through optional parameters, branching behavior, related tools, and prerequisites. It is longer than typical but the branching and routing clauses are relevant to correct use, so it stays efficient despite the density.

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 explained, but the description still summarizes the returned page list. It also covers position behavior, title optionality, prerequisite permissions, verification, and the relationship to add_question and add_end_page, making it complete for this 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 description coverage is 100%, so all three parameters are already documented in the input schema. The description repeats title optionality and position insertion/default-append semantics, but adds no new syntax or constraints beyond what the schema provides, making the baseline score of 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 opens with a specific verb and resource: 'Adds a page to a survey,' and immediately distinguishes the operation from add_end_page and add_question later in the text. It also names the returned payload fields, so an agent knows what this tool does and what it 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?

It explicitly routes content placement to add_question and end-page creation to add_end_page, giving clear alternatives. It also states the optional nature of title and position, the default append behavior, and the required edit-survey right, covering when and how to use the 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 already flag destructiveHint/readOnly=false/idempotent, but the description goes well beyond them: per-survey material lands on a dedicated copy named 'API Layout {code}', shared/system templates are NEVER modified, repeated calls update the same dedicated template, customJavascript runs in respondents' browsers on the public page, and unconfirmed customJavascript/customLayout writes nothing and returns a preview. It also discloses server-side readback verification via the 'applied' flag.

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 critical routing and safety information (what it does, what it doesn't, confirm requirements) is front-loaded in the first sentences. The remaining text is dense with parenthetical asides that reward careful reading but make the block long and hard to scan in a single pass.

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

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

For an 8-parameter, destructive, open-world mutation tool with an output schema, nothing an agent needs to call it safely is missing: prerequisites (confirm), token sourcing, idempotency, blast radius (public page, dedicated template copy), and the verification signal are all covered. Return-value details are correctly left to the 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%, so the baseline is 3, but the description adds real semantics: tokens merge BY NAME with unnamed base tokens preserved, a name passed to both set and remove ends up removed and counts only in tokensRemoved, and unknown/typo names surface as unknownTokens/tokensNotUiControlled. The confirm and removeTokens semantics overlap with the schema, so the added value is incremental rather than comprehensive.

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?

Starts with a specific verb+resource ('Applies a LAYOUT') and immediately disambiguates scope with a parenthetical definition of what a layout is (colors, fonts, buttons, CSS) plus an explicit negative boundary — 'this does NOT copy survey content; use clone_survey for that.' An agent can distinguish it from clone_survey and from list_layout_templates without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: use clone_survey for content, list_layout_templates to source templateID, list_layout_tokens for token vocabulary, and 'use customCSS/customJavascript/customLayout only for what tokens don't cover.' It also states precisely when confirm:true is required versus when calls apply directly, and when removeTokens is appropriate (typos/unwanted overrides).

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

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

Annotations only declare idempotentHint/destructiveHint; the description adds far more: reversibility, that it is not a permanent delete, that archived surveys vanish from list_surveys and free a concurrent-survey slot, that get_survey still serves them with archived:true, and that the archived state is re-read server-side before success. Consistent with, and far richer than, the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and its scope in the first clause, then layers prohibitions and edge-case outcomes. Dense with parentheticals but every sentence carries distinct, decision-relevant information with no padding.

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?

Covers preconditions, refusals, alternatives, downstream effects on listing/slots/retrieval, idempotent re-archive behavior, and server-side verification. An output schema exists so return-format detail is unnecessary; nothing an agent needs to invoke 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 description coverage is 100% and the single `code` parameter is fully documented (8-character code, sourced from list_surveys) inside the schema. The description adds no parameter-level detail beyond what structured data already supplies, 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 precise verb and resource ('Archives a DRAFT survey ... to the recoverable bin') and immediately scopes it to never-running, response-free surveys. This cleanly separates it from siblings like delete_survey and pause_survey without the agent needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (only DRAFT surveys) and when-NOT (refuses running surveys, refuses surveys with responses), and names the alternative for each blocked case: 'stop them first with pause_survey' or handle in the app. Nothing 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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without prose. The description adds the one genuinely useful behavioral fact — that the result is a boolean indicating completion status — but says nothing about what counts as 'completed' (partial vs. screened-out vs. finished) or about lookup behavior for a missing response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler or redundancy. It is appropriately sized for a narrow boolean check, though the thinness is a completeness problem rather than a conciseness virtue.

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 the description need not explain the return value, and both parameters are fully documented in the schema. What is missing is the operational context: when this check is the right call versus the response-reading siblings, and any caveat about responses that don't exist yet.

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%: 'code' is documented as the 8-character publication code with a pointer to list_surveys, and 'personalizedID' is documented including the system-generated fallback. The description adds no parameter-level meaning beyond that, 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 (returns/checks) and a precise resource (whether the respondent's response for a given survey is completed), so the operation is unambiguous. It does not, however, differentiate itself from siblings such as get_survey_response or get_response_counts, which an agent could plausibly reach for instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description contains no when-to-use guidance, no exclusions, and names no alternative. It never explains when a boolean completion check is preferable to fetching the full response via get_survey_response, leaving the agent to infer the distinction from the name 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?

Far exceeds the annotations: it discloses fresh identifiers, the 'created' vs 'already-created' states, idempotency-via-cloneID retry semantics, rollback on mid-way failure ('removes the half-created survey and reports that nothing was created'), and readback verification. The annotation idempotentHint=false is not contradicted but refined — the tool is only idempotent when cloneID is supplied.

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?

Core action and source addressing are front-loaded, and each sentence carries functional content (states, retry, rollback, readback). It is dense and slightly over-long — the readback sentence restates return values already implied — but nothing is 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 mutation tool with a full input schema and an output schema, this covers everything an agent needs: how to identify the source, how to make retries safe, what states to expect, and how failures are handled.

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 genuine meaning: sourceCode/sourceSurveyID are mutually exclusive alternatives for identifying the source, and cloneID's role as the idempotency key for safe retries is spelled out behaviorally rather than just as a UUID format.

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 (clone) + resource (survey) + explicit scope: a complete copy including pages, questions, logic, quotas and translations, landing as a fresh NOT-yet-started publication. This plainly distinguishes it from create_survey and the other siblings 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 clear operating context: the source is addressed by sourceCode or sourceSurveyID (the latter from list_surveys) and must belong to the account or be a public example survey, plus an explicit retry-with-same-cloneID recipe after a timeout. It stops short of naming an alternative tool for the non-duplicate creation case, so it is strong context rather than full routing.

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 cover safety (destructive/idempotent/openWorld), and the description goes well beyond them: shared structure/logic/dataset with text overlay, respondent language selection via ?Language=<code>, source-text fallback, seeded translation worklist, the ru/de/en-only limit on built-in service-text localization, and verification by re-reading the stored set. It even discloses the destructive edge implicitly via 'upserts translations of an existing layer'.

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 sentence one and nearly every clause carries information (fallback, ordering, service-slot limits, idempotence). It is nonetheless a dense, run-on block with caps emphasis and parenthetical asides that make it harder to scan than it needs to be.

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 explained, yet the description still tells the agent that the reply lists unlocalized service slot keys. Combined with auth requirements, ordering constraints and fallback behavior, an agent has everything needed 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 coverage is 100% so the baseline is 3, but the description adds addressing semantics the schema does not: the four translations[] item shapes ({question, text}, {question, option:<code>, text}, {question, row:<n>, text}, {target:..., text}) and the named target values. It doesn't restate the catalog-vs-unknown-code rules for direction/languageName, but those are already fully 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?

States a concrete verb+resource ('Adds a LANGUAGE LAYER to a survey ... upserts translations') and immediately defines the domain concept (a language is a layer on the same survey, not a separate survey). No sibling tool does anything similar, so it is unambiguous which tool to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit sequencing guidance: 'Add languages LAST', what happens to questions added after the layer, and that re-running is an idempotent upsert to pick them up. It also states the prerequisite ('Requires the edit-survey right') and the for-other-languages follow-up call, so the when/how 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?

Adds substantial context beyond annotations: auto-creates the 'External for {survey}' list and unknown custom fields, PersonalizedID is not uniqueness-checked, links fall back to the generated internal ID, email fires only on explicit true, and the write is verified by readback. This goes well past destructiveHint/openWorldHint and materially affects how an agent should call it.

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?

Dense single paragraph with the primary purpose front-loaded; every clause carries information (side effects, defaults, return). It is longer than ideal and the nested parentheticals make it slightly hard to scan, but no sentence is 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 non-idempotent, destructive, open-world mutation with an output schema and a nested object parameter, the description covers the risky behaviours (auto-creation, invitation email, non-unique ID, readback verification). Nothing an agent must know before invoking 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 semantics the schema only implies: the uniqueness behaviour of personalizedID, its role in the personal link, and the exact sendInvitation trigger. That is meaningful value over the structured fields.

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: "Creates a respondent in the survey's respondent list." It distinguishes this tool from siblings like create_survey_response by naming the respondent list entity and by enumerating the side effects (auto-created list, custom fields). An agent can tell what it does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit conditional guidance for sendInvitation ("sent ONLY when explicitly true — leave it off unless the user clearly asked"), which is exactly the kind of default-trap an agent needs. It does not, however, contrast this tool with alternatives or state prerequisites beyond the optionality of PersonalizedID.

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

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

Annotations only declare readOnly=false, idempotent=false, destructive=false. The description adds real behavior beyond that: ownership and visibility ('owned by and visible to you'), the language default, a readback verification step through get_survey, and atomicity ('on failure nothing is left behind').

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 essential facts, but the empty-container idea is stated twice ('one page, no questions' and again 'created as an empty container; its questions, pages and logic are added by the authoring tools afterwards'), and the closing pointer to survey_quality_guidelines is tangential.

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, yet the description still covers creation scope, ownership, defaults, verification, failure behavior, and next steps. An agent has everything needed 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 coverage is 100% and the schema already documents both parameters, including the de default. The description's restatement of the language default adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource plus the initial state ('new empty survey (one page, no questions)') and the return value ('8-char code'), which cleanly separates it from clone_survey, list_surveys, and create_survey_response.

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?

Positions the tool in the authoring workflow explicitly: 'Build it up with add_question, then publish_survey,' naming the sibling tools that follow. It does not say when to prefer clone_survey or import instead, so it stops short of full 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?

Far exceeds the annotations, which only declare it is a non-idempotent, non-destructive write. The description adds externally-visible behavior: responses are stored with source 'external', technical data is set server-side and excluded from input, duplicate PersonalizedID causes failure, and the call performs a readback that costs one heavy-class request and requires a PersonalizedID to address the response.

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?

Well front-loaded — the external-source framing leads, followed by prerequisites, item structure, and failure/readback behavior. It is on the long side and partially re-states the nested items/personalizedID semantics already documented in the schema, but every sentence still carries information.

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

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

With an output schema present, return values need not be explained, and the description goes further by stating that the reply reports stored data rather than mere acknowledgement. Prerequisites and failure modes are covered; the only minor gap is that no auth/permission requirements are mentioned, though annotations cover the safety profile.

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 real meaning beyond the schema: question variables must come from get_survey, PersonalizedID is optional on create yet required for readback (and required on update), and isCompleted semantics are restated with server-set completion date. It does not add syntax detail for code/value 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 (creates a new response/result case in a survey) and immediately scopes it to responses collected outside the survey link, explicitly contrasting them with link-submitted responses. An agent can distinguish this from get/list/update_survey_response 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 when-to-use cases (paper questionnaire, phone/in-person interview, import from another system) plus the precondition that publication must be started. It also routes the agent to the alternative explicitly: if a PersonalizedID already exists the call fails, and update_survey_response should be used to modify.

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

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

Annotations only declare the coarse profile (destructive, non-idempotent, open-world); the description adds genuinely non-obvious behavioral detail: the preview performs a real outbound HTTPS POST, health grading semantics (2xx healthy, 0 unreachable, others refused), that unreachable blocks creation unless force, that other non-2xx warn but still create, readback verification before success, and the PII guarantee that contact fields are never sent.

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 purpose, then organized logically by preview/create flow, health grading, events, payload scoping, and verification. It is long, but the density is justified for a mutating tool with a non-obvious preview side effect; minor redundancy around the confirm flow 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?

An output schema exists so return values need not be described, and the description covers everything else an agent needs: the confirm/force decision rules, the side effect of the preview call, event semantics, payload inclusion rules, and success verification. Nothing material is missing for correct invocation.

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?

With 100% schema description coverage the baseline is 3, and the description adds meaning beyond the schema: what eventType values mean in terms of payload content, that includeFields defaults to ALL question variables when empty, and the 'Recieved' spelling rationale. It reinforces rather than merely repeats the schema, though it stops short of explaining useCustomID/answersAsText interactions.

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?

Opens with a specific verb+resource ('Creates a webhook') and immediately states the durable effect ('the survey's events are POSTed as JSON to your https URL from then on'). This is unmistakably distinct from delete_webhook, list_webhooks, test_webhook, and get_webhook_deliveries among the siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit two-step protocol (call without confirm for a preview, then with confirm:true), states when to use force:true, and routes the agent to complementary tools ('Fire a sample with test_webhook and watch health with get_webhook_deliveries'). It also names the condition that should block creation (unreachable target).

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 (destructiveHint, readOnlyHint) by enumerating exactly what is destroyed (the question's own answers), the non-obvious side effect of positional Q{n} renumbering for all later questions, which logic rules break and how they surface in logic.errors, the server-side re-read verification, and the required edit-survey right.

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 purpose and constrained by a single dense paragraph with numbered consequences; almost every sentence carries new information. The Q5→Q4 renumbering detail is arguably deeper than an agent needs pre-call, but nothing is truly redundant.

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

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

For a destructive, non-idempotent mutation with an output schema (so return values need no explanation), the description covers consequences, preview semantics, auth requirements, and downstream repair paths. 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by spelling out what the confirm:false preview actually contains (response count, dependent logic rules, remaining question count) and reinforcing the 'only after explicit user agreement' condition for confirm:true.

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?

Opens with a specific verb+resource ("Deletes a question from a survey") and immediately differentiates itself from sibling delete tools (delete_survey_page, delete_survey_response) by stating that other questions' collected data is unaffected. An agent knows exactly what is deleted and at what granularity.

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 defines the two invocation modes: omitted/false confirm returns a read-only preview of consequences; confirm:true performs the delete. It also routes the agent onward to get_survey for new naming and to add_display_logic_rule / add_jump_logic_rule for repairing broken logic.

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?

Beyond the annotations, the description discloses refusal conditions, required permissions, positional renumbering effects, readback verification, and the returned page-list content. This meaningfully expands on the destructiveHint and non-idempotent hints.

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: purpose and return value come first, followed by parameter meaning, constraints, renumbering behavior, verification, and permission requirements. Every sentence adds operational 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 destructive survey-page mutation, the description covers the action, return side effect, parameter constraints, permission requirement, failure cases, and post-delete renumbering. With an output schema present, the return-value summary is additional rather than necessary, but nothing important appears 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 relevant parameter behavior by explaining that page numbers are positional and later pages renumber after removal. The moveQuestionsTo requirement is also repeated in context, reinforcing when it must be supplied.

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 (deletes a page from a survey) and clarifies that it returns the current page list. It is clearly distinguishable from sibling operations such as delete_question, add_survey_page, and reorder_survey_pages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives important usage conditions: if the page has questions, moveQuestionsTo is required or the delete is refused; the last page cannot be deleted; and edit-survey permission is required. It does not name alternative tools or explicitly contrast when another page operation should be used instead.

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 destructiveHint/idempotentHint/readOnlyHint, but the description adds real behavioral detail beyond them: not-found is reported as not-found rather than an error, an unknown survey code is distinguished from an absent response, and a readback re-read confirms the deletion actually took effect.

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 irreversible warning and the intended use case are front-loaded, then error and verification semantics follow in a logical order. The readback sentence is slightly verbose but still carries information the caller needs, so nothing is wasteful.

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

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

For a destructive mutation with an output schema, the key omission would be error/edge-case behavior, and the description covers exactly that (not-found vs. unknown code vs. real deletion, plus readback confirmation). Nothing an agent needs to decide or call 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%, so both parameters (code, personalizedID) are already fully documented in the schema, including formats and provenance. The description only restates that deletion is keyed by PersonalizedID, adding no syntax or edge-case 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?

It states a specific verb and resource ("Permanently deletes a response") and pins the lookup key to PersonalizedID, so the operation is unambiguous. It does not name or contrast with siblings like update_survey_response or get_survey_response, 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?

"Irreversible — for erroneous or test responses" gives a clear intended use case and a strong implicit exclusion (don't use it for legitimate data). It stops short of naming alternatives (e.g., update_survey_response for corrections), so there is no explicit when-not routing.

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, and the description adds substantial context beyond them: immediate cessation of delivery, irreversibility, server-side verification, and the exact refusal message for unknown/deleted webhooks (consistent with idempotency). This is rich behavioral disclosure, not repetition.

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 destructive action and its effect, then the safety workflow, then verification. It is fairly long but nearly every clause carries actionable information; only the trailing verification sentence could be trimmed slightly.

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 explained. The description covers the destructive consequence, irreversibility, the preview/confirm protocol, and error behavior — everything an agent needs to invoke this safely.

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 confirm parameter is already well documented in the schema, so baseline is 3. The description nonetheless reinforces the semantics by framing confirm as the gate between a read-only preview and the real deletion, adding workflow meaning beyond the field 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+resource ("Removes a webhook subscription") and its immediate effect. It clearly distinguishes itself from create_webhook and list_webhooks, which are the natural siblings an agent might confuse it with.

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 prescribes the two-phase workflow (call without confirm for a preview, then with confirm:true after user agreement) and names the alternative (create_webhook to recreate). Nothing about when/when-not to use it 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 only declare readOnly/destructive/openWorld/idempotent hints; the description goes well beyond them by disclosing the unguessable 128-bit token URL, the ~15-minute expiry, that no inline bytes are returned, that each call yields a fresh link (explaining idempotentHint=false), and what contact data the file contains.

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 action and content scope, and most sentences carry distinct information. The trailing 'The link is temporary.' restates the earlier ~15-minute expiry and is the only wasted sentence.

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

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

An output schema exists so return values need no explanation, and the case is nonetheless covered with the download-link and data-content details. The description also flags the sensitivity of the exported contact data, which is the key thing an agent needs to know before calling.

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 `code` parameter is fully documented in the schema (8-character publication code, returned by list_surveys). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (exports), resource (respondents pipeline report, one row per respondent across all respondent lists on the survey's publication), and format (CSV), which separates it from export_respondents_spss, export_respondents_xlsx and export_survey_responses without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Format choice versus the SPSS/XLSX siblings is only implied, and there is no explicit when-to-use or when-not-to-use guidance relative to export_survey_responses. The 're-run for a fresh link' instruction is a usage hint, but routing guidance for the alternatives 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 mark readOnly/idempotent:false, but the description goes well beyond them: it discloses the ~15-minute link expiry, the unguessable 128-bit token, that a fresh link is produced per run (explaining the non-idempotent hint), that bytes are never returned inline, and that the file contains PII (names, emails, custom fields, personal survey links). This is unusually rich behavioral 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?

Front-loaded with the action and scope, then link behavior, then file contents. Efficient overall, though 'The link is temporary' at the end repeats the earlier 'expires after ~15 minutes' and could be cut.

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 format needn't be explained, and the description still covers file contents, link lifecycle, and non-inline delivery. For a single-parameter export tool this is complete enough for correct invocation; only an explicit sibling comparison 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 there is a single required 'code' parameter already documented (including an example and its source, list_surveys). The description adds no parameter-level meaning, so the high-coverage 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 (Exports), resource (respondents pipeline report), format (.sav SPSS), and scope (one row per respondent across all respondent lists assigned to the survey's publication). The explicit format naming distinguishes it from the export_respondents_csv and export_respondents_xlsx siblings without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by format ('as SPSS (.sav)') and by the re-run guidance ('Re-run for a fresh link'), but the description never explicitly tells the agent when to choose this over export_respondents_csv/xlsx or what distinguishes respondents-pipeline exports from response exports. Adequate but leaves the selection logic 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?

Goes well beyond the annotations: discloses the unguessable 128-bit token URL, the ~15-minute expiry, that a re-run is required for a fresh link, and that file bytes are never returned inline. The non-idempotent annotation is explained rather than merely declared, and the content of the file (names, emails, custom fields, personal links) is spelled out.

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 and scope, then layers behavioral detail efficiently. Mild redundancy: 'The link is temporary' restates the earlier '~15 minutes' expiry sentence.

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

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

With only one fully documented parameter and an output schema present, the description covers everything an agent needs to call it correctly, including the asynchronous download-link pattern. It could be tightened by removing the redundant closing sentence, but nothing material 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% and the single 'code' parameter is fully documented in the schema itself (8-character publication code, example, source tool). The description adds nothing about the parameter, so the 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 ('Exports the respondents pipeline report ... as XLSX') plus the exact scope ('one row per respondent across all respondent lists assigned to the survey's publication'). This cleanly separates it from export_respondents_csv and export_respondents_spss without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its usage context (pulling contact data for a survey's respondent lists) and offers a useful re-run hint for expired links, but it never states when to choose this format over export_respondents_csv or export_respondents_spss, nor any prerequisites. With three near-identical siblings, that omission is a real gap.

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 readOnly/destructive annotations: unguessable 128-bit token URL, ~15-minute expiry, re-run for a fresh link (consistent with idempotentHint=false), UTC timestamps, inclusion of system columns, the export rate class (12/hour per token), and an explicit data-privacy note. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return medium, and most sentences carry distinct behavioral facts (expiry, rate limit, privacy). It is on the longer side and reiterates some file-content detail that the output schema also covers, but little is pure 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 an export tool with a rich output schema, the description supplies everything the agent needs to call it correctly: format implications, link lifecycle, rate class, column naming, and privacy constraints are all covered.

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 earns extra by clarifying column-naming semantics (Q-codes as returned by get_survey, or custom IDs via useCustomID) and the extra system columns present in the file. It does not add format/behavior nuance for answersAsText or loopsIsOneRow beyond the schema.

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

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

States a specific verb, resource, and scope: exports ALL responses of a survey as a downloadable file with columns/rows structure. It also names the sibling it is not (list_survey_responses) and the return medium (temporary link, never inline bytes), so the agent can place it precisely among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'suited to large data sets; list_survey_responses returns the same data inline', naming the alternative and the condition that selects it. It adds further selection context (file usable for analysis outside built-in stat tools) so use-vs-alternative is unambiguous.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the empty-survey case returns the minimum DateTimeOffset value rather than failing. That edge-case disclosure is exactly the kind of extra context the annotations don't carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with zero waste, front-loading the primary behavior and appending the edge case in a clause. 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 one-parameter read tool with an output schema and full annotation coverage, the description covers the primary behavior plus the important no-responses edge case. Only the lack of routing guidance against sibling recency tools keeps it from a 5.

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

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

Schema description coverage is 100% and the 'code' parameter is documented in detail (8-character publication code, example, provenance from list_surveys). The description adds nothing about parameters, so the baseline of 3 applies since the schema does 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: 'Returns the timestamp of the survey's most recent response.' The purpose is unambiguous and narrower than siblings like get_response_counts or list_survey_responses. It does not explicitly name or differentiate against those siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, prerequisites, or alternatives are given. With many recency-adjacent siblings (get_response_counts_by_date, list_survey_responses, check_response_completion), an agent gets no help deciding when this tool is the right choice over them.

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, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds only the field semantics of Value and Total, which is useful context but overlaps with the declared 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?

One compact sentence with the core purpose front-loaded and no filler. The Value/Total gloss is arguably redundant with the output schema but is short and unambiguous.

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, single-parameter statistics tool with full schema coverage and an output schema, the description is sufficient to invoke correctly. Its only real gap is the unstated relationship to get_quota_qualified_count.

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 'code' parameter is well documented there (format, example, where it comes from). The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Returns quota-disqualification statistics.' The 'disqualified' qualifier implicitly separates it from the sibling get_quota_qualified_count, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus the near-identical sibling get_quota_qualified_count, nor any precondition beyond the schema's required code. The agent must infer the distinction from the tool name 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the meaning of the two output fields, which is useful interpretive context, but says nothing about scoping, permissions, or whether stats are live vs cached.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler; the key semantics of the returned fields are stated immediately.

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, and the safety profile is covered by annotations. However, for a metrics tool sitting among multiple count/quota siblings, the absence of any routing guidance leaves a real gap.

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

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

With 100% schema description coverage and a single well-documented 'code' parameter, the schema does all the work. The description adds no parameter detail, which is acceptable at this coverage level but earns no extra credit.

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 ('Returns quota-qualification statistics') and clarifies the two returned figures (Value vs Total). It does not differentiate itself from the closely named sibling get_quota_disqualified_count, leaving the agent to infer the distinction from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no mention of alternatives, despite several overlapping siblings (get_quota_disqualified_count, get_response_counts, get_response_counts_by_date). The agent gets no signal for when this metric is the right one to call.

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 (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine non-obvious context: that surveyLink is the contact's PERSONAL link and that responses through it are attributed to this contact — useful semantics not available in the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with zero filler; the returned fields and the personal-link caveat are front-loaded and every clause earns its place.

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

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

With an output schema present and full annotation coverage, the description needn't explain return values, yet it still clarifies the notable surveyLink semantics. It is fully adequate for a 2-param read tool; only the absence of usage routing keeps it from a 5.

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

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

Schema description coverage is 100%, so both parameters are fully documented with examples and sourcing (code from list_surveys, PersonalizedID origin). The description only echoes 'by PersonalizedID' and adds no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns a contact of a survey's contact list by PersonalizedID') and enumerates the returned fields. The singular 'contact' lookup is clearly distinguishable from get_survey_response and list_survey_responses, though no sibling is named 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?

The description never says when to use this tool versus alternatives like get_survey_response, list_survey_responses, or create_respondent. It reads as a pure output description with no usage or exclusion 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 and destructiveHint=false, so the safety profile is fully covered. The description adds semantic meaning for the returned Total/Value fields, which is useful, but says nothing about auth needs, rate limits, or edge cases like zero responses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the return-value clarification is compact. It is efficient and appropriately sized, though the Total/Value definition reads slightly terse.

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 spelled out, and the annotations fully cover the read-only/idempotent behavior. For a one-parameter read tool the definition is essentially sufficient, with only the sibling routing left implicit.

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

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

Schema description coverage is 100% and the single 'code' parameter is well documented in the schema itself (8-char public link code, sourced from list_surveys). 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 ('Returns overall response counts for a survey') and even defines the two returned values. The word 'overall' implicitly contrasts with the by_date/by_device/by_source siblings, but no sibling is named, so an agent must infer the 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?

'Overall' hints that this is the unfiltered aggregate variant, implying usage versus the dimensioned siblings. However, there is no explicit when-to-use statement, no exclusions, and no alternative named, so the guidance remains inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds behavioral detail beyond annotations: the fixed 14-day window and the inclusion of zero-response days, which is a meaningful disclosure about result shape. It doesn't mention timezone or ordering, keeping it just 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 sentence that front-loads the time window and count scope, then defines the metric mapping. Zero waste and every clause earns its place.

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

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

With an output schema present, the description needn't detail return shape, and it still clarifies the Total/Value mapping. The definition is complete for calling it correctly, though it leaves timezone behavior and ordering 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 coverage is 100% and the single parameter 'code' is fully documented in the schema, including its origin from list_surveys. The description does not repeat or extend parameter semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (returns response counts) with a precise scope: per calendar day, last 14 days. The parenthetical defines Total and Value unambiguously. Distinguishes from siblings like get_response_counts, get_response_counts_by_device, and get_response_counts_by_source by specifying the by-date dimension.

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 14-day window and per-day granularity imply when to use it (trend over time), but the description offers no explicit when/when-not guidance or names alternatives like get_response_counts for totals. Usage is inferable from scope rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the fixed three-bucket enumeration and the column semantics (ColumnName = bucket, Total = all, Value = completed), which is useful domain context, but it is largely restating return-shape information that the existing output schema already supplies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact clauses, front-loaded with purpose and followed by the return-shape legend; no filler sentences. The second clause is terse to the point of needing decoding ('per-bucket Total = all, Value = completed'), which slightly reduces clarity.

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, complete annotations, and an output schema, the description covers what the tool returns and how buckets are labeled. Nothing an agent needs in order to call it correctly is missing, though it does not note the prerequisite that a valid survey code must exist.

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 'code' parameter is fully documented in the schema (including the 8-character format and its origin in list_surveys), so the schema carries the burden. The description adds nothing about the parameter, which is the expected baseline when coverage is complete.

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 (returns response counts) plus the exact grouping dimension (three fixed device buckets: monitor, tablet, cellphone). This clearly separates it from the same-named siblings get_response_counts, get_response_counts_by_date, and get_response_counts_by_source without needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The device grouping implies when to reach for this tool rather than the date- or source-bucketed variants, but no explicit when-to-use or when-not-to-use guidance or alternative is named. Usage is inferable from the name and description only.

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 establish that this is a safe, idempotent read (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description does not need to cover mutation semantics. It usefully goes beyond annotations by clarifying the output semantics — ColumnName is the lower-case source name and Total/Value are per-source rather than survey-wide — which is exactly the kind of disambiguation that prevents misreading the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no waste. The purpose is front-loaded and the clarifying note about column/per-source semantics follows immediately.

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 and annotations covering the safety profile, the description need not explain return structure, yet it helpfully disambiguates the column meanings. The only gap is the absence of any routing guidance toward the by_date/by_device/counts siblings, which an agent with several near-identical tools would benefit from.

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 the single 'code' parameter fully documented as the 8-character publication code returned by list_surveys. The description adds no parameter-level detail, so the schema carries this dimension entirely; baseline 3 applies.

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

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

The description states a specific verb+resource ('Returns response counts') and a clear grouping dimension ('grouped by traffic source'), which distinguishes it from the by_date, by_device, and overall counts siblings. It stops short of naming those siblings explicitly, so the differentiation is inferable rather than spelled out.

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 grouping-by-source framing implies when this tool is appropriate (per-channel analysis) versus the survey-wide or by-date variants, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Usage is left to inference from the tool name and grouping clause.

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, and the description adds substantial non-obvious behavior: pages list INCLUDES empty pages, logic.errors flags rules broken by deleted sources/targets and requires a user decision, archived:true means the survey is hidden from list_surveys and only restorable in-app, and assembled URLs are not supported links. This is context an agent cannot get from 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?

The opening clause front-loads the purpose and every clause carries concrete information with no filler, but the entire body is one dense paragraph covering five distinct concerns (structure, pages, logic, languages, archived, URLs) that would scan far better as sections or bullets.

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?

Despite an output schema existing (so return values needn't be explained), the description still enumerates the fields an agent must reason over and ties them to downstream tools (add_question, list_survey_responses). For a single-parameter read tool with full annotation coverage, nothing needed to invoke or use 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 description coverage is 100% and the single 'code' parameter is fully documented in the schema (including ID-to-code resolution). The description adds no parameter-level detail beyond what the schema provides, 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 ('Returns the survey structure for a survey code') and enumerates the exact contents (questions/variable names, page layout, logic, languages, archived flag, share/preview URLs). An agent can distinguish this from list_surveys and list_survey_responses immediately.

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 contexts and routes to siblings: use variable names to interpret responses and address answers when creating/updating a result case, use page layout to place questions via add_question's page and to plan branching, and audit logic before adding new rules. It names alternatives (list_surveys, list_survey_responses, add_question) but stops short of an explicit 'do not use this when...' exclusion.

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 meaningful extra context: the stable-identifier semantics of resultCaseID and, importantly, that respondent contact/personal data is deliberately excluded from the response — a privacy boundary the annotations do not 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?

Two dense sentences that are front-loaded with the core result and then the identifier/personal-data caveats. It is information-rich without wasted clauses, though the payload enumeration is long enough that it borders on listing what the output schema already shows.

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-required-param read tool with full schema coverage and an output schema, the description covers purpose, the key usage scenario, identifier semantics, and a data-exclusion caveat — everything needed to call it correctly. The enumeration of returned fields is partly redundant against the existing output schema, which keeps it just under full marks.

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

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

Schema description coverage is 100%, so both 'code' (8-character publication code) and 'personalizedID' are already fully documented in the schema. The description adds interpretive context (what a result case is, that items address questions by variable name) but contributes nothing new about the two parameters themselves, 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 ('Returns one respondent's response (result case)') and immediately enumerates the payload it yields (items, device, browser, source, duration, completion state). The singular 'one respondent's response' contrasts cleanly with the sibling list_survey_responses, so an agent can pick between them 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?

Explains the incremental-read scenario by tying resultCaseID to de-duplicating reads via list_survey_responses' ChangedSince, which is concrete usage context. It stops short of an explicit 'use this when you need a single response vs the list tool' statement, so it's clear context rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuinely new behavioral detail: newest-first ordering, statusCode 0 meaning unreachable, isSuccess meaning 2xx, and isRetry meaning a repeat of a failed delivery. These decoding rules materially help interpretation and are not derivable from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the return shape and field semantics come first, the purpose follows. Every clause carries information and there is no filler.

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

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

An output schema exists, so return values need not be spelled out, yet the description still decodes the key status fields. Combined with the id-sourcing hint and the health-check use case, nothing needed 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 description coverage is 100%, so both parameters are already documented, establishing a baseline of 3. The description reinforces that ids originate from list_webhooks and confirms newest-first ordering, but adds no new syntax or bounds 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 ('Returns a webhook's recent delivery attempts') and enumerates the exact fields returned. This clearly separates it from list_webhooks and test_webhook, so an agent can pick it 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 use case: check webhook health and whether the target endpoint accepts QUESTIONSTAR's events. It also routes the agent to list_webhooks for the required ID. It stops short of naming test_webhook as the contrasting alternative, so it is clear context rather than 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 cover readOnly/idempotent/non-destructive, but the description adds real context: it clarifies the tool is a pure read with no restore/delete capability and that those actions live in the app UI, which is not derivable from annotations. The enumerated return fields somewhat duplicate the output schema, keeping this from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads identity and scope, then returns, then exclusions. Three dense sentences with no filler, though the return-field enumeration is arguably redundant given the output schema and adds modest length.

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 and annotations carry the safety profile, so the remaining need is scope and when-to-use, both fully covered. An agent has everything required to call it correctly and to know when not to.

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?

Zero parameters, so the baseline is 4. There is nothing for the description to disambiguate at the parameter level, and it correctly focuses on scope and output instead.

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?

Precise verb+resource+scope: 'Lists the account's ARCHIVED surveys' and immediately defines what archived means (recoverable bin). It names the sibling operation that put them there (archive_survey) and distinguishes itself from list_surveys by excluding live and permanently deleted surveys.

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 states when to use it ('show the user what is in the bin, e.g. after archiving drafts') and what it is not for: it does not restore or delete, and those actions happen in the QUESTIONSTAR app. The exclusion of live/permanently deleted surveys routes the agent away from this tool when those are the target.

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 (readOnly, idempotent, non-destructive), so the description's job is to add context. It does so usefully by disclosing the composition of results (own + system templates) and the 'API Layout {code}' naming convention for survey-dedicated copies.

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 tightly packed sentences with no waste. The core purpose is front-loaded, followed by the disambiguation and the downstream handoff, all of which earn their place.

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

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

With an output schema present, return values need not be described, and the description still adds the naming convention and result composition. Nothing an agent needs to call this correctly and route the result 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?

The tool takes zero parameters, so the schema baseline is 4. The description correctly focuses on output semantics (what the listed items are) rather than inventing parameter guidance.

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 (lists LAYOUT templates) and clarifies scope: the account's own templates plus built-in system templates. It explicitly distinguishes the resource from surveys, which is exactly what an agent needs to avoid confusing it with list_surveys.

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 states when NOT to use this tool ('it is NOT a survey to clone from') and names the alternative route (list_surveys + clone_survey). It also names the downstream consumer by telling the agent to pass the returned ID to apply_layout.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real domain behavior: tokens are split into uiControlled (editor-visible) vs code-only (invisible in the Layout Editor), and an unknown token name silently becomes an inert CSS custom property. That 'silent no-op' pitfall is exactly the kind of failure mode an agent needs. It stops short of describing the response shape or size of the vocabulary, but the output schema covers returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the purpose before the caveat about unknown names. The first sentence is dense with parentheticals but each clause (uiControlled vs code-only vs common vs pitfalls) earns its place by defining what the caller will receive.

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, the description need not enumerate return values, and it adequately covers what the tool is for, how the tokens are categorized, and the consequence of misusing a name. Minor gap: it does not say whether the vocabulary is fixed or project-specific, which could matter when validating tokens.

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 tool takes zero parameters, so the baseline is 4; there is no parameter semantics to clarify and the description correctly does not invent any.

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 ('Returns QUESTIONSTAR's layout design-token vocabulary') and ties it directly to the sibling tool apply_layout's inlineTokens parameter. It is easily distinguished from nearby list_* siblings such as list_layout_templates, which deals with templates rather than tokens.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the use context clear by naming apply_layout's inlineTokens as the consumer, implying this is a reference to consult before applying layout tokens. However, it never explicitly states 'call this before apply_layout' nor gives any when-not-to-use condition, 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?

Adds substantial context beyond the readOnly/idempotent annotations: asynchronous persistence forcing an overlapping window, de-duplication by resultCaseID, the 600 requests/hour heavy rate class, timezone handling for timestamps, and the privacy note that respondent personal data is never returned. These are exactly the operational traits an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool returns, then layers filters, rate class, and the export alternative. It is dense and sentence-heavy, but nearly every clause carries distinct decision-relevant information, so little 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?

Complete for a filtered-list tool: it covers return structure, filter combination semantics, timezone expectations, rate limits, the file-export alternative, and privacy scope. With an output schema present, no return-value explanation is owed, yet the column/Case explanation still adds interpretive value.

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 already 100%, so the baseline is 3, but the description adds real semantic value: FromDate/ToDate compare inclusively against each response's StartDate, ChangedSince is a delta-sync bound, Device maps to buckets, and Source 'external' identifies API-submitted responses.

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?

Opens with a specific verb and resource ('Returns all responses of a survey as a tabular data set') and explains the Questions/Cases shape so the agent understands exactly what comes back. It also explicitly distinguishes itself from siblings, naming export_survey_responses and get_survey as related but different tools.

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 routing guidance to export_survey_responses for large data sets and describes the incremental-read pattern using ChangedSince. It does not explicitly state when to use get_survey_response (single response) instead, but the context is strong enough to infer the boundary.

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. The description adds real context beyond them: the previewURL 'test mode - shows the survey but stores nothing' behavior, and that the host differs per instance. This is meaningful behavioral detail, though it omits anything about pagination or result limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then enumerates returned fields. The shareURL/previewURL explanation is partially repeated in the closing sentence ('shareURL and previewURL are the canonical survey links'), creating some redundancy, but the content is otherwise efficient.

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-parameter read tool with an output schema, the description is sufficient. It enumerates return fields that the output schema likely already covers (lower value per rules) but adds useful cross-tool context about the 'code' field and instance-specific hosts.

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?

Zero parameters, so the baseline is 4. There is nothing to document and the description adds no misleading parameter info.

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: 'Lists all surveys of the account that owns the API token'. An agent can distinguish this from get_survey (single) and list_archived_surveys (archived subset) 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?

The account scoping implies when this applies, but there is no explicit when-to-use or when-not guidance relative to siblings like get_survey or list_archived_surveys. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description goes further by disclosing the returned fields and their meaning (eventType values, includeFields empty = all fields) and by noting hooks created outside the API via Zapier/n8n are included — useful context 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?

Purpose and read-only scope are front-loaded, and the sentences are dense with usable detail. The middle enumeration of return fields is somewhat long, and with an output schema present some of it is redundant, but it is not padding.

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 annotation coverage and an output schema, this is essentially complete: it explains scope, alternatives, and result field meanings. Minor gaps only, such as no mention of ordering or result limits.

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% with a single well-documented 'code' parameter (8-character publication code, returned by list_surveys). The description adds no additional meaning about the parameter, 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 ('Lists a survey's webhook subscriptions') and immediately defines what a webhook is here ('survey events pushed as JSON POST to an https URL'). It also differentiates from siblings by naming get_webhook_deliveries for the ID and create_webhook/delete_webhook/test_webhook for other operations.

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 scopes the tool as read-only ('Only reads the configuration') and names the three sibling tools that perform the write/test actions, telling the agent when to pick each. It also routes the agent onward to get_webhook_deliveries using the returned 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?

Goes well past the annotations: it discloses that mid-response respondents are saved while only new entries close, that the share link shows a survey-closed page, that a concurrency slot is freed, that a never-published survey is refused, that double-pausing is idempotent success with wasAlreadyStopped, and that the paused state is re-read server-side before success. That is exactly the behavioral depth a high-consequence mutation needs, and it is consistent with idempotentHint=true and destructiveHint=false.

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 action and the consent warning, and nearly every sentence carries non-redundant information (reversibility, guards, mid-response behavior). It is dense and heavily ALL-CAPS-emphatic, which costs a little readability, but there is essentially no filler.

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

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

For a two-parameter, high-consequence mutation with an output schema already covering return values, the description supplies everything an agent needs: side effects, reversibility path, consent protocol, guard conditions, and idempotency. Nothing material is left to inference.

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

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

Schema coverage is 100% and both params are described there in detail, so the baseline is 3. The description earns an extra point by tying confirm:true to a consent precondition and clarifying that the no-confirm path is a preview reading live state, response counts, and concurrency slots, which frames the parameter as a workflow gate rather than a bare boolean.

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 pins the exact scope: 'a RUNNING survey stops accepting NEW responses.' The reversibility contrast with publish_survey and the distinction from archive_survey (nothing deleted, PublicationID unchanged) lets an agent separate this from its siblings 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?

Prescribes an explicit call sequence: call WITHOUT confirm first for a zero-side-effect preview, show the user what pausing means, then call with confirm:true only after explicit consent. It also names the sibling that reverses the action (publish_survey), covering both when to use and what restores state.

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 webhook side effects (SurveyPublished), the concurrent-survey limit and its failure message, the instruction to relay that message, and server-side re-verification of the started state. These are operationally important traits the structured fields do not 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?

The core purpose is front-loaded, but the text runs long and repeats itself: the concurrent-limit consequence is stated twice, and 'Surveys can also be published from the app' restates the earlier UI-flow sentence without adding value.

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 a mutation tool with an output schema and rich annotations, the description still supplies the error behavior, idempotency semantics, side effects, and limit enforcement an agent needs to invoke it correctly. Nothing material 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% and the single 'code' parameter is fully documented in the schema, including format and source tools. The description adds nothing about the parameter, 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 (publishes), the resource (a survey), and the concrete effect (starts collecting responses) plus the return (public share link). This clearly separates it from siblings like pause_survey and archive_survey.

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?

Implies usage context (publishing to start collection, stopping another survey when the limit is hit) but never names the alternative tool (pause_survey) or states explicit when-not conditions. Guidance is inferable rather than stated.

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

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

Annotations already declare mutation (readOnlyHint=false), idempotency, and non-destructiveness. The description adds genuinely non-redundant behavior: the edit-survey right requirement, readback verification of the result, and the branching-ordering constraint. It does not, however, describe what happens on an invalid permutation, which would round this out.

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 action and return value, then the parameter contract, then the constraint and prerequisites. Dense but every clause carries information; the branching explanation is slightly long but justified given the subtlety it prevents.

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 explained, and the description still summarizes them. Permissions, parameter contract, ordering constraint, and verification are all covered — nothing needed 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 baseline is 3. The description goes beyond the schema by clarifying that order must be a permutation of every page 'as get_survey reports them' and that numbers are 1-based and current — meaningfully sharpening the parameter's contract.

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 ('Reorders a survey's pages') and immediately distinguishes itself from siblings that add/delete/flags pages by noting it returns the current page list. An agent can tell it apart from add_survey_page, delete_survey_page, and set_survey_page_flags without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear operating constraint — keep each branching source page before the pages it gates, because show/skip logic fires on page moves — and points to get_survey as the source of the page numbers. It stops short of naming an explicit alternative tool to use instead in edge cases, so it is clear context without full when-not routing.

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/idempotent/non-destructive, so the bar is low, yet the description adds substantial context: a heavy rate class (600 requests/hour), pairwise exclusion of missing answers so n varies per cell, error cells for uncomputable pairs like constants, and the exact per-cell payload (r, pValue, fisherZ, n). Nothing contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core operation and its scope, and every later clause carries operational detail. It is dense and slightly rambling in the opening sentence about QUESTIONSTAR's built-in computation, but no sentence is purely 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?

Despite an output schema existing, the description still documents the shape and caveats of results, and it covers the inputs, the analyzable-data constraints, the rate limit, and the null/error behavior. An agent has everything needed to invoke it correctly and interpret edge cases.

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 meaningfully exceeds the schema by decoding the question-code addressing scheme (Q1 whole question, Q3.1 matrix row, Q2.3 checkbox option entering as 0/1), explaining that choice options enter by numeric export code, and clarifying that correlationTypes accepts any combination yielding one matrix per method.

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 ('Computes pairwise correlations between survey variables') and immediately scopes it against siblings, noting the same/other statistics are available via list_survey_responses and that run_regression/run_t_test-style analyses are separate tools. An agent can distinguish it from every sibling 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 clear selection rules for the method parameter (pearson default, spearman for ordinal/non-normal, tau = Kendall) and an explicit when-not ('free-text cannot be analyzed'), plus a list of analyzable question types. It stops short of an explicit statement of when to prefer this tool over pulling raw responses from list_survey_responses, only alluding to that alternative.

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?

Beyond the readOnly/idempotent annotations, it discloses listwise deletion of responses missing any model variable, dependency on the server R engine with an error envelope when unavailable, a heavy rate class (600 req/hour), and the presence of engine warnings such as collinearity. These are exactly the operational traits an agent must anticipate before calling.

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 block is long but front-loads the core definition and proceeds through alternative, computation, variable syntax, missing-data policy, output contract, and rate limit in a logical order. Most sentences carry non-redundant information, though the positional header contract detail could be trimmed given an output schema exists.

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 complex statistical tool it covers everything an agent needs: input variable encoding, analyzable question types, missing-data handling, engine failure behavior, rate limits, and how to read the positional result headers. With an output schema present, it does not over-explain return values while still clarifying the non-obvious header ordering.

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?

Although schema coverage is 100%, the description adds substantial meaning the schema lacks: variable addressing syntax (Q1 whole question, Q3.1 matrix row, Q2.3 checkbox option as 0/1), which question types are analyzable, that choice options enter by numeric export code, and that free-text is not analyzable. This materially changes how an agent must construct dependent and predictors.

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

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

The description names a specific verb and resource — computing a linear regression of one survey variable on one or more predictors — and situates it against siblings by noting that other statistics (multivariate regression, time-series, ANOVA) come from list_survey_responses instead. An agent can distinguish this from run_correlation and run_t_test 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?

It clearly frames when this tool is the right path (built-in server-side regression) versus pulling raw data and computing statistics externally via list_survey_responses. It does not explicitly name or exclude the sibling statistical tools run_correlation and run_t_test, so the routing guidance is strong but not exhaustive.

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

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

Goes well beyond the readOnly/idempotent annotations: declares the rate class (600 requests/hour), explains that non-computable cases return an 'error' field, and discloses the n-counting rule (responses missing either value are excluded). It also spells out the returned statistical set, so the agent knows exactly what evidence comes back.

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 is, then layers code formats, analyzable question types, and return shape in a logical order with no filler sentences. It is a dense single block, though — the return-value enumeration is long and partly duplicated by the output schema.

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?

Covers everything an agent needs to call it correctly: valid question types, code addressing syntax, pair-completeness semantics, rate limit, and error signaling. Since an output schema exists, the return-value prose is surplus but harmless rather than a gap.

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

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

Schema coverage is 100%, so a baseline of 3 would apply, but the description adds real meaning: how variables are addressed (Q1 whole question, Q3.1 matrix row, Q2.3 checkbox entering as 0/1) and that options enter by numeric export code. It also reinforces the exactly-two constraint on the questions array beyond the schema's terse wording.

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 precise statistical procedure: 'Computes a PAIRED-samples t-test between exactly two survey variables answered by the same respondents,' with a concrete example (before/after item pair). This clearly separates it from siblings like run_correlation and run_regression, which an agent could otherwise confuse with it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear condition for use (paired samples, same respondents) and an explicit alternative for a different need — 'the same and other statistics ... can be computed from the raw responses returned by list_survey_responses.' It also states a hard exclusion ('free-text cannot be analyzed'). It does not explicitly say when to prefer run_correlation or run_regression over this tool, so it falls short of a full when/when-not/alternatives treatment.

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 (which only flag destructive/idempotent/openWorld) by disclosing that only the default language is written, that other languages route through configure_survey_language, that the text may be saved-but-not-displayed, that willDisplay reports which case applies, and that the write is verified by re-reading. This is unusually rich behavioral 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?

Front-loads the core action before the caveats and alternatives. Dense but every clause carries information; slightly long, though nothing is truly redundant.

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

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

For a mutation tool with an output schema present, the description covers the display conditions, language scoping, permission requirement, alternative tools, and the willDisplay reply field. Nothing an agent needs to call 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 already 100%, so the baseline is 3, but the description adds genuine meaning: it clarifies that `title` renders above the message and that `message` accepts HTML. Minor added value over 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 ('Sets the survey's GLOBAL end-screen message') and immediately distinguishes it from the standard thank-you text and from siblings. The contrast with add_end_page and configure_survey_language 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?

Explicitly states when the message appears (standard end screen only) and when it does not (redirect/restart end behavior saves but does not display), plus the routing rule for branch-specific text via add_end_page. It also states the required permission.

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 cover safety (non-read-only, idempotent, non-destructive), and the description adds real behavioral context beyond them: omitted flags stay unchanged (partial-update semantics), the change is 'Verified by readback', markComplete affects completed statistics, and an auth requirement is stated. It does not say whether flipping a flag retroactively affects already-collected responses, which is the one notable gap.

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?

Dense but front-loaded: the core action and return value come first, then per-flag semantics, then the alternative, then prerequisites. No filler sentences, though the multi-clause sentences per flag make it longer than strictly minimal.

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 detailed, yet the description still summarizes the returned page list. Combined with prerequisite rights, partial-update semantics, and the sibling alternative, an agent has everything needed to invoke this 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it defines 1-based page numbering semantics in prose and explains the operational consequence of each flag (completion statistics, survey ending behavior) rather than just restating the schema text.

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

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

States a specific verb and resource ('sets a page's flags') plus the return payload ('returns the current page list (number, title, question count, flags)'). It also names the sibling it should not be confused with ('usually you want add_end_page instead'), so an agent can differentiate it 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?

Gives explicit when-to-use for each flag: markComplete for surveys where the required part ends mid-flow with optional content after, isEnd for ending a survey on a page's own content. It names the preferred alternative (add_end_page) for the common case and states the prerequisite ('Requires the edit-survey right on this survey').

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, non-destructive and non-open-world, so the safety profile is fully covered. The description adds only that the payload is a checklist; it discloses nothing further about behavior, though for a zero-param static content tool there is little else to disclose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with what is returned and followed by when to call it. Every clause earns its place; there is no filler.

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

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

With an output schema present, return values need no explanation, and with zero parameters and full annotation coverage, the description carries everything an agent needs to select and invoke this tool 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?

The tool takes no parameters, so the baseline is 4. Schema coverage is 100% and there is nothing parameter-wise the description needs to compensate for.

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: 'Returns QUESTIONSTAR's survey-design checklist.' No sibling tool returns design guidance, so the agent can instantly distinguish this from the CRUD/survey-authoring tools in the list.

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 when the user asks to design, review or improve a survey' gives a clear triggering context with three concrete intents. No explicit when-not or alternative is named, but no sibling overlaps this capability, so nothing is left dangerously ambiguous.

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/openWorldHint/non-idempotent, but the description adds material context beyond them: the real external request, the preview-then-confirm workflow, the server-side ID validation and its exact error string ('Webhook not found.'), and how to confirm delivery via statusCode. This is exactly the extra behavioral detail an agent needs before an irreversible external call.

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?

Dense but front-loaded: the irreversible side effect leads, then the safe workflow, then verification. Every sentence carries non-redundant information and none could be dropped without losing guidance.

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?

Output schema exists so return values need no explanation; the description compensates by covering the risk profile, the confirm protocol, the failure case, and the verification path. Complete for a destructive, open-world operation.

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 meaning by tying the confirm parameter to a safe two-phase workflow (preview vs. actual fire) rather than merely restating the default. webhookID's origin is also echoed ('the webhook's target URL').

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