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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the asynchronous build status, approximate duration, expected_url and claim_token, unauthenticated guest behavior, 72-hour deletion of unclaimed sites, and free-tier constraints. This is rich, honest behavioral context that directly affects how the agent should invoke and follow up on the tool.

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 dense but every sentence carries critical information. It front-loads the core purpose, then immediately states the async nature, the don't-call-twice rule, and the auth-dependent behavior. No filler or redundant restatement.

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 tool with no output schema and complex runtime behavior, the description covers everything an agent needs: how to handle the immediate response, where to poll, how to avoid duplicates, and how auth state changes the result. There is no missing guidance that would cause incorrect invocation.

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%, so the baseline is 3. The main description adds value by explaining the consequences of parameters (guest builds vs signed-in builds, one-site limit, claim_url for unsigned users) and reinforces the 'plain-language description' requirement. The only reason it is not a 5 is that the schema already documents the parameters well, including minLength and examples; the description complements rather than fully compensates.

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 opens with a specific verb+resource pair: 'Build a brand-new hosted website from a plain-language description.' This clearly distinguishes create_site from siblings like edit_site, publish_site, and get_build_status. It does not merely restate the name or title.

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 gives explicit operational guidance: it returns before the site is ready, so the agent must poll get_build_status with claim_token; it warns never to call create_site twice for the same site; and it explains the signed-in vs guest flows. This goes well beyond vague 'use for creating sites' guidance.

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