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

Annotations only tell the agent this is a non-read-only, non-destructive, open-world operation. The description adds genuine behavioral context beyond that: build latency (5-15 min), that a build_url is returned instantly, that the site does not exist until the build finishes in non-widget contexts, the polling interval, and the terminal states to watch for.

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?

It is long, but the length is justified by a genuinely multi-path workflow, and the trigger condition is front-loaded before the widget/no-widget branches. A few sentences are dense run-ons ('In a widget client... do NOT need to block or keep polling'), but almost every clause carries actionable information.

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?

An output schema exists so return values need not be detailed, yet the description still names the key return artifact (build_url/task_id) exactly where the agent needs it. Combined with the polling workflow and the sibling preference, nothing required to call this 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%, so the baseline is 3. The description reinforces that 'prompt' is a detailed text description of the site but says nothing about 'context' or the visibility enum that the schema does not already cover, so it adds little beyond structured fields.

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 first sentence states the specific verb+resource ('build a complete, hosted website or web app from a text description') and gives a concrete triggering utterance. It explicitly distinguishes itself from the nearest sibling by adding 'Prefer this over write_files for full-site creation.' An agent can identify the tool without opening the schema.

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?

It splits the decision by client type: with a widget preview, polling is unnecessary; without a widget (CLI, script, scheduled run), the agent must poll check_task every ~30s with defined stop conditions (completed/deployed or failed) and then call get_app. The alternative (write_files) is named with the condition that selects this tool instead.

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