get_deployment

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context (polling cadence, terminal condition 'until running'), but omits what other statuses exist, error behavior, or how long a poll cycle should run.

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?

Two compact sentences, front-loaded with the action and followed by the polling constraint. No filler.

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 needn't be explained, and the polling behavior is covered. Still missing: the identifier's expected form and the set of possible status outcomes that would tell the agent when to stop polling.

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?

One required parameter, deployment_id, with 0% schema description coverage and the description never mentions it — no format, source, or where to obtain it. The description does not compensate for the schema gap as it should.

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: read deployment status for a given deployment. It's clearly distinguishable from list_deployments and list_projects by virtue of operating on a single deployment. No explicit sibling differentiation, but the resource specificity carries it.

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?

"Poll at most once per minute until running" gives real operational guidance for repeated invocation, which is more than most definitions offer. However, it never states when to prefer this over list_deployments, nor what to do on failure or terminal states other than running.

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