MobOpinions Survey Light

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description doesn't need to restate those. It adds useful behavioral context: the token is redeemed for the linked account, the tool joins the workspace, and it switches to that workspace. This goes beyond the schema and 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?

The description is a single, compact sentence that front-loads the action and includes the key source of the token. No wasted words.

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

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

For a single-parameter tool with no output schema, the description covers the essential context: what the token is, what happens when redeemed, and the side effect of switching workspaces. It could mention error cases or idempotency, but annotations already 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 schema already documents the token parameter. The description adds that the token comes from the invitation email, which is helpful, but it doesn't add much beyond that. 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?

The description clearly states the action ('Redeem a workspace invitation token'), the resource (workspace invitation), and the effects ('joins the workspace and switches to it'). It distinguishes itself from sibling tools like invite_workspace_member and cancel_workspace_invitation by focusing on the redemption/acceptance flow.

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 the usage context: the token comes from the invitation email, and the action is for the linked account. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over invite_workspace_member or cancel_workspace_invitation.

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=false and destructiveHint=false, so the description's 'Add' is consistent and carries a lighter burden. The description does not add extra behavioral context such as effects on published surveys, validation failures, or relationship to fixed_position and randomise_answers, but it does not contradict 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?

The description is a single sentence that front-loads the action and object, then specifies the applicable question types. There is zero filler or redundancy, making it optimally concise.

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

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

For a simple create operation with full schema coverage and annotations, the description covers the core intent. However, it does not address error behavior for invalid question types, whether the survey must be in draft mode, or any return values (no output schema). It is minimally adequate but not rich in context.

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 each of the 8 parameters described meaningfully. The description itself adds no additional parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific action ('Add'), a specific object ('answer option'), and a clear scope (single_select / multi_select / ranking / matrix questions). This immediately distinguishes it from sibling tools like add_question, update_answer_option, and remove_answer_option without requiring schema inspection.

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 implicitly scopes usage to four question types, which gives some context. However, it does not explicitly instruct when to use this tool versus update_answer_option or remove_answer_option, nor does it mention exclusions like text questions. The usage guidance is implied rather than made explicit.

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=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate those. It adds useful behavioral context: piping tokens are inserted as {{Q<qid>}}, the tool returns the updated questionnaire plus created_qid, and answer codes are auto-assigned. It doesn't mention side effects like whether appending affects existing questions, but the return value and piping behavior are meaningful additions.

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: the core action and the type-dependent requirements come first, followed by the piping note and the return value. Every sentence carries information not already in the schema, 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?

For a 20-parameter tool with no output schema, the description covers the most important cross-field constraints and the return value. It doesn't enumerate every type-specific parameter (e.g., rating_limit for star_rating, range_multi_min for slider), but the schema already documents those, and the description's type-dependent guidance covers the critical branching. The absence of an output schema is partially mitigated by the explicit return description.

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

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

Schema description coverage is 100%, so the schema already documents all 20 parameters. The description adds cross-parameter semantics that the schema cannot express: which parameters are required for which question types (answers vs subquestions), and how piping tokens relate to list_piping_sources. This goes beyond the schema's per-field 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 description opens with a specific verb and resource ('Append a question with its answer options'), and immediately distinguishes the tool from siblings like update_question, delete_question, and reorder_questions. It also names the sibling list_piping_sources for piping IDs, which further disambiguates its role.

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 explicitly states when to use this tool versus alternatives: it is for appending a question, and it points to list_piping_sources for piping IDs. It also gives per-type requirements (single_select/multi_select/ranking need answers; matrix needs subquestions AND answers), which is actionable usage 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?

The description adds a useful behavioral detail: a condition on a second question interlocks the cell. It does not contradict the annotations, but it does not describe error behavior, idempotency implications, or the precise effect on the quota structure beyond the interlock note.

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 concise sentences with no filler. The primary action is front-loaded, and the interlock nuance is presented as a short, useful addition.

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 four-parameter mutation with no output schema, the description gives the essential action and an important domain concept. It lacks broader context such as how conditions interact with existing quota limits or what a successful response looks like, but it remains minimally adequate.

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

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

Schema description coverage is 100% and every parameter has a meaningful description, so the schema already carries the semantic weight. The tool description adds no further parameter-level detail, keeping this at the baseline.

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

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

The description clearly states the action ('Add'), the resource ('a manual quota'), and the object ('a (question, answer code) condition'). It is specific enough to distinguish adding from removing or updating conditions, though it does not explicitly name sibling 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?

The phrase 'manual quota' implies when this tool is relevant, and the action 'add' signals the operation. However, there is no explicit guidance about when to use this over update_quota_condition or remove_quota_condition, and no stated exclusions or alternatives.

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 convey that this is a non-read-only (readOnlyHint=false), non-destructive (destructiveHint=false), idempotent (idempotentHint=true) operation. The description adds the 'pending' scope but does not disclose any additional behavioral details such as side effects (e.g., notifying the invitee) or the state change after revocation. With annotations covering the safety profile, the description's contribution is minimal but consistent.

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

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

The description is a single sentence with no filler words. 'Revoke a pending workspace invitation' is direct, action-first, and fully front-loaded. Every word earns its place.

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

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

For a simple action with only two parameters, a rich schema, and helpful annotations, this description is nearly complete. It lacks an explicit statement about the outcome (e.g., 'the invitation becomes invalid') but the verb 'revoke' conveys that. No output schema exists, so explaining return values is unnecessary.

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

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

Schema description coverage is 100%, and the schema clearly explains both parameters: invitation_id is required and sourced from list_workspace_members → pending_invitations; workspace_id is optional with a default. The description itself adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description 'Revoke a pending workspace invitation' uses a specific verb ('revoke'), a precise resource ('pending workspace invitation'), and includes a qualifier ('pending') that distinguishes it from accepting invitations or removing existing members. This clearly differentiates it from sibling tools like accept_workspace_invitation and remove_workspace_member.

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 word 'pending' implies this tool is for invitations that have not yet been accepted, but the description does not explicitly state when to use it versus accept_workspace_invitation or other alternatives. It also does not mention any exclusions (e.g., what happens if the invitation is already accepted). The parameter hint in the schema about list_workspace_members adds some contextual guidance, but the description itself only implies usage.

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

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

The description adds meaningful context beyond annotations: it clarifies that this is a copy operation (not a move) and that it produces a new draft, leaving the original untouched. This is useful since annotations only indicate non-readonly, non-idempotent, non-destructive properties without explaining the actual 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?

A single, well-structured sentence that front-loads the verb and resource, then specifies the scope and result. Every word contributes to the meaning; there is no redundancy or filler.

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

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

For a simple clone tool, the description covers the core behavior and scope. However, it does not mention the return value (e.g., the new survey's ID), which is commonly expected for a creation tool, and there is no output schema to compensate. This is a minor gap.

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

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

Schema coverage is 100%, with both parameters (survey_id and optional title) fully described in the schema. The description adds no parameter-specific details beyond what is already in the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb 'deep-copy' and resource 'survey', and enumerates what is copied (questions, answers, targeting, skip logic). It clearly distinguishes this from creating a survey from scratch by noting the result is 'a new draft', though it doesn't explicitly name sibling 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?

The description implies usage for duplicating an existing survey into a draft, but it never explicitly contrasts with alternatives like create_survey or create_survey_from_template. There is no 'use this when…' guidance or mention of when not to use it.

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 destructiveHint=true, but the description adds specific behavioral detail: it charges accepted completes, releases the hold back to the wallet, and prevents future rejections. This financial and finality context goes beyond the annotation, though it does not address auth requirements or error handling.

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

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

Two sentences, front-loaded with the action and key effects, and a clear safety warning. No redundant phrasing; every clause adds 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?

For a single-parameter destructive tool with no output schema, the description covers the primary behavior, finality, and a user-confirmation prerequisite. It does not mention what happens on failure or return format, but these are minor given the simplicity and the annotations.

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

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

The single parameter survey_id is fully described in the schema (100% coverage), including its source and type. The description adds no extra meaning about the parameter, so a baseline 3 is appropriate since the schema carries the weight.

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 clearly states the verb 'close' with a specific resource ('a running survey'), and enumerates the concrete effects: stops fielding, charges accepted completes, releases hold. It also emphasizes finality ('Final — no more rejections after this'), which distinguishes it from sibling tools like pause_survey or resume_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?

The description advises 'Confirm with the user first,' implying a prerequisite for this irreversible action. However, it does not explicitly contrast with alternatives like pause_survey (for temporary stops) or delete_survey (for permanent removal). The finality is stated but the when-to-use vs. siblings is left mostly 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 cover readOnlyHint and destructiveHint, and the description adds the key no-side-effect behavior by saying 'Preview only'. It also discloses the output shape at a conceptual level (region/state/DMA list or postcode list), going beyond the structured annotation fields.

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

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

Two sentences with no filler: the transformation, output types, examples, and preview/apply relationship are all packed in. The most important scoping information ('Preview only') is placed before the alternative.

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 preview tool with two well-documented parameters, the description covers what it does, what it returns conceptually, and what to do next. It could specify the exact return schema, but no output schema is present and the conceptual output description is sufficient for selecting and invoking the 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 the baseline is 3. The description adds value by giving concrete examples of acceptable locations_text values ('Texas and Florida', 'Greater London', 'zip codes starting 902'), which clarifies the free-text format beyond the schema's brief description.

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 uses a specific verb and resource: 'Turn a free-text location description ... into structured targeting', and clarifies the result forms ('region/state/DMA selection or a postcode list'). It distinguishes itself from siblings by explicitly flagging 'Preview only' and naming set_location_targeting as the actual application step.

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 instruction 'Preview only — apply with set_location_targeting' gives an explicit alternative and tells the agent when this tool is appropriate. This is analogous to the high-calibration example that named its sibling and the condition for using it.

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

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

The description adds useful behavioral context beyond the annotations: interlocking of multi-question conditions, automatic binding of age to standard questions, and the fact that limits are expressed in completes. These details help an agent predict how the tool behaves. There is no contradiction with the annotations (readOnlyHint, idempotentHint, etc.).

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, with the core purpose stated in the first sentence. Every subsequent sentence adds distinct value: demographic setup, own-question setup, and unit clarification. There is no filler or redundant detail.

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

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

For a create operation with 8 parameters, the description covers the key decision points: quota type selection, demographic vs. own-question cells, and interlock semantics. The schema already documents all parameters, and the annotations cover side-effect hints. The description does not mention the 'location' quota_type variant, though the schema does, and it does not state what the tool returns, but this is not critical 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?

Schema coverage is 100%, so the baseline is 3. The description adds semantic value on top of the schema by explicitly mapping quota_type to its companion parameters (gender or age_from/age_to) and by explaining interlocking behavior for conditions. It also clarifies that qlimit is in completes, reinforcing the qlimit schema description.

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 clear verb and resource: 'Cap how many completes a group may fill,' which immediately conveys quota creation. It goes on to distinguish demographic-cell quotas from own-question-cell quotas, giving the tool concrete scope. It doesn't explicitly name sibling tools (like add_quota_condition or update_quota), but the creation-focused behavior is evident.

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 clear contextual guidance for the two main modes: use quota_type 'gender' or 'age' for demographic cells, and use conditions for own-question cells. It explains the difference between these modes and how they should be parameterized. It does not mention alternatives such as add_quota_condition or update_quota, so exclusion guidance is missing.

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 provide only generic false hints, so the description carries the behavioral burden. It usefully discloses that the tool returns survey_id and a price estimate, that nothing is charged until launch, and that it creates only an empty draft. This goes beyond the annotations and gives the agent a clear picture of side effects and billing behavior.

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

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

Two sentences with no filler. The core action is front-loaded, the workflow is compactly listed, and the return and billing information is delivered in a single closing sentence. 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?

For a simple 5-parameter draft-creation tool, the description is complete: it states the operation, the workspace context, the follow-up workflow, the return payload, and the billing implication. There is no output schema, but the description covers what the agent needs to know about the result.

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

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

Schema description coverage is 100%, and each parameter has a descriptive explanation in the schema. The description itself adds no parameter-level details beyond saying 'empty draft survey' and the workflow. Baseline 3 is appropriate because the schema already documents all parameters.

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

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

The description states a specific verb and resource: 'Create an empty draft survey in the active workspace.' The term 'empty draft' clearly distinguishes it from siblings like create_survey_from_template, create_survey_from_question, and clone_survey. The subsequent workflow names the exact tools involved, leaving no ambiguity about what this tool does.

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

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

The description clearly indicates when to use this tool: at the start of a survey-building workflow. It even enumerates the recommended next steps (add_question, set_targeting, preview_survey, launch_survey). It does not explicitly contrast with create_survey_from_template or other alternative creation paths, so it stops just short of explicit when-not-to-use guidance.

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

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

The description goes well beyond annotations by disclosing that the call is slow (up to a few minutes), outputs a draft rather than a launched survey, requires review before further steps, and is limited to 5 calls per hour. This is valuable behavioral context that 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?

Four dense sentences deliver scope, output state, expected duration, follow-up workflow, and a rate limit. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a creating tool with no output schema, the description is complete: it explains what is created, what state it is in, how long it takes, what limits apply, and exactly which subsequent tools to use. An agent has enough context to invoke it and continue 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. The description adds the meaningful qualifier that the input is 'ONE research question,' clarifying that a full survey is generated from a single prompt rather than multiple questions. It also notes the result lands in the active workspace, which gives situational meaning to the call.

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: 'Build a complete survey ... from ONE research question using AI.' It clearly distinguishes itself from siblings like create_survey, create_survey_from_template, and suggest_survey_topic by emphasizing AI generation, draft mode, and the complete survey 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?

Provides a clear post-call workflow: 'Review with list_questions, then set_targeting → preview_survey → launch_survey.' It also gives practical constraints like slowness and rate limit. It does not explicitly state when to prefer manual creation or template-based alternatives, so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint=false, so the description's mention of 'create' is consistent. It adds context about creating a draft (as opposed to a finalized survey) and identifies the template via flags. However, it does not disclose potential side effects or permission requirements, which is acceptable given the annotation coverage.

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, well-structured sentence that front-loads the key concept ('Create a new draft') and efficiently explains the template identification criteria. No wasted words.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers all necessary information for the agent to call it correctly: how to identify a template, what the resulting survey is (a draft), and parameters are fully described in schema. It does not over-explain but is complete enough.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining that template_id refers to a survey with is_template=true, which clarifies the schema's terse 'Survey id of the template'. This extra context helps the agent understand the parameter's semantics more fully.

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 action ('create a new draft'), a resource ('copying a template survey'), and precisely defines what qualifies as a template via flags. It clearly distinguishes from create_survey (blank creation) and create_survey_from_question (creation from a question).

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 explains the prerequisite for using this tool (template marked with set_survey_template_flag, is_template=true) but does not explicitly contrast it with alternatives like create_survey or create_survey_from_question. The intended use is clear, but no exclusions are stated.

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

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

Annotations only indicate non-readonly, non-idempotent, non-destructive. The description adds valuable behavioral detail: returns a URL for browser payment, funds are credited asynchronously, and the call is refused with billing_country_required until the country is known. This goes beyond the schema and annotations, though it omits auth or rate-limit expectations.

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

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

The description is compact and front-loaded: the main purpose is in the first phrase. It uses three concise sentences and avoids fluff. The 'Minimum 10.' fragment is slightly abrupt but acceptable. Each sentence adds necessary operational detail.

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

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

Given three simple parameters and no output schema, the description explains the return value (checkout_url) and the key behavioral constraint (billing_country refusal). It also clarifies the asynchronous funding flow. It could mention error cases beyond billing_country, but it covers the essential operational guidance an agent needs.

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 enriches the billing_country parameter by explaining its purpose (invoice country), the VAT implication for the UK, and its practical requirement despite not being in 'required'. It also reiterates the minimum amount. Currency is not discussed beyond the schema default, but the added semantics are meaningful.

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 clearly identifies the action ('Create a Stripe Checkout link') and the resource ('add funds to the wallet'), and it specifies the key output (checkout_url). This distinguishes it from wallet balance or survey tools, so an agent can understand its role without opening the schema.

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

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

The description provides clear usage flow: generate the link, give it to the user, funds land after payment. It also explains when billing_country must be collected ('ask the user for it') and the failure mode if omitted. It does not explicitly mention alternatives or when not to use this tool, but the context is sufficient for correct invocation.

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 provide false hints, so the description carries the behavioral burden. It adds useful non-obvious side effects: the caller becomes owner and the created workspace becomes the active one. It does not mention duplicate-name handling or failure behavior, but the main side effects are disclosed.

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

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

The description is one concise sentence that front-loads the action and then adds ownership and switching side effects. There is no filler or redundant restatement of the tool name.

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

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

For a one-parameter create tool with no output schema or nested objects, the description covers the essential invocation context: what it creates, its side effect, and ownership. It could mention what happens if a duplicate name is used, but that is not necessary for a basic agent to call it correctly.

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

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

Schema description coverage is 100% and the single 'name' parameter is already documented as 'Workspace name.' The description adds no extra constraints or format details for the parameter, so 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?

The description states a specific action (create), a specific resource (a new Survey Light workspace), and the key consequence (you become its owner and switch to it). This clearly distinguishes it from siblings like switch_workspace, rename_workspace, and list_workspaces.

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 wording makes the core use case clear: create a new workspace and switch to it. However, it does not explicitly say when not to use it or point to alternatives such as switch_workspace for existing workspaces, so the guidance is more implied than explicit.

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, so the description's 'Irreversible' adds context beyond the annotation by specifying the consequence. It also discloses that the tool deletes associated answers/statements, which is a behavioral trait not captured in the schema or annotations. 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?

Two short sentences with no wasted words. The core action and scope are front-loaded, and the irreversibility warning is placed immediately after, making it highly scannable.

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 tool with two well-documented parameters and no output schema, the description is nearly complete. It covers the action, scope, and irreversibility. It could mention that the operation cannot be undone or that it affects dependent data, but 'Irreversible' already covers the key risk. The lack of an output schema is not a gap since delete tools typically return minimal confirmation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (qid and survey_id) with references to list_questions and list_surveys. The description adds no additional parameter meaning beyond the schema, so 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?

The description states a specific verb ('Delete') and resource ('a question and its answers/statements'), clearly distinguishing it from sibling tools like delete_survey, delete_quota, and remove_answer_option. The scope of deletion is explicit, so an agent can tell exactly what this tool operates on.

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

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

The description implies when to use it (when a question must be removed) but does not explicitly state when not to use it or mention alternatives like remove_answer_option for deleting only an answer option. The irreversibility warning provides some usage caution, but no explicit routing to alternatives.

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 the description adds meaningful behavioral context by explaining that auto cells are not deleted but follow targeting, and should be frozen instead. It could go further and state that deletion is irreversible, but the destructive hint covers the safety profile adequately.

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 one sentence with a parenthetical clarification, and every part earns its place. The core action is front-loaded, and the important manual/auto distinction is conveyed in the same breath.

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

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

For a simple delete operation with two well-documented parameters, clear annotations, and no output schema, this description covers all decision-relevant context. It tells the agent what to delete, what not to delete, and what to do instead for auto cells.

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?

Both parameters are fully documented in the schema with descriptions referencing list_quotas and list_surveys/create tools, so the description does not need to add parameter-level detail. This meets the baseline for high schema coverage.

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

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

The description uses a specific verb ('Delete') with a precise resource ('a manual quota cell') and immediately distinguishes it from auto quota cells. This clearly differentiates from the sibling tool freeze_auto_quota without requiring schema inspection.

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 states when deletion applies (manual quota cells) and explicitly redirects for the alternative case (auto cells: 'freeze them instead'). This provides a clear decision rule for choosing between delete_quota and freezing, which is the key ambiguity for this tool.

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

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

Annotations already declare destructiveHint=true, so the description doesn't need to restate that. It adds value by specifying the irreversibility ('Irreversible — confirm with the user') and the precondition that the survey must have no completes. This goes beyond the annotation and gives the agent important behavioral context for a destructive operation.

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

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

Two sentences with no filler. The first sentence states the action and its preconditions; the second adds the irreversibility warning. Every word earns its place, and the most important constraint (permanently delete, no completes) is front-loaded.

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

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

For a single-parameter destructive tool with no output schema, the description covers the key context: what can be deleted, what must happen first, and that the action is irreversible. It doesn't describe the return value, but with no output schema and a simple delete operation, that's a minor gap. The confirmation requirement is also a useful addition.

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

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

Schema description coverage is 100%, so the schema already documents survey_id well, including its type, minimum, and how to obtain it. The description doesn't add parameter-level detail beyond the schema, but it doesn't need to. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description states a specific verb ('delete'), a specific resource ('survey'), and the exact scope ('draft or closed survey with no completes'). It also distinguishes from related tools like close_survey and pause_survey by noting that live/paused surveys must be closed first. This is a clear, non-tautological purpose statement.

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 explicitly says when deletion is allowed ('draft or closed survey with no completes') and when it is not ('Live/paused surveys must be closed first'). This gives the agent a clear decision rule and implies the alternative workflow (close_survey first). It also warns to confirm with the user, which is a usage guideline for a destructive action.

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, and non-destructive behavior. The description adds useful context about data granularity and inclusion criteria (one row per accepted/rejected complete, one column per question), which goes 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?

One short, front-loaded sentence that communicates the format, granularity, and row/column structure with zero wasted words. It is a model of concise, structured description.

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 having no output schema, the description explains the output shape well enough for a 1-parameter export tool. It could mention whether the response is a file download or include delimiter/header details, but basic invocation is clear.

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 survey_id parameter is fully documented in the schema. The description adds no parameter-specific meaning, but the schema baseline of 3 is appropriate.

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

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

The description states exactly what the tool produces: a raw respondent-level CSV with defined row and column semantics. This clearly distinguishes it from export_results_xlsx and get_results, which are the likely alternatives.

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 provides no explicit when-to-use or when-not-to-use guidance. It never mentions export_results_xlsx or any other sibling, so an agent must infer from the tool name that CSV format is the differentiator.

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 the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: the response is an embedded .xlsx base64 blob and includes per-complete labels, stored answer codes, and a code-to-label codebook. 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?

Two focused sentences front-load the core deliverable and sheet contents, then add the encoding detail. There is no filler, repetition of schema fields, or unnecessary context.

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

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

For a single-parameter, read-only export tool with no output schema, the description covers the essential operational facts: which completes are included, the workbook's sheet structure, and the base64 .xlsx return format. It omits guidance about how this relates to the CSV export, but that is a selection concern rather than a blocking gap for calling the 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 only parameter, survey_id, is fully described in the schema with a pointer to list_surveys and create tools, giving 100% schema coverage. The description adds no extra parameter-specific meaning, so the schema-only baseline 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 deliverable: an Excel workbook containing 'Responses', 'Codes', and 'Codebook' sheets, returned as a base64 .xlsx blob. This clearly distinguishes it from export_results_csv by format and content, though it does not explicitly name the sibling alternative.

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

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

There is no guidance about when to choose this tool over export_results_csv, get_results, or get_complete_answers. The only implied usage signal is the Excel/codebook format, which is not enough to steer an agent's selection.

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 idempotentHint=true and readOnlyHint=false, so the description need not restate mutation or idempotency. It adds valuable context: that the tool recomputes LOI from the question count and re-prices against targeting, which clarifies the side effects beyond a generic 'update'. 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?

The description is a single, tightly worded sentence that leads with the usage condition ('Call after editing questions') and then lists the concrete actions. No filler or redundancy. It efficiently conveys all essential information in minimal space.

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 having no output schema, the description sufficiently explains the tool's purpose and effects for a simple action. It omits what the return value looks like, but for an idempotent, non-destructive recalculation tool, this is a minor gap. The one-parameter schema and annotations cover the operational context well.

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 schema already provides 100% description coverage for the single parameter survey_id, including guidance to use list_surveys or a create tool. The description adds nothing beyond the schema, so the baseline of 3 applies. The parameter is well-documented in the schema itself, so no further explanation is needed.

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 clearly states the verb ('recomputes', 're-prices') and the resource (the survey), and specifies the exact outputs (LOI, CPI, total, feasibility). It distinguishes itself from siblings like get_price_quote (which is read-only) by framing it as an action taken after editing questions. The purpose is 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?

The description explicitly tells the agent when to call this tool: 'Call after editing questions'. This provides clear context. It does not explicitly name alternatives or when not to use it, but the 'after editing' condition implicitly sets it apart from read-only pricing tools. It lacks explicit exclusions, but the guidance is strong enough for correct selection.

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 idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false). The description adds meaningful behavioral context: that freezing prevents the quota from filling and from being rebuilt on audience changes, and that unfreezing restores normal behavior. 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?

The description is a single, front-loaded sentence that places the key action and the dual-mode (freeze/unfreeze) up front. There is zero wasted text; every clause contributes to understanding the tool's behavior.

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

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

For a simple 3-parameter tool with full schema coverage and annotations covering idempotency and safety, the description is complete. It explains the tool's purpose, scope (auto quotas), and the exact effect of the boolean parameter. No output schema exists, so return values are not 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 description coverage is 100%, so all parameters are already documented in the schema. The description adds no extra parameter meaning beyond what the schema provides (e.g., 'disabled' already described as 'True = frozen'). The tool description simply restates the freeze/unfreeze semantic already implied by the parameter.

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 precise verb ('Freeze') and a specific resource ('auto-generated (targeting-derived) quota'), and explains the effect (never fills, never rebuilt on audience changes) while covering the inverse via 'disabled=false unfreezes'. This clearly distinguishes it from generic quota tools like update_quota, which would handle manual quotas.

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 specifies the context of use (auto-generated, targeting-derived quotas) but does not explicitly name alternatives or state when not to use it. The wording implies it is for auto quotas only, which is clear enough given the sibling set includes manual quota operations.

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, and destructiveHint=false, so safety profile is covered. The description adds response field details but no extra behavioral context (e.g., implicit active workspace logic, no side effects). With annotations present, a 3 is appropriate.

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

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

One concise sentence with a structured field list; no filler or redundancy. The purpose is front-loaded with 'Account card:' and every word carries meaning.

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

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

For a simple read-only tool with one optional parameter and full annotations, the description lists all key output fields. It does not mention the effect of workspace_id (that lives in the schema), so slightly incomplete if read in isolation, but overall sufficient 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?

The single optional parameter workspace_id has 100% schema description coverage ('Only affects which workspace name is returned'). The tool description does not itself elaborate on parameter semantics, but the schema fully compensates, so baseline 3 applies.

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

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

The description precisely enumerates the returned resource: full name, email, Survey Light workspaces (with id, name, role, member count), active workspace id and name. It clearly differentiates from siblings like get_profile or list_workspaces by combining account and workspace context.

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 tool versus alternatives such as get_profile, list_workspaces, or switch_workspace. The description states what the tool does but offers no condition, exclusions, or route to a sibling.

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 read-only, non-destructive operation. The description adds useful behavioral context by documenting the minimum-completes requirement and the nature of the output, which is beyond what annotations convey. It could also mention behavior when the threshold is not met, but the added prerequisite is meaningful.

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

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

The description is a single, focused sentence that front-loads the core purpose (AI digest of results) and immediately appends the output components and the key prerequisite. Every element earns its place; there is no filler or redundancy.

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

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

For a single-parameter, read-only tool, the description provides sufficient context: it names the output content, states the threshold, and the schema fully documents the input. Since there is no output schema, the description does not detail the exact return structure, but it still gives an agent enough information to decide whether and how to call the 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%, and the survey_id parameter is already well-documented with type, minimum, and guidance to list_surveys or create tools. The tool description mentions 'results' but adds no additional meaning to the parameter itself, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as producing an AI-written digest of results and specifies the content categories: headline, key points, and watch-outs. It is distinct from sibling tools like get_results or get_insights_report by signaling an AI-generated, synthesized summary, though it does not explicitly name or contrast those 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?

The tool includes an important precondition ('needs ≥3 accepted completes'), which gives the agent a concrete condition for when the tool is callable. However, it does not explicitly state when to prefer this tool over get_results, get_insights_report, or get_launch_summary, nor does it describe any when-not-to-use scenarios.

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, and destructiveHint=false, so the safety profile is covered. The description adds detail about the returned data (counts, amounts), which is useful. However, it does not explicitly state that this operation has no side effects or that it is a pure preview, though the annotations imply that. The description is consistent 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?

The description is a single, compact sentence that lists the key output components without unnecessary detail. It is front-loaded with the core purpose and efficiently conveys the tool's function.

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

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

With no output schema, the description must explain the return values. It lists the main items but lacks detail on structure or types (e.g., whether amounts are numeric, how counts are formatted). Given the tool's simplicity (one parameter) and the listed items, it is reasonably complete, but an agent might need more specifics on the exact response format.

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 schema provides a full description for survey_id ('Survey id (see list_surveys, or the survey_id returned by a create tool)'), achieving 100% coverage. The tool description adds no additional meaning about the parameter, so it does not exceed the baseline. The parameter is straightforward, and the schema is sufficient.

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 clearly indicates the tool provides a preview of closing settlement, listing specific items (accepted/rejected counts, held amount, charge, release-back). It distinguishes from the sibling close_survey by implying it's a preview, though it does not explicitly name the alternative. The verb 'would settle' implies a hypothetical, which aligns with the title 'Preview close settlement'.

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 is given on when to use this tool versus close_survey or other related tools. The description does not mention that this should be used before actually closing a survey, nor does it state any prerequisites or alternatives. The agent must infer usage from the title 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, and destructiveHint, covering the safety profile. The description adds that the output contains 'full question-by-question answers', which is useful but does not disclose other behaviors like error conditions, pagination, or response format. Given strong annotations, the added value is modest.

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, focused sentence that front-loads the core action ('Full question-by-question answers') and includes the essential context (location_id from list_completes). There is no filler or redundancy.

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

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

For a simple two-parameter read tool with strong annotations and no output schema, the description covers the essentials. It explains the input source and the nature of the output. It does not mention potential errors or limitations (e.g., whether the complete must be finished), but these are minor for a tool of this simplicity.

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 both parameters described. The description repeats the location_id source from list_completes but adds no new meaning beyond the schema. Since the schema already documents each parameter, the description provides no additional semantic value, warranting the baseline score.

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 is specific: it states the tool retrieves full question-by-question answers for a single complete, identified by location_id. It clearly distinguishes this from aggregated tools like get_results or get_crosstab by emphasizing 'one complete' and 'question-by-question'. The reference to list_completes adds contextual grounding.

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 implies a workflow: first use list_completes to obtain a location_id, then call this tool. This gives clear context for when to use it. However, it does not explicitly state when NOT to use it or name alternatives such as get_results for aggregate data, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it mentions chi-square significance (statistical behavior) and the default table behavior when ids are omitted. This goes beyond the annotations and helps an agent understand what to expect. No contradictions 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?

The description is two sentences, front-loaded with the primary purpose, followed by a concise usage tip. There is zero wasted words; every clause contributes to understanding the tool. This is exemplary conciseness.

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?

While the tool is relatively specialized and the schema covers all parameters, the description lacks detail on the return format or output structure. There is no output schema, so the agent must rely on the description to know what the tool returns. The phrase 'default table and list of available fields' is a start, but it does not explain the table structure, significance indicators, or any other output details. This leaves a moderate gap for an agent planning to use the response.

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 parameters are well-documented. The description adds meaning by clarifying that omitting row_qid/col_qid returns a default table and available fields, which is not explicitly in the schema. It also implicitly explains the up-to-4 banner limit. This adds value beyond the schema, so a 4 is warranted.

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

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

The description clearly states the tool's function: cross-tabulating a question (rows) by up to 4 banner questions (columns) with chi-square significance. It distinguishes this from other result tools like get_results or export_results_csv by specifying the crosstab nature and the row/column structure. The additional note about omitting ids to get a default table and field list further clarifies its behavior.

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 provides clear context on when to use this tool (for cross-tabulation with multiple banners) and hints at usage via the 'Omit ids' instruction. However, it does not explicitly name alternatives or state when not to use it, leaving the selection to inference. Since the purpose is distinct and the context is clear, a 4 is appropriate.

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, and destructiveHint=false, so the safety profile is covered. The description adds the content structure of the report, which is useful context, but does not disclose other behavioral aspects like performance implications or whether it requires prior setup. Since annotations carry most of the burden, a 3 is appropriate.

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

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

A single, well-structured sentence that front-loads the key output components and avoids redundancy. Every word adds value, making it highly 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?

Given there is no output schema, the description adequately explains the return content. It covers the major sections an agent would need to know. However, it does not mention optional banner parameters or how they influence the report, but since the schema documents those, the description is sufficiently 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 parameters are already documented with their types and meaning. The description does not add any parameter-specific semantics beyond what the schema provides, so it stays at the baseline of 3.

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

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

The description states the tool returns the full Insights report and enumerates its contents (methodology, banner columns, per-question findings with significance flags, and comparison vs a wave). This is a specific verb+resource and clearly differentiates from siblings like get_crosstab or run_insights_function, which have narrower scopes.

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 this is the comprehensive report tool but does not explicitly state when to use it over alternatives like get_ai_results_summary or run_insights_function, nor does it provide exclusions or prerequisites. Usage context is only inferred from the word 'full'.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by listing the exact data returned: quote components, preview status, wallet balance, required amount, and shortfall. This gives the agent a clear behavioral expectation 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?

The description is a single, tightly-packed sentence that front-loads the purpose ('Pre-launch check') and then enumerates the returned fields in a compact list. Every word contributes information; there is no repetition of the tool name or any 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 read-only, single-parameter tool with no output schema, this description is complete. It tells the agent what data the summary contains, where the survey_id comes from (via the schema), and the pre-launch context in which it applies. 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?

The schema covers the only parameter (survey_id) fully with a description and minimum constraint, and schema description coverage is 100%. The description adds no parameter-specific meaning, but that is acceptable because the schema already carries the burden.

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

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

The description names a specific resource ('launch summary') and details exactly what it contains: final quote, preview status, wallet balance, required amount, and shortfall. This is distinguishable from similar siblings like get_price_quote and get_wallet because it combines those pieces into a single pre-launch check. The verb is implied by 'get' in the title and the noun-phrase description is sufficient.

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

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

The phrase 'Pre-launch check' clearly communicates when the tool is relevant: before launching a survey. It does not explicitly name alternatives or state when not to use it, but the context is concrete enough for an agent to select it appropriately. Some extra guidance about choosing this over get_price_quote/get_wallet would push it to a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat that. It adds value by specifying the exact outputs (incidence, LOI, CPI, total, feasibility, warnings) and constraints (min 100 completes, max 75 questions). It also explains the effect of targeting on incidence and price, which is useful 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?

Two sentences, front-loaded with purpose and output, followed by constraints. No wasted words. Highly scannable.

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

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

Given the rich schema and annotations, the description covers the core purpose and constraints. It lacks details about output format or how to interpret the quote, but for a pricing tool this might be sufficient. The absence of an output schema means the description could have clarified the return structure, but it lists key metrics, which is helpful.

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 parameters are well-described. The description adds usage nuances: 'Omit for a 10-question estimate' for question_count, 'adds a warning only' for has_location_targeting, and explains targeting's effect on incidence/price. This exceeds the schema's basic 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 description states a specific verb ('Price') and resource ('hypothetical survey'), and explicitly distinguishes itself from creation tools by saying 'without creating anything'. This clearly separates it from siblings like create_survey and launch_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?

The description implies the tool is for pre-creation pricing, but doesn't explicitly name alternatives or exclusions. It's clear enough that this is the pricing step before creating, but could benefit from explicit guidance on when not to use it (e.g., when you need to create the 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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context about what is returned (account details, workspaces, current session workspace), but does not mention authentication expectations, errors, or any other behavioral nuance.

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 compact sentence packs the essential return scope without filler. The most important idea, identity and current session, is front-loaded.

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

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

For a parameterless read-only tool with no output schema, the description fully covers what an agent needs to know about the returned data. There is no missing invocation guidance that would materially affect correct use.

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 and the schema confirms an empty object, so no parameter documentation is required. The description compensates by clarifying the output scope, which is the only semantic content that matters here.

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 clear resource scope: the linked account identity (user id, email, display name), the user's workspaces, and the session's switched workspace. It avoids tautology and is more informative than the title, but it does not explicitly differentiate from the sibling get_account.

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 'Who am I' framing implies use when the agent needs the current account identity or the session's active workspace. However, it gives no explicit when-not-to-use guidance or comparison to alternatives such as get_account or list_workspaces.

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 this read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those annotations by specifying that data is limited to 'accepted completes' and that open-text answers are capped at 200 per question, which meaningfully constrains expectations. It does not describe the return format, but with strong annotations the burden on the description is lowered.

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

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

The description is a single sentence that front-loads the core purpose, then efficiently enumerates the specific result types. Every clause adds information, and there is no filler or repetition of the title.

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

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

For a simple read-only tool with a single well-documented parameter and no output schema, the description gives enough context to know what data will be returned and its limitations. Minor missing details like exact response formatting or pagination are not critical for 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?

Schema description coverage is 100%, and the only parameter, survey_id, is already well documented with a clear description and reference to related tools. The tool description itself adds no additional parameter-level meaning, but per the baseline for high schema coverage, that is acceptable.

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 resource and scope: 'Per-question aggregates over accepted completes' with counts, percentages, age buckets, and open-text answers. This is clearly more specific than the generic title 'Get results' and distinguishes it from related reporting tools like get_crosstab or get_insights_report, though it does not name any 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?

The description implies the tool is appropriate when the agent needs per-question aggregate statistics, especially counts and percentages for choice questions and limited open-text answers. However, it gives no explicit guidance on when to prefer this over sibling tools such as export_results_csv, get_crosstab, or get_insights_report, and names no alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds behavioral context by stating it returns reference data (code + name, languages, categories, currency) and its role as a pre-check. It doesn't describe pagination or size limits, but given the trivial nature (no parameters), this is sufficient.

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

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

The description is two sentences with no fluff. The first sentence immediately states the purpose and lists contents; the second gives a clear usage directive. Information is front-loaded and every word earns its place.

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

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

For a zero-parameter, no-output-schema tool with annotations covering safety, the description is fully complete. It tells an agent exactly what data is returned, when to use it, and how it fits into the survey-creation workflow. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description adds value by detailing the exact content of the returned lists (country code+name, languages, categories, currency), which helps an agent understand what to expect even without an output schema.

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

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

The description clearly states the tool's purpose: providing reference lists for creating a survey, specifically naming the resources (countries, languages, categories, wallet currency) and their purpose (picking valid values for create_survey). This distinguishes it from sibling tools by its unique role as a look-up utility for survey creation parameters.

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 explicitly instructs to call this tool before create_survey to select valid country_code and category values. It gives clear timing and context, and implicitly states when not needed (when creating surveys without these parameters). No alternative tool is mentioned, but none exists for this purpose.

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 it read-only, idempotent, and non-destructive. The description adds useful behavioral context by calling it 'cheap' and a 'liveness snapshot,' which signals it is appropriate for repeated polling. It does not detail latency or error behavior, but that is a minor gap for a simple read operation.

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 front-loads the core purpose, enumerates the returned fields, and ends with routing guidance. There is no filler or redundant repetition of the title or 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?

For a one-parameter read-only tool with full schema coverage and strong safety annotations, the description is nearly complete: it lists the observed fields and the intended polling use case. With no output schema, type and format details for values like status or timestamps are unstated, but they are not needed to select or invoke the 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?

Schema description coverage is 100%, so the baseline is 3. The only parameter, survey_id, is already well documented in the schema with guidance on where to find it; the description adds no parameter-level meaning beyond referring to 'a survey.'

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 concrete operation: returning a cheap liveness snapshot with status, is_live, completes, target, and latest complete time. It clearly distinguishes itself from get_results by framing this as the progress-watching endpoint.

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 tells the agent to poll this instead of get_results to watch progress, naming the alternative and the specific use case. This gives clear selection guidance and avoids ambiguity with a sibling 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns 'current audience' and a 'live price quote,' implying real-time data retrieval. It doesn't disclose any side effects or requirements beyond that, but given the annotations, this is acceptable.

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

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

The description is a single sentence that front-loads the key subject ('Current audience') and enumerates the dimensions without waste. It is concise and structured effectively.

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?

The tool has one required parameter, no output schema, and annotations covering safety. The description tells the agent exactly what the response contains—audience dimensions, option dictionaries, and a live price quote—which is sufficient for a read operation. It doesn't mention error cases or whether the survey must exist, but the schema implies survey_id is required. This is fairly complete for its simplicity.

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 schema fully describes survey_id with a clear explanation and a minimum value, and the description does not mention parameters at all. With 100% schema coverage, the baseline is 3; the description adds no additional parameter meaning.

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 explicitly lists the returned data (country, gender, age ranges, etc., plus option dictionaries and a live price quote), clearly indicating this is a retrieval of current targeting settings. It distinguishes from set_targeting (which modifies) and get_price_quote (which only returns a quote), though the inclusion of a price quote might overlap with the latter. The name and title reinforce the get action.

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 provides no guidance on when to use this tool versus alternatives like get_price_quote, set_targeting, or get_survey_options. It doesn't mention that this is read-only or that it should be used to review current settings before editing. The agent must infer usage from the name and annotations.

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, covering the safety profile. The description adds useful behavioral context beyond annotations: the balance is pre-formatted with a currency symbol and the ledger includes the full set of transaction categories. No contradictions 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?

A single, well-structured sentence packs the resource, return contents, formatting detail, and workspace scope without waste. The most important information is front-loaded.

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

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

For a parameterless read-only tool, the description fully specifies what the agent will receive: a formatted balance and a full ledger with transaction categories. Even without an output schema, no critical invocation or return semantics appear 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 leaves nothing undocumented. The description still adds relevant context by scoping the result to the 'active workspace', which is the only implicit input the agent needs to understand.

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 clearly identifies the resource ('wallet') and the exact returned contents: 'total_credits, pre-formatted with currency symbol' and the 'full transaction ledger' including deposit, hold, charge, and release entries. It is unambiguous and conceptually distinct from siblings like get_account, though it does not explicitly name an alternative.

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 use case: retrieve the active workspace's wallet balance and transaction history. However, it provides no explicit when-to-use guidance and does not differentiate it from similarly named or related tools such as get_account.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable behavioral details: the invitation link's 7-day validity and the failure condition when the email is already a member or invited. This goes beyond the annotation flags and helps the agent anticipate side effects.

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

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

The description is a single, dense sentence that front-loads the core action and immediately notes key constraints. No wasted words; every clause adds essential 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 simple invitation tool with full schema descriptions and no output schema, the description covers the critical aspects: the action, ownership requirement, link validity, and duplicate failure. It omits minor details like rate limits, but these are not essential 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?

Schema description coverage is 100%, so each parameter (email, role, workspace_id) is fully documented in the schema. The description does not add additional parameter-specific meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description states a specific action ('Email an invitation') on a specific resource ('a workspace you own') and adds constraints (link valid 7 days, failure on duplicate). It clearly distinguishes from siblings like accept_workspace_invitation, cancel_workspace_invitation, and list_workspace_members by focusing on the invite action.

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 explicitly scopes usage to workspaces the caller owns, giving clear context on when this tool applies. It does not name alternatives or exclusions, but the ownership condition sufficiently narrows usage relative to related invitation tools.

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 (readOnlyHint=false, idempotentHint=false), the description reveals a significant hidden behavior: it reserves the full project value as a wallet hold and charges only for accepted completes at close. This financial side effect and the sample-supplier attachment are not inferable from the schema or hints, adding real decision-relevant context.

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

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

Three sentences, each earning its place: the core effect, the financial terms, and the prerequisites/confirmation rule. The most important action is front-loaded, and there is no redundant restating of the title or 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?

The definition covers the action, prerequisites, financial consequences, and user-confirmation requirement, which is enough for an agent to invoke it correctly. It does not describe the success response or error conditions, but there is no output schema and those are secondary for a launch action with such detailed prerequisites.

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 survey_id with a clear pointer to list_surveys and create-tool return values. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate because the schema carries the full burden.

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

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

The description states a specific action ('Take a draft live') with a clear resource (the survey) and detailed effects: publishing the survey, attaching sample suppliers, and reserving wallet funds. This distinguishes it from related siblings like preview_survey, close_survey, and pause_survey by making the 'go live' intent unmistakable.

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 explicit prerequisites (≥1 question, preview_survey done, sufficient balance) and a mandatory confirmation step ('ALWAYS confirm with the user before launching'). It does not name alternatives or state when not to use the tool, so it falls just short of a 5.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, lowering the burden. The description adds useful context about which statuses are included and the data fields returned, but it does not disclose ordering, pagination, or any operational constraints beyond the 15% rejection cap.

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, compact sentence front-loads the core purpose and captures the complete return set without filler. Every phrase contributes information.

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

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

For a single-parameter read-only list with no output schema, the description conveys the essential output contents and scope. It omits minor details such as pagination or ordering, but nothing critical is missing for invoking the 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 schema fully documents survey_id with cross-references to list_surveys and create tools, so the description does not need to repeat parameter details. It adds context by clarifying the tool scope ('Every complete'), but no additional parameter meaning is necessary.

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 clearly names the resource ('complete') and the action ('list'), and enumerates what is included: accepted/rejected statuses, timestamps, duration, rate, counts, target, and rejection cap. It does not explicitly contrast itself with siblings like get_complete_answers, so differentiation relies on content cues rather than an explicit statement.

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 intended use is implied by the survey_id parameter and the phrase 'Every complete...' – this is the tool for a survey-wide completion overview. However, it does not state when to use it over get_complete_answers, get_results, or set_target_completes, nor does it provide exclusions.

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

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

Annotations already indicate it's read-only, idempotent, and non-destructive, so the description doesn't need to restate. It adds the behavioral detail that current_qid limits to earlier questions, which is useful. However, it doesn't disclose whether questions in the current survey are always included or the exact ordering, but given annotations cover the safety profile, a 3 is appropriate.

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

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

Two concise sentences that front-load the core purpose and then the important filter. No wasted words; the example is helpful and placed early.

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

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

For a simple read-only list tool with 2 well-described parameters and no output schema, the description is complete. It explains the token concept and the filtering behavior. Minor gap: it doesn't specify what is returned (just question IDs or full objects), but given the simplicity, 4 is fair.

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. The description adds value by explaining the semantic of current_qid (limiting to earlier questions), which goes beyond the schema's phrase 'being edited'. This is slight added value, hence 3.

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

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

The description clearly states the tool lists questions whose answers can be piped via tokens, with a specific example. It distinguishes itself from list_questions by focusing on pipeable questions and mentioning the current_qid filter, which is unique 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?

The description explains the concept of 'pipeable questions' and the current_qid parameter for filtering earlier questions, giving a clear use case. It doesn't explicitly contrast with list_questions, but the context makes the purpose obvious, so I would rate it at 4.

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 read-only, idempotent, and non-destructive. The description adds useful domain-specific context beyond annotations, such as the locked flag meaning standard demographics can't be edited and the editable count cap of 75. There is no contradiction with 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?

The description is a single dense sentence with no filler, and the core subject ('The questionnaire') is front-loaded. It is somewhat run-on due to the long enumeration of fields, but every item contributes information about what the tool returns.

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

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

For a simple read-only tool with one required parameter and no output schema, the description provides a thorough inventory of the returned question attributes. It does not discuss pagination or ordering, but the low complexity and strong annotation coverage make the definition sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%: the single survey_id parameter is documented with a clear explanation and cross-reference to list_surveys and create tools. The tool description itself adds no parameter-level detail, but it doesn't need to because the schema fully carries that burden.

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

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

The description clearly identifies the resource ('questionnaire') and the action (listing every question) and enumerates the fields returned, making the tool's purpose specific. It does not explicitly differentiate from sibling listing tools like list_surveys or list_quotas, which keeps it at a 4 rather than 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?

The description gives no guidance on when to choose this tool over alternatives, and there is no mention of exclusions or complementary tools. The schema's parameter description references list_surveys, but the tool description itself does not provide usage context, so the agent is left to infer when list_questions is appropriate.

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 readOnly, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: auto-derived age/gender cells are marked is_auto, only their limit can change, and their ids are regenerated on every call. The warning to always use ids from the latest response is critical and highly transparent.

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

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

The description is two tight sentences: the first states the resource and returned fields, the second states a non-obvious id-freshness rule. There is no filler and the critical behavioral warning 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?

Although there is no output schema, the description names the main returned components (limit, filled, remaining, conditions/members, questions/answers) and the special is_auto behavior with id regeneration. This is enough for an agent to understand what it will receive and how to use the ids safely, leaving no obvious gaps for a list 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?

The only parameter, survey_id, is fully documented in the schema with guidance on how to obtain it, so the description carries no extra parameter burden. The phrase 'of a survey' adds no semantic value beyond the schema. Baseline 3 is appropriate given 100% schema description coverage.

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

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

The description identifies the resource as 'quota cells of a survey' and enumerates the returned data: limit, filled, remaining, conditions/members, and questions/answers a quota can be placed on. This clearly distinguishes it from sibling quota operations like create_quota, update_quota, and delete_quota, which are different verbs/resource intents.

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

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

No explicit alternatives or when-to-use guidance is provided; usage is implied by the 'list' verb and the resource description. It does not state exclusions or contrast with related quota tools such as update_quota, so an agent must infer when this is the right 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations: the result is ordered newest first, capped at 300, and includes specific fields. This provides useful context about the operation's behavior, aligning with annotations with no contradiction.

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, tightly worded sentence that front-loads the resource (surveys) and workspace scoping, then lists key attributes. No filler, every word contributes. Excellent structure.

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

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

With no output schema and no parameters, the description must explain what is returned. It lists the fields, ordering, and a maximum count, which is sufficient for a zero-parameter listing tool. It doesn't mention pagination beyond the max, but that is a minor gap. Overall adequate for an agent to call 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?

There are zero parameters, so the description carries no burden for parameter documentation. The baseline is 4. The description adds value by enumerating the returned fields (status, target quota, completes, CPI, total, country), which helps an agent understand what the listing provides.

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 clearly states it lists surveys in the active workspace, with a specific verb and resource. It also provides scoping (active workspace) and details about the returned fields. It does not explicitly differentiate from sibling list_* tools, but the resource (surveys) is distinct and the context makes it obvious.

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

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

The description implies when to use it (to get surveys in the active workspace) but does not explicitly state when not to use it or mention alternatives. It provides no exclusions, but the context of sibling tools (e.g., list_questions, list_completes) makes the intended usage clear. Lacks explicit guidance but is not misleading.

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 non-destructive behavior, so the description need not repeat safety. It adds the ownership precondition and the output categories (members with user id/email/role plus pending invitations). No contradictions or hidden side effects are hinted at.

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 front-loads the returned fields and ends with the ownership constraint. There is no redundant restatement of the title or annotations. The structure is ideal for a simple list tool.

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

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

The tool has only one optional, well-described parameter and rich read-only annotations, so the description needs little else. It conveys the output contents (members and invitations) despite the absence of an output schema. An agent can invoke it correctly and interpret the result without further clarification.

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

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

The single workspace_id parameter is already fully described in the schema, including its optionality and default. The description adds the extra meaning that the workspace must be one the user owns, which is not in the schema text. This is sufficient parameter-level 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?

The description specifies the resource (workspace members and pending invitations) and the returned fields (user id, email, role). It also scopes the result to 'a workspace you own,' which distinguishes it from generic workspace operations. Combined with the title's 'List' verb, this clearly establishes the tool's purpose.

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 provides clear context for invocation: retrieving members and pending invitations of an owned workspace. It does not explicitly name alternatives like invite_workspace_member or remove_workspace_member, but the read-only listing purpose is clear and no competing list tool exists. The ownership precondition is stated, so an agent can determine when this tool applies.

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 with readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful output context by noting the current session's workspace id is included, but it does not disclose the full return shape or ordering.

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 one short, front-loaded sentence with no filler. It efficiently conveys both the workspace list scope and the extra current-workspace id detail.

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

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

For a zero-parameter read-only list tool, the description is sufficient to select and invoke it correctly. It could specify each workspace's fields, but that is not essential for calling a parameterless 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?

The tool has zero parameters and an empty input schema, so there are no parameter semantics to document. This matches the baseline for zero-parameter tools.

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 the resource (workspaces) and adds scope: 'My Survey Light workspaces' distinguishes this from list_surveys and list_workspace_members. However, it lacks an explicit verb such as 'lists' and instead describes the return value, with the verb coming from the title.

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 intended use—retrieving the user's workspaces and the currently switched workspace—is implied but not explicitly stated. It does not mention alternatives like switch_workspace or list_workspace_members, and provides no when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds explicit clarity by stating 'Nothing is written' — reinforcing the read-only nature and that no data is mutated. It also mentions the input format (PDF, DOCX, XLSX, CSV) and size limit (max 20 MB), which are not in the schema. This adds valuable behavioral context beyond annotations.

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

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

The description is concise (two sentences) with no fluff. It front-loads the verb and purpose, specifies the input constraints, and ends with a clear next-step pointer. Every word adds value, making it appropriately sized and 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?

Given the tool's moderate complexity (3 parameters, no output schema, no nested objects), the description fully covers what an agent needs: input formats, size limit, scope of action (no writes), and the follow-up step (add_question). The lack of an output schema is not an issue because the description clearly states the output is a 'review-ready list of questions,' which is sufficiently descriptive for anticipated use.

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 schema description coverage is 100%, so the schema already documents each parameter (url, filename, survey_id). The description adds context about the URL being 'public http(s)' and survey_id referencing list_surveys, but these are minor additions. The baseline of 3 applies since the schema handles parameter semantics adequately.

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 clearly states the tool's purpose: 'AI-parse a questionnaire document... into a review-ready list of questions with types, answers and skips.' It specifies the resource (questionnaire document), the action (parse), and the output (list of questions). This distinguishes it from sibling tools like add_question and list_questions, which operate on already parsed questions.

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 explicitly states when to use this tool ('feed the result into add_question') and what it does not do ('Nothing is written'), which implies it is a read-only preparation step. It also implicitly differentiates from sibling tools like upload_media (which is for media) and suggests the workflow: parse first, then add.

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

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

The annotations declare idempotentHint=true and destructiveHint=false, which are useful. The description adds the behavioral nuance that pausing stops data collection but does not release funds, which is not inferable from the annotations. It implies the survey remains in a resumable state. No contradiction with annotations; a minor gap is lack of detail on what happens if called on a non-live survey, but overall it adds value beyond the 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 a single sentence of 13 words, front-loading the primary action and effect ('stops collecting') and mentioning the related tool. There is no fluff; every word earns its place, and the key point about funds is highlighted.

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

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

Given the tool's simplicity (one required parameter, no output schema, clear annotations), the description is quite complete. It explains the purpose, the side effect on funds, and the path to undo (resume_survey). Could mention the prerequisite that the survey must be live, but the phrase 'a live survey' implies that; it might benefit from stating what happens if called on a non-live survey, but such edge cases are often left out. Overall, it's adequate for an agent 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?

The single parameter survey_id is already well-described in the schema with a clear type, minimum, and a reference to list_surveys, giving 100% schema coverage. The description does not add any additional parameter semantics, but with full schema coverage, the baseline of 3 is appropriate. The schema description covers the parameter's purpose and origin, so the description does not need to repeat it.

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

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

The description clearly states the action (pause) and the resource (a live survey), and adds the key effect: 'stops collecting; funds stay reserved'. It is distinct from siblings like close_survey, launch_survey, and resume_survey, making the tool's purpose 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?

The description explicitly mentions the condition for use ('a live survey') and names the counterpart tool (resume_survey) for the opposite action. This direct routing helps an agent decide when to call this tool versus resume_survey or even close_survey, which has different implications.

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 idempotency and non-destructiveness. The description adds the 'mark as tested' side effect and the prerequisite relationship, but does not detail what 'mark as tested' entails or the response structure. It does not contradict annotations, but leaves some behavioral context unstated.

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

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

Two sentences with no waste. The main action is front-loaded, followed by a crucial workflow requirement. Every word 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 single-parameter tool with annotations covering safety, the description is quite complete: it states the purpose, the prerequisite, and the intended use of the result. It implies the response contains a test_url. A minor gap is the lack of explicit return format, but this does not hinder 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?

Schema coverage is 100% and the schema's parameter description is already informative, referencing list_surveys and create tools. The tool description adds no additional parameter semantics, so 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?

The description clearly states the verb 'Get' and the resource 'respondent-view preview link for a survey', plus the side effect 'mark it as tested'. It distinguishes from launch_survey by noting that launch requires this step, making the tool's purpose 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?

It explicitly states 'Launch REQUIRES this step', providing a clear condition for when to use this tool. It also instructs to 'share the test_url with the user', telling the agent what to do with the result. This is strong usage 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?

The description adds meaningful behavioral context beyond the annotations. It discloses that rejection excludes the complete from billing and reopens the slot, which is a key effect. It also notes the 15% cap, which is a critical operational limit. The idempotentHint=true annotation is consistent with the description (rejecting the same complete twice would have the same outcome), and the description does not contradict any annotation. The only minor gap is that it doesn't state what happens when the cap is reached, but that's an edge case.

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

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

The description is a single, well-structured sentence that front-loads the action and immediate consequence, then adds the cap and instruction. Every clause earns its place: the purpose, the effect, the constraint, and the required reason. There is no fluff or redundant repetition of the tool name or title.

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

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

For a simple mutation with three documented required parameters and no output schema, the description covers the essential context: when to use, what happens, and a constraint. It lacks detail on error handling (e.g., what if the cap is exceeded) or exact behavior when called after close, but these are edge cases not typically required for a tool of this simplicity. Overall, the description is complete enough for an agent to invoke 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?

The input schema already provides thorough descriptions for all three parameters (reason, survey_id, location_id) with full coverage (100%). The description adds little beyond the schema, except a reinforcement to provide a concrete reason. It does not introduce new syntax or format details. Since the schema carries the parameter semantics, a baseline score of 3 is appropriate, and the description does not compensate further.

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 clearly states the action (reject a complete) and the resource (a 'complete', i.e., a survey response). It also specifies the timing ('before close') and the consequences (excluded from billing, slot reopens). This distinguishes it from other tools that operate on completes, such as list_completes, which lists them, or accept_workspace_invitation, which is unrelated. No other tool in the sibling list performs a rejection, so the purpose is 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?

The description gives explicit context for when to use this tool: before close, and for low-quality completes. It also provides a constraint (capped at 15% of the target) and a directive (give a concrete reason). It does not explicitly name alternatives or state when NOT to use it, but since there is no alternative rejection tool, the implicit guidance is sufficient. It could be improved by noting that this should only be used when a complete is truly invalid, not for routine edits.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is captured. The description adds no further behavioral context such as permanence, cascading effects, permissions, or error behavior, and it does not contradict 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?

A single sentence that front-loads the action and object with no wasted words. Every token contributes meaning.

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

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

For a simple three-parameter destructive operation with full schema coverage and a destructive annotation, the core invocation is sufficiently specified. It could be improved by mentioning permanence or expected response, but nothing required 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 description coverage is 100%, with qid, code, and survey_id all documented. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Delete' with a clear resource 'one answer option' and container 'from a question'. This distinguishes it from siblings like add_answer_option, update_answer_option, reorder_answer_options, and delete_question.

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 states the action but offers no explicit when/when-not guidance or mention of alternatives. An agent can infer the use case from the verb and resource, but the description does not explicitly route to add/update/reorder siblings.

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 readOnlyHint=false, so the mutation is structurally disclosed. The description adds the constraint 'manual quota', which is useful context, but does not elaborate on reversibility, permission needs, or side effects. Given the annotation coverage, this meets the baseline without adding significant new behavioral insight.

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

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

The description is a single, focused sentence that directly states the action and object. It contains no filler, front-loads the purpose, and is appropriately sized for the tool's simplicity.

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 straightforward destructive mutation with full parameter documentation and a destructiveHint annotation, the description is largely sufficient. However, it omits any context about post-conditions (e.g., what happens to the quota) and potential edge cases (e.g., minimum condition count), which would be valuable but are not critical given the tool's simplicity.

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

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

Schema description coverage is 100%, and each parameter (survey_id, quota_id, member_id) already carries a clear description. The tool description adds no parameter-specific information, so it correctly relies on the schema. The baseline 3 applies because the schema fully handles parameter semantics.

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

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

The description uses a specific verb ('Remove'), names the resource ('condition'), and qualifies it ('from a manual quota'), clearly distinguishing it from siblings like add_quota_condition and update_quota_condition. An agent can immediately infer the tool's function without opening sibling schemas.

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

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

The description implies usage when one needs to remove a condition from a manual quota, but it does not explicitly name alternatives or provide exclusion criteria. The phrase 'manual quota' hints at a prerequisite, yet there is no comparison with update_quota_condition or add_quota_condition, leaving the decision boundary mostly implied.

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

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

Annotations already mark the tool as destructive and not read-only. The description adds useful context beyond that: an authorization requirement (workspace ownership) and an expectation to confirm with the user. It does not contradict the annotations, though it could mention irreversibility or re-invitation.

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

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

Two short sentences with no wasted words. The action and scope are front-loaded, and the critical confirmation instruction is included without 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 destructive operation with full schema coverage and clear annotations, the description supplies the key non-obvious context: ownership and prior confirmation. It leaves out only minor details such as the post-removal outcome, but nothing essential is missing for selecting and calling the 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 both parameters are already fully explained, including the optional workspace_id default and the source of member_user_id. The description adds no additional parameter-level detail, placing it at the baseline for fully-covered schemas.

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

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

The description uses the specific verb 'Remove' with a clear object ('a user from a workspace') and states the ownership prerequisite. This makes it readily distinguishable from sibling tools like invite_workspace_member or cancel_workspace_invitation.

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 implies when to use the tool: when removing an existing member from a workspace you own. It also provides explicit operational guidance ('Confirm with the user first'), though it does not explicitly contrast itself with invite_workspace_member or cancel_workspace_invitation.

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

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

The description adds an ownership requirement that goes beyond the annotations, which is useful behavioral context. But it does not elaborate on side effects or permission details beyond that, and the annotations already declare idempotentHint=true and destructiveHint=false, so the additional disclosure is modest.

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

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

The description is a single, efficient sentence that states the action and a key constraint. No filler or redundancy, and it is front-loaded with the verb and resource.

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

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

For a simple 2-parameter tool with complete schema documentation and safety annotations already present, the description covers the essential usage context (ownership). It does not need to restate schema or annotation details, so it is adequately complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, and both parameters ('name', 'workspace_id') are already well-documented in the input schema with clear descriptions. The tool description adds no further parameter-level meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Rename') and resource ('a workspace'), plus a clear ownership constraint. It is immediately distinguishable from siblings like create_workspace, switch_workspace, or delete_workspace, and there is no other rename tool 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?

The phrase 'you own' provides a clear precondition and context for when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full 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 indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that the operation changes display order based on a code sequence, but it does not disclose whether all answer codes must be supplied or how partial/unknown codes are treated. It does not contradict 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?

A single front-loaded sentence that states the action, the target resource, and the key input method with zero filler. Every word contributes meaning.

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

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

The tool is simple, the schema covers all three required parameters, and the annotations clarify idempotency and non-destructive behavior. The only notable omission is whether the codes array must enumerate every existing answer option, but overall the agent has enough information to call the tool successfully.

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 input schema provides 100% coverage: survey_id and qid are linked to list tools, and codes is described as 'Answer code' items with the ordering intent in the parameter description. The tool description only restates the ordering concept and adds no new parameter 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?

The description uses a specific verb ('Set') with a clear resource ('display order of a question's answers') and the mechanism ('listing their codes in order'). It is immediately distinguishable from siblings like add_answer_option, remove_answer_option, update_answer_option, and reorder_questions.

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 usage context is implied: you use this when you want to reorder existing answer options. However, the description does not explicitly say when not to use it or contrast it with add/remove/update_answer_option, so the agent must infer the appropriate selection from the sibling names.

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, which already indicate this is a non-read-only, idempotent, non-destructive operation, the description reveals the actual ordering algorithm: locked demographics remain first and omitted questions preserve their relative order. This gives the agent concrete expectations about side effects without contradicting any annotation.

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

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

The description is one efficient sentence that front-loads the action ('Set the order of the editable questions by listing their qids') and then compacts the two important constraints into a short second sentence. Every phrase earns its place.

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

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

For a simple mutation with no output schema and only two fully documented parameters, the description captures everything an agent needs to call it correctly: what to provide (qids in desired order), what is immutable (locked demographics first), and what happens to omitted questions (relative order preserved). No important gap is apparent.

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's mention of 'listing their qids' adds minimal extra meaning beyond the schema's 'Question ids in the desired order,' and it does not introduce any new parameter detail that the schema already provides.

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 uses a specific verb and resource: 'Set the order of the editable questions by listing their qids.' It clearly distinguishes this from the sibling reorder_answer_options by targeting questions rather than answer options, and it adds precise scope with 'editable questions' and 'Locked demographics stay first.'

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 clear context for when to use the tool: when reordering editable questions via qidsched. It explains locked demographics and omitted-question behavior, which is helpful usage guidance, but it does not explicitly mention alternatives or exclusion cases such as 'use reorder_answer_options for answer options' or what happens if you attempt to reorder locked questions.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds no behavioral context beyond that—it doesn't explain what resuming entails (e.g., making the survey active again for respondents). It is consistent with annotations, so no contradiction, but it adds nothing extra. Given annotations carry the safety profile, a 3 is appropriate.

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

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

The description is a single, front-loaded sentence with zero waste. It directly states the action and the precondition. It is concise and appropriately sized for a simple tool.

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

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

For a tool with one parameter, no output schema, and annotations covering safety and idempotency, the description is fairly complete. It states the precondition (paused and previously launched) and the action. It could explicitly mention that resuming changes the survey state from paused to active, but that is implied by the verb 'resume.' Overall, it's adequate.

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 parameter has a descriptive description in the schema ('Survey id (see list_surveys, or the survey_id returned by a create tool)'). The tool description does not add any additional parameter semantics beyond the schema, so the baseline of 3 is correct.

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 clearly states the action (resume) on a specific resource (a paused survey that was previously launched). It distinguishes from siblings like launch_survey and pause_survey by specifying the precondition (paused and previously launched). This is a specific verb+resource combination.

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 clear context by noting it applies to paused surveys that were previously launched, which implies when to use it (after a pause_survey call). It doesn't explicitly exclude alternatives like launch_survey or close_survey, but the condition is sufficient for most agents to infer correct usage. A small gap: it doesn't mention that this is the counterpart to pause_survey, but the context is present.

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

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

The annotations include readOnlyHint=false and destructiveHint=false, but the description does not add context about side effects. It mentions specific flags (regenerate=true) and data needs (qid) but does not disclose that many of the listed functions (e.g., insights_share_revoke, insights_theme_frame_delete) are mutating or potentially destructive. Since destructiveHint=false, there is no contradiction, but the description fails to surface the behavioral variance across the enumerated operations.

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

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

The description is a single long run-on sentence that dumps a massive list of functions with no line breaks or clear structure. It front-loads 'Advanced Insights operations by name' but then becomes a wall of text, making it hard to scan. It could be split into a short overview plus a bulleted list. The density reduces readability without adding proportional 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?

For a tool that dispatches over 40 distinct operations, the description is incomplete. It lists function names but does not explain return values, error handling, or how to obtain detailed docs for each function (beyond 'see its docs'). There is no output schema, and the agent is left guessing what each function returns or what side effects to expect. Some functions are mentioned with partial hints, but many are not, leaving significant gaps.

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

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

Schema coverage is 100% (survey_id and fn have descriptions, and params is described as the function's arguments). The description adds extra meaning by giving concrete examples for several functions, such as 'insights_ai_summary with regenerate=true' and 'insights_openend_themes, needs qid'. This goes beyond the schema's generic 'Function name.' and 'Arguments for the function' by linking parameters to real usage scenarios.

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 clearly states the tool's purpose as a dispatcher for advanced Insights operations, enumerating a specific list of function names. It goes beyond a generic 'run function' by naming the exact operations (e.g., insights_ai_summary, insights_pptx) and gives a few usage hints (regenerate=true, needs qid). This distinguishes it from generic tools and aligns with the 'Run an Insights function' title.

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

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

The description does not provide guidance on when to use this tool versus alternatives. It lists many functions but does not mention sibling tools like get_insights_report or get_results, nor does it say 'use this for X, use that for Y'. The only implicit guidance is the list itself, which tells the agent which functions are available here, but it never explains why to choose this over a more specific 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 carry idempotentHint=true and readOnlyHint=false, so the core safety profile is known. The description adds valuable behavioral context beyond annotations: '[] clears' documents the clearing behavior, and it explains that location_text is the label used by manual panels. This is useful, non-obvious behavior an agent could not recover from the schema alone.

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

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

The description is two compact sentences with no filler. It front-loads the main action, packs both mode branches, clearing behavior, label semantics, and a prerequisite pointer into a highly efficient structure.

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

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

For a 5-parameter tool with no output schema, the description covers both execution modes, the clearing case, the free-text label, and the prerequisite conversion step. It does not describe response behavior or explicitly name set_targeting as a sibling alternative, but the schema already documents survey_id requirements and postcode limits, so the description is sufficiently complete 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond individual property docs by specifying the mutual-exclusion relationship between assoc_type/values and postcodes, clarifying the [] clears semantics, and explaining what location_text represents. This genuinely helps an agent assemble a valid parameter set.

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 the specific action 'Apply location targeting' and clearly distinguishes two modes: admin-area selection versus postcode list. It references convert_location_text as a prerequisite, but it does not explicitly differentiate itself from the sibling set_targeting, so an agent may still need to infer the boundary between them.

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

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

The description gives explicit usage guidance: 'Use convert_location_text first' and explains the EITHER/OR branching between assoc_type+values and postcodes. It does not explicitly state when not to use this tool versus set_targeting, but the mode selection and prerequisite are clear enough for typical use.

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 provide idempotentHint=true and destructiveHint=false, so the baseline disclosure burden is lower. The description adds a valuable behavioral detail: the operation replaces the question's existing routing. This is important context for an agent, and it does not contradict 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?

The description is two concise sentences with no filler. The main behavior is front-loaded, and the replacement consequence is stated clearly at the end. Every sentence contributes useful information.

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

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

For a 3-parameter tool with complete schema coverage and informative annotations, the description covers the core behavior, valid route targets, and the overwrite consequence. It does not describe return values or error cases, and there is no output schema, so it is strong but not fully comprehensive.

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

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

Schema description coverage is 100%, so the schema already documents survey_id, qid, and routes well. The description mostly restates the routes semantics already present in the schema, though it adds the useful constraint that this applies specifically to single_select questions.

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 action ('Replaces the question's existing routing') on a specific resource ('single_select question') and explains the routing semantics: per answer code, jump to a later question id, 'end', or 'continue'. It is clear and unambiguous, but it does not explicitly distinguish itself from sibling tools like update_question or reorder_questions.

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

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

The use case is implied: use this tool when you want skip logic on a single_select question. However, it gives no explicit when-to-use or when-not-to-use guidance, and it does not mention alternatives or prerequisites such as the question needing to be single_select or the survey needing to exist.

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 communicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to restate them. The phrase 'Mark (or unmark)' adds useful context that the operation is a reversible toggle, but it does not disclose side effects or auth requirements beyond what annotations already 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?

One compact sentence that front-loads the action and object. Every word earns its place, and there is no redundant filler or repetition of the title.

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

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

For a simple two-parameter, idempotent flag setter with no output schema, the description and schema together provide enough information to invoke the tool correctly. The only slight gap is the absence of usage guidance relative to sibling template-related tools, but this is a minor omission for such a low-complexity 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 description coverage is 100%, so both survey_id and is_template are already well documented in the schema. The description adds no further parameter-level detail, so it meets the baseline but does not exceed it.

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

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

The description states a specific action ('Mark (or unmark)') applied to a specific resource ('a survey as a reusable workspace template'). It clearly distinguishes itself from siblings like create_survey_from_template by focusing on toggling a flag rather than creating a new survey from a template.

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 no explicit guidance on when to use this tool versus alternatives such as create_survey_from_template or clone_survey. It implies the use case from the wording, but does not state exclusions, prerequisites, or when a different tool would be more appropriate.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses meaningful behavioral consequences: raising the target reserves funds from the wallet and lowering it refunds the surplus at close. This is exactly the kind of real-world side effect an agent needs to know before invoking the tool.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the second sentence adds high-value behavioral detail without unnecessary elaboration.

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 mutation with a rich schema and clear annotations, the description covers the essential behavior and financial side effects. It could have clarified whether the target can be changed before launch, but the given information is enough for an agent to invoke it correctly in the most relevant scenario.

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

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

Schema description coverage is 100%, with both survey_id and submissions_quota already described. The tool description does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Change') and a specific resource ('the target number of completes'), making the tool's function immediately clear. This is distinct from siblings like list_completes (read) and set_targeting (targeting criteria), so there is no ambiguity about what it operates on.

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 clear context for when this tool matters: while a survey is in the field, changing the target has wallet implications. It doesn't explicitly name alternatives or when-not-to-use, but there is no direct sibling for setting the completes quota, so the guidance is sufficient.

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