Get status

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

Annotations already declare readOnly, idempotent, closed-world, and non-destructive, so the safety profile is largely covered. The description still earns credit for adding non-obvious behavior: private monitors are included in results, draft notes are excluded, and an out-of-workspace app id returns not_found rather than erroring or empty. It stops short of describing result size or pagination, which keeps it from a 5.

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 scope and payload, then usage routing, then the default/error semantics. Four dense sentences with no restatement of the title or name; each one adds new information an agent needs.

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 spelled out, yet the description still tells the agent what categories of data come back and what is deliberately absent (draft notes). Combined with the entry-point guidance and error semantics, nothing required to call this correctly is missing.

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 100%, so the baseline is 3 and the schema already documents the app id format and the '*' const. The description adds semantic weight by explaining that omitting the param is equivalent to passing '*' and by describing the not_found failure mode for foreign ids, which the schema alone does not convey.

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 concrete verb and resource ('Read the current status of one app or every app') and then enumerates exactly what 'status' contains: overall state, monitors (including private ones), status page components, and open incidents with their latest published note. Sibling tools with overlapping domains (get_uptime, get_incidents) are explicitly positioned as history-only, so the boundary is 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?

'Start here: its app, monitor and incident ids feed the other tools' gives an explicit entry-point rule, and 'Use get_uptime or get_incidents for history' names the alternatives and the condition that selects them. The '*'-vs-omit behavior and the not_found case for out-of-workspace ids close the remaining ambiguity.

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