pollbolt

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

Annotations are all false (not read-only, not destructive, not open-world), so they provide minimal safety context. The description adds valuable behavioral context by stating the operation returns details including share_url and enumerating supported question types. However, it does not disclose potential side effects or permission requirements, so a score of 4 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 extremely concise: two sentences achieve clarity. The first sentence states the action and return value; the second lists question types. No filler words, 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?

Given the tool's complexity (many nested objects for styles, settings, logic, ending screens), the description wisely leaves detailed parameter information to the schema. It provides the essential context (create + return + supported types), which is sufficient for an agent to understand the tool. The absence of an output schema is partially addressed by mentioning the share_url, but a few more behavioral notes would make it complete.

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

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

The input schema has high coverage (88%) and documents most parameters. The description goes beyond the schema by listing all supported question types (short_text, multiple_choice, etc.), which is essential because the schema only gives examples and does not provide an enum for the 'type' field. This addition meaningfully supports correct parameter usage.

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 creates a new survey, distinguishing it from sibling tools like update_survey, delete_survey, and duplicate_survey. It also specifies the return value (survey details including share_url) and lists supported question types, leaving no ambiguity about the operation'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 implies when to use the tool (when a new survey needs to be created) but does not explicitly discuss alternatives or exclusions. For example, it does not mention that duplicating an existing survey would use duplicate_survey instead, nor does it note any prerequisites or conditions for 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 indicate a write operation (readOnlyHint=false), non-destructive (destructiveHint=false), and external interaction (openWorldHint=true). The description does not add significant behavioral detail beyond the purpose, such as validation or activation process, but it does not contradict 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, concise sentence that immediately states the verb and purpose. It contains no redundant information and is well-structured.

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 simplicity of a webhook creation tool, the description combined with comprehensive schema annotations covers the essential context. It does not mention return values, but that is acceptable without an output schema, and there are no obvious missing behavioral caveats.

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

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

All parameters are fully described in the schema (100% coverage), so the description adds no parameter-specific meaning. The schema handles semantics adequately, making a baseline score of 3 appropriate.

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

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

The description uses a specific verb ('Register') with a clear resource ('a webhook') and purpose ('to receive notifications when survey events occur'). This clearly distinguishes it from sibling tools like update_webhook, delete_webhook, and list_webhooks.

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 the tool (when creating a webhook to receive event notifications) but does not explicitly provide guidance on when not to use it or mention alternatives (e.g., updating an existing webhook with update_webhook).

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 destructive, but the description adds key behavioral context: the deletion is permanent and includes all associated responses. This goes beyond the raw annotation flags to explain the cascade effect.

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

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

The description is a single, front-loaded sentence with no wasted words. It conveys everything essential without padding.

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

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

For a simple one-parameter destructive tool, the description fully covers the action, scope (including responses), and permanence. No output schema is needed for a delete operation, and nothing essential 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 only parameter survey_id is fully described in the schema with 'The survey ID to delete.' The tool description doesn't add any extra meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool permanently deletes a survey and all its responses, using a specific verb (delete) and resource (survey). This distinguishes it from sibling tools like delete_webhook and update_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 usage context is implied by the name and description—use this to permanently remove a survey—but no explicit when-to-use or when-not-to-use guidance is given, nor any mention of alternative tools like update_survey for non-destructive changes.

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 the context that the webhook must be 'registered,' implying it must already exist. It does not state consequences like irreversibility or permission requirements. Since annotations already declare destructiveHint=true, the description does not need to repeat that, but it could add more details about removal being permanent. With annotations present, the bar is lower, so 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, efficient sentence: 'Delete a registered webhook.' Every word earns its place; it is front-loaded with the verb and resource, with no filler or repetition. Optimal 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?

For a simple delete operation with one parameter, a clear description, and annotations indicating destructiveness, the description is complete. It specifies the action and the resource type. It does not detail return values or error behavior, but these are not typical for a delete tool and are absent from the schema/output schema. The low complexity and rich annotations reduce the need for more 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?

The schema has full coverage: webhook_id is described as 'The webhook ID to delete.' The description 'Delete a registered webhook' does not add further semantic detail about the parameter beyond what the schema already provides. Baseline 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 uses a specific verb and resource: 'Delete a registered webhook.' This clearly distinguishes it from sibling tools like create_webhook, update_webhook, and list_webhooks, which represent different operations on the same resource. The intent 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 implies usage: it is for removing a webhook that has already been registered. It does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions (e.g., 'do not use to disable a webhook temporarily'). However, the name alone makes the purpose obvious, and sibling tools cover other operations, so the context is clear.

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

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

The description states that all questions, styles, logic, and screens are copied and that the new survey details are returned, including share_url. This adds behavioral context beyond the annotations (which only indicate it's not read-only and not destructive) without contradicting them.

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, front-loaded with the action verb and purpose. It avoids redundancy and includes the key return value without unnecessary 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 simple duplication tool with a well-documented schema, the description covers the core functionality and return value adequately. It does not mention error handling or prerequisites, but these are not critical for this straightforward operation.

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

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

Schema coverage is 100%, with both 'survey_id' and 'title' described in the schema. The description does not add additional parameter semantics beyond what the schema provides, so it does not exceed the baseline for high 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 specific verb 'Create a copy' and identifies the resource as an 'existing survey', clearly distinguishing it from create_survey for new surveys. It also lists what is copied (questions, styles, logic, screens), leaving no ambiguity about its function.

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 that this is for duplicating an existing survey, which is sufficient for an agent to infer when to use it. It does not explicitly mention alternatives or when not to use it, but the sibling tools make the distinction obvious.

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, indicating a safe read operation. The description adds useful context by specifying the return metrics (views, responses, completion rate), but does not disclose any caveats such as data freshness or permission requirements. This adds some value beyond the annotations without being rich.

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 concise sentence that front-loads the tool's purpose and key output. Every word earns its place, with 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 one-parameter tool with no output schema, the description adequately conveys what the tool returns. It lists the key metrics, but does not specify the exact response format or mention any limitations (e.g., 'only aggregate data, not raw responses'). Slight gap, but generally complete.

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

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

The input schema provides 100% coverage: survey_id is described as 'The survey ID'. The description does not add extra meaning to the parameter. Since the schema carries the full burden, 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 ('get') and resource ('analytics summary for a survey'), and clearly lists the metrics it returns (views, responses, completion rate). This distinguishes it from sibling tools like get_survey or get_response, which focus on survey details or individual responses.

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

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

Usage context is implied: if you need aggregate analytics, this is the tool. However, it does not explicitly name alternatives (e.g., for survey details use get_survey) or any exclusions. The sibling list is available, but the description itself provides no explicit when/when-not guidance.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds minimal behavioral context beyond 'get single by ID', but does not disclose error handling, return format, or any side effects. With annotations present, this is adequate but not rich.

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 no wasted words. It immediately conveys the action 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?

This is a low-complexity get-by-ID tool with complete schema annotations and safety annotations. The description sufficiently explains the tool's purpose for selection and invocation, though it omits details about error responses, which are not critical for basic usage.

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

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

Schema description coverage is 100% for both survey_id and response_id. The description adds no additional parameter-specific meaning beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb ('Get') and resource ('response'), specifies scope ('single by ID'), and clearly distinguishes it from list_responses and other sibling tools. It is concise and 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 implies usage for retrieving one specific response, contrasting with list_responses, but it does not explicitly mention alternatives or conditions when to use this tool over others. No when-not-to-use guidance is provided.

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 no extra context such as authentication requirements, rate limits, or what happens if the survey is not found, but it is consistent with the annotations and adds 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?

The description is a single concise sentence that fully communicates the purpose and scope without extraneous information. It is well-structured and immediately understandable.

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 get-by-ID tool, the description covers the essential purpose and scope ('full details including all questions'). There is no output schema, but the description gives enough context about what the response will contain. It lacks notes on error conditions or return format specifics, but those are not critical for this low-complexity 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 input schema already describes survey_id as 'The survey ID' with 100% coverage. The description does not add additional meaning about the parameter, such as format requirements or examples, so it provides no value beyond the schema.

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

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

The description clearly states the action ('Get full details') and the resource ('a specific survey'), and it specifies scope ('including all questions'). This distinguishes it from sibling tools like list_surveys, which likely returns summaries, and get_analytics, which targets analytics data.

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 'specific survey' implies the need for a survey_id and suggests this tool is for retrieving detailed data for one survey, not for listing surveys. However, it does not explicitly name alternatives or exclusions, 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, so the safety profile is known. The description adds scope details (includes brandkits, uploaded media, etc.), but doesn't disclose further behaviors like response format or pagination.

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?

Single sentence, directly to the point, no unnecessary words. It efficiently conveys the tool's purpose and content scope.

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, the description covers the resource and scope adequately. With no output schema, a bit more detail about the response could be helpful, but the function's purpose 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?

Input schema descriptions cover both 'limit' and 'search' fully (100% coverage). The description doesn't add any parameter-specific information beyond the schema.

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

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

States it lists images from the account's media library and enumerates content types (brandkits, uploaded media, logos, theme backgrounds). This is a specific verb+resource and clearly distinguishes it from sibling tools that handle surveys, responses, and webhooks.

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 that this tool retrieves media library images, but it doesn't explicitly state when to choose this over sibling list tools. Usage is implied by the resource type rather than explicitly contrasted with 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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds value by stating 'Returns response metadata and answers,' which informs the agent about the output structure. It also mentions pagination and filters as behavioral traits. This goes beyond the annotations' safety implications.

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 ('List responses for a survey') followed by additional useful details. No wasted words; 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?

Given the tool's moderate complexity (6 params, 1 required) and lack of an output schema, the description provides enough context for selection: it states the resource, scope, pagination/filters, and return content. While not exhaustive on return format details, it is sufficient for a list operation with a well-defined schema.

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

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

The schema provides 100% coverage with descriptions for all parameters, so the description does not need to compensate. The description's mention of 'pagination and filters' is a high-level summary that does not add detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb ('List'), the resource ('responses'), and the scope ('for a survey'), clearly distinguishing it from sibling tools like get_response (single response) and list_surveys (surveys). It also mentions pagination and filters, which further clarifies the functionality.

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 this tool (to list responses with pagination and filters), and the context is clear given the sibling get_response for retrieving a single response. However, it does not explicitly state exclusions or alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the key behavioral trait of pagination, which is useful context. It does not mention filtering, but that is documented in the schema, so the added value beyond annotations is adequate.

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 wasted words. It conveys the core purpose and pagination in a compact form, earning the highest score for 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?

For a simple list tool with good annotations and fully documented parameters, the description covers the essential purpose and pagination. The lack of an output schema is mitigated by the tool's simplicity, though mentioning status filtering could have made it marginally more complete.

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

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

Schema description coverage is 100%, with all three parameters (page, status, per_page) having clear descriptions. The tool description does not add extra parameter semantics 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 clearly states a specific verb ('List') and resource ('surveys'), distinguishing it from sibling tools like list_responses and get_survey. The phrase 'in your PollBolt account' adds scope, making the 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 implies usage (listing surveys) but does not explicitly state when to use this tool versus alternatives like get_survey or list_responses. There are no exclusions or conditional guidance, so it remains at an implied-usage level.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, aligning with the read-only list behavior. The description adds the account scope, but does not disclose pagination, return format, or other behavioral details beyond what annotations provide.

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

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

The description is a single, concise sentence that front-loads the verb and resource. Every word earns its place, with zero unnecessary content.

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 list tool with one optional parameter and strong annotations, the description is nearly complete. It lacks return format details, but the low complexity and schema coverage make this a minor gap rather than a critical omission.

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 covers the sole parameter (survey_id) fully (100% coverage). The description itself omits any parameter details, so it adds no value beyond the schema. Baseline 3 is appropriate when schema coverage is high.

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 ('List') with a clear resource ('registered webhooks') and scope ('for your account'). It clearly distinguishes from sibling webhook tools (create/delete/update) by indicating a read-only listing operation.

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 purpose is self-evident as a listing tool, but there is no explicit guidance on when to use it vs. alternatives, nor any exclusions or mention of the optional survey_id filter. Context is implied rather than stated.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it is a write operation. The description adds minimal behavioral context beyond that, such as the answers map structure, but does not disclose idempotency, error behavior, or return value. Given the annotations, the description provides some value but not rich context.

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

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

The description is a single concise sentence that front-loads the primary action and clarifies the key parameter. No wasted words 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?

Given the tool has a nested object parameter and no output schema, the description is adequate but leaves gaps: it does not explain what the tool returns, what validation occurs, or how user_id and completion_time are used. However, the schema covers all parameters, and the tool is relatively simple, so it meets a minimum viable standard.

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 parameters are already well-documented. The description's mention of 'Answers is a map of question_id to answer value' adds no new meaning beyond what the schema provides. 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 ('Submit a response to a survey') with a specific verb and resource, distinguishing it from sibling tools like get_response and list_responses which are read operations. The scope 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 clearly implies when to use this tool (to submit responses programmatically) but does not explicitly exclude alternatives or state when not to use it. The context is clear enough for an agent to differentiate from read-only siblings, but no explicit when-not guidance is given.

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

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

The description explicitly warns that 'Providing questions replaces all existing questions,' adding concrete destructive behavior beyond the destructiveHint=true annotation. It does not mention that other array fields (variables, hidden_fields, ending_screens) also replace all, but the annotation already signals destructiveness and the schema provides those details.

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 only two sentences, front-loaded with the action and resource, and includes a critical caveat without wasted words. 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 complex tool with 9 parameters and deeply nested objects, the description is quite brief and slightly imprecise: 'logic' is not a top-level parameter, and it omits 'variables' and 'hidden_fields' from the list of updatable sections. The rich schema and destructive annotation compensate partially, but the concise description alone is not fully complete for such a complex 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 high (89%), so the baseline is 3. The description's list of updatable fields is a useful summary, and the question-replacement caveat is valuable but already present in the schema's questions parameter description. It does not add meaning beyond what the schema 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 ('Update') and clearly identifies the resource ('a survey') while enumerating the updatable aspects: title, questions, settings, styles, screens, or logic. This distinguishes it from sibling tools like create_survey, delete_survey, and duplicate_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 phrase 'Update a survey's' clearly implies the tool is for modifying an existing survey, which distinguishes it from create/delete siblings. It does not explicitly state when not to use it or mention alternatives, but the usage context is unambiguous enough for an agent.

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 a non-read-only, non-destructive operation. The description adds the specific fields that can be updated but does not disclose deeper behavioral traits such as partial-update semantics, validation rules, or side effects. 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?

A single, concise sentence that front-loads the verb and clearly enumerates the updateable fields. 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 mutation tool with five parameters and no output schema, the description is too terse. It does not explain that webhook_id must refer to an existing webhook, whether fields are optional, or whether updates merge or replace existing values. The low schema description coverage further increases the need for more contextual guidance.

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 description lists the updatable attributes (URL, events, active status, secret), which maps to the url, events, is_active, and secret parameters. With schema description coverage at only 20%, this partial compensation is helpful, but it does not provide detailed format or constraint information for each 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 clearly states the action ('Update') and the resource ('a webhook') with specific updatable attributes (URL, events, active status, secret). This distinguishes it from sibling tools like create_webhook and delete_webhook.

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

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

The verb 'Update' implies usage for modifying an existing webhook, but the description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or typical scenarios. It is adequate but not explicit.

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