publish_survey

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

The description adds behavioral details beyond annotations: authentication via API key, max 10 concurrent requests, and respect for read-only/dry-run modes. Annotations are minimal (no readOnly, idempotent, destructive hints), so the description provides useful extra context. It does not explicitly state idempotency, but the annotation already indicates non-idempotent.

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 well-structured with a clear purpose, usage conditions, instructions, authentication/limits, parameter list, and return format. It is somewhat verbose but all content is relevant and efficiently presented.

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 description covers all aspects: preconditions (valid states), prerequisites (getting IDs), side effects (publishing), limits (concurrent requests), error handling (error object), and return format (JSON with status and survey_id). It is complete for the tool's complexity.

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 0%, so the description fully compensates by explaining each parameter: list_id (from list_audiences), survey_id (from list_surveys), and account (optional, with account name configuration). It also provides source tools for each.

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 states 'Publish a survey, making it live at its public URL,' clearly identifying the verb (publish) and resource (survey). It distinguishes from siblings by mentioning unpublish_survey and list_surveys as 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 specifies valid states: 'draft, unpublished, or previously-published-then-edited state.' It advises using list_surveys to find the ID and check status, and unpublish_survey to revert. This gives clear context and alternatives.

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