create-survey

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

Annotations indicate readOnlyHint=true, destructiveHint=false, and openWorldHint=false, which already convey that this is a safe, non-destructive operation with limited scope. The description adds minimal behavioral context beyond this, such as 'start the survey workflow,' but doesn't detail what that entails (e.g., UI interactions, state changes). No contradiction with annotations exists, but the description doesn't enrich behavioral understanding significantly.

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 with two sentences that directly address purpose and parameter usage, avoiding redundancy. It's front-loaded with the core function, though it could be slightly more structured (e.g., separating creation vs. editing scenarios). Overall, it's efficient with minimal waste.

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 (mutation-like but annotated as read-only), 1 parameter with full schema coverage, no output schema, and annotations covering safety, the description is moderately complete. It explains the dual create/edit function and parameter role but lacks details on workflow outcomes, error handling, or integration with siblings, leaving room for improvement in guiding the agent.

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

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

Schema description coverage is 100%, with the single parameter 'project_token' fully documented in the schema. The description adds marginal value by reiterating its optional nature and linking it to editing, but doesn't provide additional semantics beyond what the schema already states (e.g., format details or usage nuances). Baseline 3 is appropriate given 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 clearly states the tool's purpose: 'Create a new survey or edit an existing one.' It specifies the verb ('create'/'edit') and resource ('survey'), making the function unambiguous. However, it doesn't explicitly differentiate from siblings like 'save_survey' or 'preview_survey', which might handle overlapping aspects of survey management.

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 some usage guidance: 'Call this to start the survey workflow' and mentions using 'project_token' for editing. This implies context but lacks explicit when-to-use rules or alternatives (e.g., when to use 'save_survey' instead). It doesn't specify exclusions or prerequisites, leaving gaps in agent decision-making.

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 this as read-only, non-destructive, and closed-world, which the description doesn't contradict. The description adds valuable context beyond annotations by specifying that it generates a preview link for testing purposes, which helps the agent understand the tool's behavioral output even without an output schema.

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

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

The description is perfectly concise with two sentences that each earn their place: the first states the purpose and action, the second states the requirement. No wasted words, and the information is front-loaded with the core functionality.

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 comprehensive annotations and clear purpose, the description is mostly complete. The main gap is the lack of output schema, so the description doesn't specify what the preview link looks like or how it's returned. However, given the tool's simplicity and good annotations, this is a minor 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?

With 100% schema description coverage, the input schema already fully documents the single required parameter (project_token). The description mentions the parameter requirement but doesn't add semantic meaning beyond what's in the schema, such as explaining why this token is needed or how it relates to survey previews.

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 specific action ('Get a preview link'), the resource ('an existing survey'), and the purpose ('so the user can try it out before sharing'). It explicitly distinguishes from sibling tools like share_survey and view_responses by focusing on preview functionality rather than distribution or analysis.

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 about when to use this tool ('to try it out before sharing') and mentions the prerequisite requirement ('Requires the project_token'). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the purpose implies it's for preview rather than final sharing or editing.

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. The description adds minimal behavioral context beyond confirming mutation (create/update) and returning a URL and token. No additional details about authentication, side effects, or response format are provided.

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 with no wasted words. It front-loads the core action 'Save a survey' and efficiently covers the create/update distinction and return values.

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 (nested objects, no output schema), the description adequately covers the return value (URL and token) and the create/update logic. However, it omits details like error handling, the format of the survey token, and explicit differentiation from the sibling 'create_edit_survey' tool. Nonetheless, it is sufficient 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 50%: the 'project_token' parameter has a schema description (format: projectId:secret). The tool description adds context to 'project_token' by explaining its role in create vs update, but 'guide' remains undocumented in both the schema and description. Overall, the description adds some value but does not fully compensate for the missing parameter documentation.

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

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

The description clearly states the tool's purpose: 'Save a survey' and distinguishes between creating (no token) and updating (with token). It is specific with verb-resource, but does not explicitly differentiate from the sibling tool 'create_edit_survey', which may cause confusion.

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 guidelines by stating when to create vs update based on token presence. However, it does not provide explicit guidance on when to use this tool over alternatives like 'create_edit_survey' or mention any exclusions or prerequisites.

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 readOnlyHint and destructiveHint. Description adds requirement of project_token and return of a link, but does not significantly expand behavioral disclosure beyond what annotations convey.

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

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

Two sentences, no fluff, front-loaded with purpose and usage. 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 read-only tool with one parameter and no output schema, the description fully covers what it does and when to use it. Sibling differentiation is sufficient.

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 description only restates that project_token is required, adding no new semantic 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?

Clearly states 'Get the public share link for an existing survey' – specific verb and resource. Distinguishes from siblings like create_edit_survey and view_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?

Provides explicit scenario: 'Use when the user is ready to collect responses and says share it'. Also mentions required parameter. Lacks explicit when-not-to-use but context with siblings is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns by stating it 'views' and returns non-destructive output. The description adds value by stating the return content (summary plus dashboard URL), which is beyond 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?

Two sentences, no wasted words, action verb first, and immediately states what is returned. Highly concise and 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?

With one required parameter and rich annotations, the description sufficiently covers the tool's operation. It specifies return format but could mention if there are limits or filtering options, though not strictly necessary given the 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 a description for project_token. The tool description does not add any extra semantics for the parameter; it only repeats the purpose. 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 'View' and the resource 'survey responses and transcripts', and specifies the return includes a summary and dashboard URL. It distinguishes from sibling tools like create_edit_survey which are for editing.

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 viewing responses but does not explicitly guide when to use this tool versus siblings like create_edit_survey or preview_survey. No when-not-to-use or alternative references are provided.

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