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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine value by interpreting return fields (desired vs observed are separate, app_health reflects fline's checks, not_answering means failures for at least two minutes), which is real context beyond annotations. It stops short of describing response shape, timing, or auth needs.

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 sentences with little padding, but the phrasing is dense and awkward ('arrive separately and mean different things separately') and it is not front-loaded with the tool's purpose. The most important information, what the tool returns, is buried behind jargon.

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?

With no output schema, the description reasonably attempts to explain return semantics, which is the right instinct. However, for a status-retrieval tool it omits the core purpose statement and any project_id guidance, leaving key gaps for an agent deciding how to call it.

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 0% and the description says nothing about project_id, so the one required parameter carries no documented meaning beyond its self-evident name. The reference to get_project implies project scoping but does not define or constrain the argument.

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 title supplies the verb+resource ('Get deployment status'), but the description itself opens with a fragment ('Deployment state:') and never states what the tool returns or does. It jumps straight into field semantics (desired/observed/app_health), so an agent must infer the purpose from the name rather than the prose.

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?

There is no when-to-use guidance, no conditions distinguishing it from siblings like get_project, get_service, or get_events, and no prerequisites. The trailing '(see get_project)' points to a related read tool but does not frame it as an alternative or explain when to prefer one over the other.

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