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

Annotations only cover readOnlyHint and openWorldHint, so the description carries real weight: it discloses the 30-day default and 366-day cap, that only active monitors are counted unless include_paused (with the pause semantics spelled out), and that limit slices the listing while totals always cover every matching monitor. These are non-obvious behaviors an agent could otherwise get wrong.

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?

Dense but every clause carries information, and the return-field enumeration is justified because there is no output schema. The routing guidance to siblings sits at the end rather than being front-loaded, and the semicolon-chained prose is close to run-on, costing a little clarity.

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 and seven optional parameters, the description fills the gaps that matter: metric definitions (uptime_pct, downtime, outage count, longest outage, MTTR with 'resolved outages only'), project totals, defaults, caps, and scope exclusions. Nothing an agent needs to call it 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, but the description adds meaning beyond the schema: the 366-day maximum period, that from/to accept an age like 30d, and that limit controls only the ranked listing while totals are unaffected. It does not restate the name/group substring semantics or the protocol list, which the schema already handles.

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+resource and scope ('Uptime of every monitor of the project over a period, worst first, in one call') and enumerates the returned metrics. It explicitly distinguishes itself from the two nearest siblings, get_monitor_uptime (per-day/week series) and list_outages (the outages themselves).

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?

Gives explicit use cases ('which monitors had the worst uptime' or an SLA overview) and names the alternatives with the condition that selects them. It also states an exclusion ('Healthchecks and servers are not included'), so an agent knows when this tool is the wrong pick.

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