Publish Forms survey

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

Annotations already flag this as a non-read-only, non-idempotent, open-world mutation, but the description adds genuinely useful behavior the annotations cannot convey: the two failure conditions (blocked, at cap) and the API's unusual bare 200 OK response semantics. It does not explain the error shape or whether re-publishing is harmful.

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 short sentences, each earning its place: the action, the failure modes, the response semantics, and the reversal. The core purpose 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?

With no output schema, the description usefully compensates by describing the response ('bare 200 OK; the returned record confirms the accepted action') and the failure cases. It is close to complete, though it omits permission requirements and what an agent should do when the call fails.

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 sole parameter (survey_id, 24-char hex, sourced from surveys_list) is fully documented in the schema. The description adds nothing beyond that, 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?

States a specific verb (publish) on a specific resource (a form/survey) and its user-visible effect ('so respondents can fill it'). It also explicitly names the inverse sibling tool (surveys_unpublish), so an agent can place it precisely among the forms_surveys_* family.

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 clear context: use it to make a form fillable, and it fails if the form is blocked or at its cap. It names the reverse operation for the opposite intent. It stops short of stating prerequisites (e.g. permissions, whether the form must be complete) or what to do on failure.

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