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

The readOnlyHint annotation already covers the non-destructive nature, so the description doesn't need to repeat that. It adds valuable behavioral details: it reports elapsed_s and defines a failure condition (pending after ~5 minutes). This informs the agent about timing expectations and error interpretation, which is useful beyond the annotation.

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 exceptionally concise: two sentences that front-load the purpose, then usage, then behavioral detail. Every sentence adds distinct value with no redundancy. It is well-structured for quick parsing by an agent.

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 tool has no output schema, so the description's mention of 'reports elapsed_s' provides essential return-value context. It also covers the failure condition and usage. Missing details like full response structure or polling interval are minor given the tool's simplicity and the fact that it's a companion to build_deploy/build_go_live. It feels adequately complete for an agent to use correctly.

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 50%: poll_url has no description in the schema, but the tool description clarifies it as the URL returned by the deploy tools. This compensates for the missing schema documentation. The permanent parameter is already described in the schema, so the description doesn't need to repeat it. The added clarity for the required parameter earns a 4.

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 clearly states the tool's purpose: to poll a cloud deploy initiated by build_deploy or build_go_live. It specifies the resource (deploy) and the action (poll), and differentiates it from sibling tools like build_e2e_test_status and connector_status. The mention of the two parent tools makes the intent unambiguous.

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 explicitly states when to use the tool: after a deploy started by build_deploy or build_go_live, and instructs to pass the returned poll_url. It also provides a critical usage note about treating a pending launch after 5 minutes as failed. However, it doesn't explicitly mention alternatives or when not to use it, though the 'started by' clause provides a clear scope.

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