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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: pages list INCLUDES empty pages, logic.errors flags rules broken by deleted sources/targets and requires a user decision, archived:true means the survey is hidden from list_surveys and only restorable in-app, and assembled URLs are not supported links. This is context an agent cannot get from structured fields.

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

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

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

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

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

Despite an output schema existing (so return values needn't be explained), the description still enumerates the fields an agent must reason over and ties them to downstream tools (add_question, list_survey_responses). For a single-parameter read tool with full annotation coverage, nothing needed to invoke or use it correctly is missing.

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

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

Schema description coverage is 100% and the single 'code' parameter is fully documented in the schema (including ID-to-code resolution). The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Returns the survey structure for a survey code') and enumerates the exact contents (questions/variable names, page layout, logic, languages, archived flag, share/preview URLs). An agent can distinguish this from list_surveys and list_survey_responses immediately.

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

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

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

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