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

Goes well beyond the readOnly/idempotent annotations: build duration of 15-25 minutes, that running is non-terminal and contains no page, that HTML is summarised by default to avoid flooding context, and that elapsed_seconds is server-measured build age. This is exactly the operational context an agent needs for long-poll behavior.

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?

Front-loaded with the core contract and free of padding in the opening lines, but the middle digression about a twenty-minute build becoming a handful of calls is restated at some length. Dense but slightly over-explained.

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?

No output schema exists, so the description carries the return contract itself — status stages, non-terminal running, summarized vs. full HTML, and elapsed_seconds — and it does so completely for a 3-parameter polling tool.

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?

With only 67% schema coverage, the description compensates: it explains the rationale for wait=300 (blocks until a material change, collapsing repeated reads) and the purpose of include_html (full page is tens of thousands of characters). It also explains the otherwise-undocumented elapsed_seconds return field.

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 a build's status and, once finished, the complete page. It is clearly the polling counterpart to siblings like build_page, though it never names that sibling to draw the contrast explicitly.

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?

Explicit when-to-use and how: poll with wait=300, use include_html only when the user actually wants the file (e.g. to save locally), and stop and re-poll silently when the stage is unchanged. It even covers the failure mode of idempotent resumption by ID instead of restarting.

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