Oh Dear

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered without the description. The description's added value is content disclosure (what account/team fields come back) and a doc link, but nothing about auth requirements, rate limits, or failure modes, so it is incremental rather than rich.

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 primary answer (who the connection is authenticated as and which team), then supporting detail, then a doc link. The field enumeration is slightly list-heavy but each item earns its place by telling the agent what questions this tool can answer.

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 an output schema present, return structure need not be spelled out, and annotations cover the read-only safety profile. Adding the enumerated fields plus the official doc URL makes this fully self-sufficient for a zero-argument context-fetch tool.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the rubric a 0-param tool baselines at 4. It correctly implies no arguments are needed by describing only contextual grounding value.

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 (get) and resource (the authenticated account/connection) and enumerates the concrete fields returned: authentication identity, team, timezone, monitor count, plan status. This clearly separates it from the sibling list_* tools, which enumerate monitors or destinations rather than the caller's own account.

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?

Explicitly frames when to reach for it: grounding answers about 'my' monitors and determining which team a question applies to. It gives clear positive context but names no alternative tool or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, covering the safety profile. The description adds real value beyond that by describing the response content (the prompt, conclusion, and rationale), which is more than the annotations convey.

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?

Three short sentences, front-loaded with the core action and followed by the motivating use case and a doc link. Every sentence earns its place, though the doc-link sentence is marginal rather than essential.

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?

For a simple two-parameter read tool with full annotation coverage, an output schema, and 100% parameter documentation, the description is complete: an agent knows what it does, when to call it, and what it retrieves. Nothing needed for correct invocation 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%, with both limit and monitor_id fully documented including defaults and bounds. The description adds no parameter-level detail, so the schema does the heavy lifting and baseline 3 applies.

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 ('Get the results of the AI check on a monitor') and then enumerates the content returned (what the AI verified, concluded, and why). No sibling tool covers AI checks, so it is unambiguously distinguishable from the surrounding get_* tools.

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?

'Use this to see why an AI monitor passed or failed' gives a clear selecting condition for the tool. It does not name an alternative or any exclusion, but for a uniquely-scoped read tool the usage context is well established.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful domain context about what a check consists of (each one has a current status and message) and that it reads application-internal signals, but says nothing about pagination, limits, or auth requirements beyond the docs URL.

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 tight sentences plus a docs link: purpose and examples first, differentiating constraint second, reference last. Every sentence carries information and nothing is redundant with the name or title.

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 an output schema present, the description needn't detail return shape, and the docs link covers deeper detail. It gives enough for an agent to select and call the tool, though it omits what happens when a monitor has no application health checks configured.

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%: monitor_id is documented as the monitor to query and only_with_issues as a filter for non-OK checks. The description adds no parameter-level semantics beyond that, so the baseline of 3 is appropriate when the schema does the heavy lifting.

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 ('Get the application health checks a monitored site reports back to Oh Dear') and enumerates concrete examples (queue depth, disk space, database connectivity, Horizon). It explicitly distinguishes itself from network-level siblings: 'surfaces problems inside the application rather than on the network,' which separates it from get_certificate_health, get_uptime_statistics, etc.

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?

Provides clear context for when this is the right check ('problems inside the application rather than on the network'), which implicitly routes the agent away from network-oriented siblings. It stops short of naming a specific alternative tool or stating exclusions/prerequisites, and there is no guidance on the only_with_issues flag as a scoping choice.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds meaningful behavioral context: the definition of 'broken' (4xx/5xx), that only the latest completed crawl is sampled, and that each entry carries the referring page. It stops short of noting pagination or result caps.

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?

One well-formed sentence with the key scoping qualifier embedded, plus a docs link at the end. Nothing is redundant and the core definition of 'broken' is front-loaded.

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 an output schema, full annotation coverage, and a single required parameter, the description supplies everything an agent needs: what is returned, the crawl window, and the included referring page. No material gap remains.

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?

Only one parameter and schema description coverage is 100%, so the schema fully documents monitor_id; baseline 3 applies. The description adds no format, range, or lookup guidance beyond what the schema already says.

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 ('List the broken links') and goes further by defining what counts as broken (dead URLs returning 4xx/5xx) and pinning the scope to the most recent completed crawl. An agent can distinguish this from get_crawl_results or get_sitemaps without opening the schema.

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 'most recent completed crawl' constraint implies the temporal boundary and helps route away from raw crawl tooling, but no sibling is named and there is no explicit when-to-use/when-not guidance. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world. The description still adds real behavioral context by noting the data is what 'Oh Dear last saw', implying a possibly stale snapshot rather than a live check.

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 tight sentences: purpose plus returned fields first, then the intended use, then a docs link. No redundancy or 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 need no further explanation, and the description still sketches the payload contents. For a single-parameter read tool, everything needed to call it correctly is present.

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 100% and the single monitor_id parameter is fully documented in the schema itself. The description adds no syntax, format, or lookup guidance beyond it, so the baseline 3 applies.

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 ('Get the SSL/TLS certificate ... for a monitor') and enumerates the returned fields (issuer, validity dates, expiry date, covered domains). This clearly separates it from siblings like get_application_health and get_domain_intel.

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?

'Use this to answer whether a certificate is valid or about to expire' gives an explicit triggering intent. It lacks any exclusions or named alternatives, but the use case is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds value by disclosing the scope (every check, or one type) and the shape of the result (current result plus one-line summary).

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: the first defines the scope and output, the second gives the use case. The documentation link is placed last and the key framing is front-loaded.

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?

Complete enough for a read-only summary tool – purpose, scope, filter behavior, and use case are all present, and an output schema exists to carry return structure. Slightly short of 5 only because it does not mention issue severity semantics.

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%, with check_type, monitor_id, and only_with_issues all documented in the schema including the enum. The description only restates the ability to filter to one check type, so baseline 3 is appropriate.

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 (get) and resource (result and summary for every check), and distinguishes itself from the sibling report tools by framing itself as the aggregate overview versus the per-type reports like get_broken_links or get_certificate_health.

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?

Explicitly positions the tool as the fastest way to answer 'is anything wrong right now' before drilling into a specific report, which is clear usage context. It does not name specific sibling alternatives by name, keeping it below a 5.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the fallback to an in-progress crawl, the meaning of mixed content (insecure http assets on an https page), and the internal/external counting scheme. It does not mention rate limits or pagination, but those are minor here.

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 main behavior is front-loaded in a single (long) sentence, followed by a short routing instruction and a docs link. Dense but every clause carries information; the parenthetical definitions are a touch heavy.

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-value explanation is unnecessary, and the description covers scope, fallback behavior and the sibling alternative. The only gap is explicit guidance on choosing between the two report modes, which an agent can infer from the enum descriptions.

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 report, monitor_id and limit are already fully documented with types, bounds and an enum. The description adds semantic color about what each report value represents but no new syntax or format detail, so the baseline 3 is appropriate.

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 ('Get what Oh Dear's crawler found on a site during its most recent crawl') and enumerates the two shapes of the result (mixed content vs. internal/external URL breakdown). It also explicitly distinguishes itself from the sibling get_broken_links, so an agent can route without opening a schema.

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?

Names the alternative explicitly ('For the broken links themselves, use get_broken_links') and clarifies that an in-progress crawl is used as a fallback when none has completed. It stops short of stating when to prefer mixed_content over crawled_urls, leaving that to the enum descriptions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds some value by disclosing what data is surfaced (schedule, status, ping history) and linking the API docs, but says nothing about auth requirements, pagination, or limits on the ping history window.

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?

A single dense sentence with the resource and contents front-loaded, followed by the motivating use case and a docs URL. No filler, though the sentence is long enough that the return contents and the purpose are packed together rather than separated.

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 an output schema present, return values need not be explained, and annotations cover the safety profile, so the description only needs to establish scope and contents — which it does, plus a docs link. The one gap is that it gives no hint about how far back ping history reaches or how the optional include flags change the payload.

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 all three parameters (monitor_id, include_log_items, include_failed_days) are already documented in the schema. The description's mention of 'recent ping history' loosely maps to the optional include flags but adds no format, default, or boundary detail. Baseline 3 applies when the schema does the heavy lifting.

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 (List) and resource (cron job checks) and defines the resource inline as 'heartbeat monitoring for scheduled tasks', which separates it from the uptime, certificate, DNS and broken-link siblings. It also enumerates what the listing contains (schedule, current status, recent ping history).

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 clause 'so you can see which scheduled jobs failed to report in' implies the use case (detecting silent cron failures), but there is no explicit when-not guidance and no alternative sibling is named for adjacent needs like check summaries or uptime statistics. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds a real trait beyond them — that responses can be very large and should be paged in with a small limit — which directly affects how the agent calls it.

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 what is returned, followed by the size warning and a docs link. Two sentences plus a URL, no filler, though the trailing link is the only mildly non-essential element.

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 an output schema present, return values need not be explained, and annotations carry the safety semantics. The description covers purpose, data volume, and a docs reference, leaving only minor gaps such as pagination/ordering of the history.

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 100%, so the baseline is 3, but the description adds practical guidance absent from the schema: an explicit recommended starting value of 3-4 for limit rather than just the documented default 10 / max 100. monitor_id meaning is left to the schema.

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?

Specific verb+resource: returns the DNS records Oh Dear last saw for a monitor plus the history of changes. It also states the concrete outcome ('spot when a record changed'), which no sibling tool covers, so the agent can distinguish it from the other get_* tools.

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 clear usage intent ('so you can spot when a record changed') and an operational caution to start with limit 3 or 4 because the payload can be large. It does not name exclusions or an alternative sibling, but none of the listed siblings overlaps in behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing data provenance (whois/RDAP, latest port scan, DNS blocklist) and the default-returns-all behavior, though it omits latency or freshness caveats for the scan/blocklist data.

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 behavioral content is front-loaded in one dense sentence before the documentation links, so an agent gets the essentials immediately. The three appended doc URLs are somewhat bulky but plausibly useful pointers rather than pure padding.

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 an output schema present, the description needn't explain return shapes, and it does cover all three data sections plus the default selection behavior. It is essentially complete for invocation; only the absence of any when-to-use guidance and freshness notes keeps it from the top.

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 both parameters are already documented in the schema, and the description largely restates the sections enum and the default. Baseline 3 is appropriate since it adds little syntax or format detail beyond what the schema provides.

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 states a specific verb (get) and resource (domain intel) and enumerates the three concrete sections returned — registration/expiry via whois/RDAP, open ports from the latest scan, and DNS blocklist status. This distinguishes it from nearby siblings such as get_dns_records or get_certificate_health without requiring the schema.

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?

It frames the tool as showing 'what the outside world can see about a monitored domain' and notes that all three sections return by default, which implies when the full payload is appropriate. However, it never states when to prefer this over a narrower sibling or when to limit sections, so usage is only implied.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so safety is established. The description adds genuinely non-obvious behavior: times are UTC, results are newest-first, and the downtime total is scoped only to the returned subset, which can mislead if the limit is small.

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?

Three sentences, front-loaded with what is returned and immediately followed by the caveat that matters most. Nothing is padding; the docs link is a reasonable trailing pointer.

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 an output schema present, return-value shape needn't be described, and annotations carry the safety profile, so the description is nearly complete for this read tool. Only the lack of explicit sibling routing keeps it from being fully complete.

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 100%, so the schema already documents all four parameters, making 3 the baseline. The description goes beyond it by clarifying the interaction between limit and the aggregate total, plus the UTC convention for the time filters, which is the kind of nuance the schema does not spell out.

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: list the outages recorded for a monitor, with start/end times. It implicitly separates itself from get_uptime_statistics and get_maintenance_periods by being about outages, but it never names or contrasts those siblings explicitly.

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?

It gives real operational guidance about the limit ('returns the most recent outages up to the limit you set... widen the limit before drawing conclusions'), which is useful when-to-use behavior. However, it never states when to prefer this over get_uptime_statistics or get_maintenance_periods, leaving tool selection to inference.

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

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

Annotations already carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful scope ('most recent' reports) and content context plus a docs link, but says nothing about rate limits, history retention, or what happens when a monitor has no Lighthouse data.

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, front-loaded with the action and resource, with zero filler. The enumeration of report contents is slightly long given an output schema exists, and the trailing docs URL is supplementary rather than essential, keeping it just short of maximal conciseness.

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 full annotations, 100% schema coverage, and an output schema present, the description does not need to explain return values or safety. It only omits edge-case behavior (empty results, monitors without Lighthouse enabled), which is a minor gap for a simple read tool.

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% — limit, monitor_id and include_json_report are each documented in the schema, including defaults and min/max. The description adds no parameter-level detail beyond reinforcing 'most recent' reports, so the baseline 3 applies.

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 ('Get') and resource ('Google Lighthouse reports for a monitor') and enumerates the payload (performance/accessibility/best-practices/SEO scores, Core Web Vitals, flagged issues). No sibling tool covers Lighthouse, so the agent can distinguish it from the surrounding get_* retrieval tools immediately.

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?

Usage is only implied: it retrieves reports 'for a monitor', so the agent infers it needs a monitor_id of a Lighthouse-enabled monitor. There is no explicit when-to-use/when-not guidance and no stated alternatives (nothing in the sibling list overlaps, but the description doesn't say so), nor any prerequisite about the monitor having Lighthouse configured.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful behavior: alerts are suppressed during active windows, times are in the team timezone, and it links to external docs. It does not spell out pagination ordering beyond what the schema says, so it stops short of 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?

Three sentences, each earning its place: scope definition, behavioral note, routing to the sibling, plus timezone and docs. Front-loaded with the core purpose; 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?

Output schema exists, so return values need not be explained. Given a simple read tool with full schema coverage and annotations, the description covers scope, the critical routing alternative, and a behavioral nuance (alert suppression). 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 coverage is 100%, with descriptions for limit (defaults, sort order, max) and only_active_or_upcoming already in the schema. The description adds no parameter-level syntax or defaults of its own, so baseline 3 applies.

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 (list) and resource (one-off maintenance windows on a monitor), and crisply delimits scope as 'the ones with a fixed start and end.' It explicitly distinguishes itself from get_recurring_maintenance_periods, so an agent can pick the right tool without opening a schema.

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 the exact routing condition: scheduled/repeating windows go to get_recurring_maintenance_periods instead. It also supplies domain context on why one would care (alerts are suppressed during a window), which is real selection guidance.

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

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

Annotations already establish the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is to add domain behavior — and it does, disclosing that alerts are suppressed while a window is active and that generated periods are only a recent sample. It stops short of covering permissions, rate limits, or result-size behavior.

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?

Three sentences, purpose and payload first, domain behavior second, reference link last — no filler. The closing URL is marginally useful rather than wasteful, though it could be dropped without loss.

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-shape explanation is unnecessary, and annotations carry the safety profile. What remains — what the tool returns conceptually, the alert-suppression semantics, and the sample nature of generated periods — is covered, making the definition sufficient to invoke 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 description coverage is 100%, so both parameters are fully documented in the schema and the baseline is 3. The phrase 'maintenance periods recently generated from them' loosely echoes include_generated_periods but adds no format or semantics beyond the schema's own text.

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?

It names a specific verb and resource ('List the recurring maintenance windows defined on a monitor') and adds the payload detail (schedule plus recently generated periods), which separates it in spirit from the sibling get_maintenance_periods. It never explicitly contrasts itself with that sibling, so an agent must still infer the boundary from names alone.

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?

Usage is only implied: you call it when you want the recurring window definitions and their recent generated periods for a monitor. There is no explicit when-to-use, when-not-to-use, or pointer to get_maintenance_periods, which is the obvious alternative for the same domain.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety behavior is covered. The description adds useful content scope (what fields are returned: indexes, sitemaps, URL counts, problems), which is real value beyond the annotations, but nothing about freshness, empty-result behavior, 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 compact sentences front-loaded with the purpose, then the return scope, then a doc link. Little waste; slightly more enumeration than strictly necessary.

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?

Output schema exists, so return values needn't be re-explained, and annotations cover the safety profile. For a single-param read tool the description is essentially complete; only cross-tool routing guidance is absent.

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 100% and the single parameter's meaning is fully documented in the schema. The description adds nothing about the monitor_id parameter beyond context, so baseline 3 applies.

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 (get sitemap check results for a monitor) and enumerates what the results contain: sitemap indexes, sitemaps, URL counts, problems. Clear, though it doesn't differentiate itself from similar check-result siblings like get_broken_links or get_crawl_results beyond the resource name.

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?

Usage is implied by the name and description (fetch sitemap results for a monitor), but there's no explicit when-to-use vs. alternatives like get_check_summary or get_broken_links. Acceptable for a narrow read tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that per-interval average response timings come back alongside the uptime/downtime percentages, but with an output schema present and the enum already listing the grouping values, the incremental behavioral disclosure is modest.

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 plus a docs reference; the core capability is front-loaded before the usage hint. Efficient, though the trailing documentation URL is the least essential element in an otherwise tightly written definition.

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 a rich schema and an output schema that defines the response shape, the description needs only to convey purpose and when to reach for it, which it does. The one real gap is that it never positions itself against the similar get_downtime sibling.

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%, including formats (YmdHis / ISO 8601), defaults ('now', 'seven days ago'), and the full group_by enum, so the schema carries the parameter burden. The description only echoes the date range and grouping concepts without adding format or constraint detail beyond the schema.

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 states a specific verb and resource ('Get uptime and downtime percentages for a monitor over a date range') and adds the grouping options and that average response timings are returned per interval. It is clear, but it does not differentiate itself from the close sibling get_downtime, which the agent could easily confuse with this tool.

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?

'Use this to answer how much downtime a site had' gives a concrete intent-based usage context, which is more than most tool descriptions offer. It stops short of naming exclusions or alternatives – notably it never says when to prefer get_downtime or get_check_summary over this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavioral value by describing the payload (status, issues, performance metrics), the dual list/detail mode, and a docs link. It does not mention pagination behavior or the default limit, which is the only remaining gap.

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?

Three sentences, front-loaded with the core action and return contents, then the mode switch, then the entry-point guidance, ending with a reference link. Every sentence earns its place with 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 need not be explained. Combined with full schema coverage, covered annotations, and explicit guidance on when to reach for this tool versus the detail mode, nothing an agent needs to invoke 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 all four parameters are already documented in the schema, which sets the baseline at 3. The description notes that monitor_id switches the call into a single-monitor detail mode, which is useful context, but it largely restates the schema's own wording for that parameter and adds nothing for limit, search, or only_with_issues.

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 (search/list) and resource (the team's monitors), and disambiguates the term by defining monitors as 'the websites, hosts and services Oh Dear watches, also called sites.' It also enumerates what comes back (up/down status, open issues, performance metrics), so an agent can tell it apart from the many get_* siblings.

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 when you need a monitor ID for another tool' gives explicit entry-point guidance, and 'Pass monitor_id to fetch the full detail for one monitor' explains the second mode of use. It does not name any competing sibling (e.g. get_uptime_statistics, get_check_summary) as an alternative, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safe-read profile is fully covered externally. The description adds domain context about what destinations mean per scope but says nothing extra about auth requirements, rate limits, or pagination behavior, so a mid score is right.

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?

A single front-loaded sentence delivers scope semantics, and a second short sentence routes to the alternative, followed by a docs link. Nothing is redundant and no clause could be dropped without losing meaning.

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?

Output schema exists, so return values need no explanation, and annotations fully cover the safety profile. With purpose, scope semantics, and the sibling alternative all stated, an agent has everything needed to select and invoke this tool 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 description coverage is 100%, so the baseline is 3, and the description exceeds that by explaining what each scope value actually returns rather than merely restating the enum. It still does not restate the conditional requirement of tag_name/monitor_id, which the schema already carries.

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 ("List where Oh Dear sends alerts") and then defines the three scope values so the agent knows exactly what is being listed for each case. It also explicitly names the sibling it is not (list_tag_groups), making it distinguishable without opening any schema.

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 per-scope usage semantics ("team" = team-wide alerts, "tag" = alerts for monitors carrying a tag, "monitor" = a single monitor's alerts) plus a named alternative for tag-group routing. The agent has both the when and the when-not.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results are public status pages with specific display fields, but says nothing about pagination, result limits, or auth requirements, so it only modestly exceeds the annotation baseline.

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?

Three short sentences, front-loaded with the core list behavior, then the optional single-fetch mode, then the entry-point hint and docs link. 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 need not be explained; the description still names the key fields. With one optional param, full schema coverage, and a docs link, an agent has everything needed to select and invoke this tool 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 description coverage is 100% for the single optional parameter, so the schema already documents it. The description's 'Pass status_page_id to fetch a single one' largely restates the schema description rather than adding format or edge-case detail, making the baseline 3 appropriate.

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 (List) and resource (the team's public status pages) and enumerates the fields returned (title, slug, custom domain, display settings). This clearly distinguishes it from siblings like list_status_page_updates, which operate on a different sub-resource.

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?

Explicitly says to pass status_page_id to fetch a single page and, more valuably, 'Start here when you need a status page ID for another tool' — clear entry-point routing. It lacks an explicit when-not-to-use or a named alternative tool, so it falls just short of a 5.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description adds ordering behavior ('most recent first') that is neither in the annotations nor the schema, which genuinely helps the agent reason about results. Pagination beyond limit is not described, keeping 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?

Three tight sentences: what it does first, then why/when to use it, then a docs pointer. No filler and the payload is front-loaded.

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 an output schema handling return values, annotations covering the safety profile, and full schema coverage on both parameters, the description only needs purpose, ordering, and usage – all of which it supplies. 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 both status_page_id and limit are fully documented in the schema. The description adds no syntax, format, or default detail beyond what the schema already provides, matching the baseline 3.

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?

State a specific verb (list) and a precise resource (incident updates posted on a status page), plus ordering ('most recent first'). An agent can distinguish this from the sibling list_status_pages (which lists pages, not their updates) without opening either schema.

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 two concrete selection conditions: inspecting what visitors are currently being told, and finding an update ID to edit. Clear context for when to reach for this tool, though it does not name a when-not case or an explicit alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description adds useful domain context about what a tag group does and links to the API docs, but says nothing about pagination or result shape (the output schema covers the latter).

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 tight sentences plus a docs link, with the primary action front-loaded. The second sentence earns its place by defining tag-group semantics, though the trailing URL is marginally low-value given the parameter docs.

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 annotations covering safety, a 100%-covered single-parameter schema, and an output schema, the description only needs to establish purpose and domain meaning, which it does. Minor gaps like pagination behavior are adequately handled by the structured fields.

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% and the single optional tag_group_id parameter is fully documented in the schema as fetching a single group. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 ('List the team's tag groups') and even enumerates what is returned (tags and notification destinations). It distinguishes itself from list_tags and list_notification_destinations by explaining the routing concept, though it never names those siblings explicitly.

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 or when-not-to-use guidance. The domain explanation ('A tag group routes alerts to destinations such as an email address...') helps an agent understand relevance, but nothing tells it when to pick this over list_tags or list_notification_destinations, nor whether the ID parameter switches it into a single-record fetch.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return shape (tags plus the monitors carrying each) and the routing role of tags, though it says nothing about pagination or limits.

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?

Three short sentences, front-loaded with the core action, then rationale, then a reference link. Every sentence earns its place with no filler or repetition of the title.

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?

For a read-only, single-optional-param list tool with rich annotations and an output schema, the description supplies everything needed: what is returned, why it matters, and where the docs live. Return values need not be restated since an output schema exists.

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% for the single optional 'search' parameter, so the schema already documents it. The description adds no syntax, matching behavior, or empty-result guidance for that filter, making the baseline 3 appropriate.

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 (list the team's tags) and adds the scope detail that each tag is returned with the monitors carrying it. It gestures at the tag-groups relationship but does not explicitly distinguish itself from the sibling list_tag_groups, so it stops short of a 5.

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 a concrete entry-point cue ('start here when you want to see how monitors are grouped') and explains why tags matter (notification routing through tag groups). It offers no explicit when-not or direct alternative routing to list_tag_groups, which keeps it at a 4.

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