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

Goes well past the annotations: it explains that repeat alerts stop but the recovery alert still fires, that acknowledging twice keeps the first acknowledgement, and that acknowledging a resolved incident succeeds without alert effect. It also discloses the required write scope, which is an auth prerequisite the annotations do not 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?

The core effect and the primary exclusion are front-loaded, and each subsequent sentence carries distinct information (recovery alerts, closing semantics, sibling exclusion, auth scope, idempotency). No sentence is redundant with another.

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 single-parameter mutation with an output schema, the description covers effect, exclusions, auth scope, idempotent behavior, and the return shape ("the get_incident shape"). An agent has everything needed to call it correctly and interpret the result.

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 schema already documents the uuid source (list_incidents) and the 404 behavior for foreign ids. The description adds no additional meaning about the incident_id parameter, so the baseline of 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 ("Mark an open incident as being handled") plus the concrete effect ("its repeat alerts stop"). It explicitly separates itself from closing the incident and from status page incidents, so an agent can distinguish it from siblings like post_status_page_update or get_incident 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 an explicit positive trigger ("Use it when someone is working on the outage") and two explicit exclusions: it does not close the incident, and it is not for status page incidents, with the alternative tool named in parentheses. Both when-to-use and when-not-to-use are covered.

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 only say the call is a non-idempotent, non-destructive write; the description adds far more: atomic rejection with nothing created, which HTTP statuses arise from which item faults, that only the first non-validation item error is reported while all validation errors are reported at once, and that a prefix-less plan 403 concerns the batch as a whole. It also specifies return contents and ordering ('one list_monitors row per created monitor, in request order'). No contradiction with the annotations.

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 purpose, prerequisite, and pre-check, which is good. But roughly half the text is dense error-parsing minutiae (the regex `^monitors\[(\d+)\]`, the note that index 3 is the fourth item, lead-in prefixes), which is useful yet verbose and crowds out the item-defaults guidance that lives only in the schema.

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 high-stakes atomic batch mutation, the description covers scope, authorization, failure modes, error identification, recovery action, and return shape. With an output schema present, it still adds the ordering guarantee, which is the one thing an agent needs to map results back to inputs.

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 would be 3, but the description adds real meaning: a fully worked TCP example with a single region and a 300-second interval floor, plus the rule that plan-limit 403s mean either the monitor count or the sub-60s quota is exceeded. That clarifies constraints the schema's min/max integers do not express.

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?

Opens with a specific verb, resource, and batch bounds ('Create 1 to 100 monitors in one call, all or nothing') and immediately names the sibling it replaces for the single-item case ('for a single monitor use create_monitor'). An agent can distinguish it from bulk_update_monitors and create_monitor without reading 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 routing ('for a single monitor use create_monitor'), a prerequisite ('Requires a key with the write scope'), and a recommended pre-check ('call get_plan_usage first to check the batch fits'). The all-or-nothing semantics also tell the agent when it must fix and resend the whole call.

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?

Adds substantial context beyond the annotations: all-or-nothing atomicity, that no checks run and open incidents close without alert, the write-scope requirement, and that re-pausing is not an error. These are behavioral facts the idempotent/destructive hints alone would not 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?

Front-loads the action and scope, then routes to alternatives, then states prerequisites and return shape. Dense but every sentence carries distinct information; 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, yet the description still names the return ('list_monitors rows after the change, in request order'), and the auth requirement plus atomicity behavior are covered. Nothing needed 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 coverage is 100% and the schema already documents the 422 duplicate-id and 404 unknown-id behavior, so the baseline is 3. The description's inline example clarifies invocation format and reinforces the atomic failure semantics ('all or nothing'), adding modest value over 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?

States a specific verb and resource with scope: 'Pause up to 100 monitors in one call'. It also explicitly distinguishes itself from pause_monitor (single) and create_maintenance_window (silence while checks run), so the sibling 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?

Gives explicit when-to-use ('stop monitoring a whole project or group found with list_monitors') plus two named alternatives with the condition that selects each. No inference required.

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 cover safety (idempotent=true, destructive=false), and the description adds substantial context beyond them: transactionality ('all or nothing'), resulting state (PENDING, checked next tick), the 403 plan-limit behavior with no partial change, and the no-op on already-running monitors. No contradiction with idempotentHint or destructiveHint.

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-loads the batch semantics, then routing, then auth/preconditions, then return shape, then example. Every sentence carries distinct information; no filler or restatement 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 single-parameter bulk mutation, the description covers scope, alternatives, permissions, failure modes, no-op behavior, and return format — everything an agent needs. An output schema exists, and the description's brief return note is complementary rather than redundant.

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 already documents the 1-100 distinct-uuid constraint plus 422/404 handling, so baseline is 3. The description adds a concrete invocation example and states the return order is the request order, giving slightly more than the schema alone.

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 (resume) plus resource (monitors), with scope stated (up to 100 paused monitors, all-or-nothing). It explicitly distinguishes itself from resume_monitor and check_now, so an agent can route without opening sibling schemas.

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 two alternatives with their selecting conditions: resume_monitor for a single monitor, check_now for an immediate check on an already-running monitor. Also states the auth prerequisite (write scope) and the plan-limit failure path with a pointer to get_plan_usage.

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 only declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description goes well beyond that with atomic failure semantics, the 10-tag ceiling that rejects the whole call, tag normalization rules (trim/lowercase/dedupe, 50 chars, allowed character set), and the 422/404/429 failure modes. It also discloses a concrete throttling model — 10 calls per minute shared with bulk_update_monitor_tags, scoped per calling address or per user — which no structured field conveys.

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 critical scoping and routing information is front-loaded, and the worked example at the end is genuinely useful for constructing a call. It is a dense single block, however: rate-limit and tag-validation rules run together without visual separation, and 'Returns heartbeats_updated' duplicates information an output schema already provides.

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 batch mutation with three parameters and an output schema, the description covers everything an agent needs: atomicity, preconditions, error codes, rate limits, tag format constraints, and sibling routing. Return values are correctly left to the output schema rather than restated at length.

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 already 100%, so the baseline is 3; the description earns more by adding semantics the schema lacks, notably that add and remove must be disjoint (422) and the final tag-set formula '(its tags | add) - remove'. It also advises reusing names from list_tags and specifies the tag character/format constraints, though it leaves the maxItems and repeated-id 422/404 detail largely 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?

The opening sentence names a specific verb pair (add and/or remove), the resource (tags on heartbeats), the batch bound (up to 300), and the atomicity (all or nothing), plus a precise formula for the resulting tag set. It then explicitly distinguishes itself from bulk_update_monitor_tags, update_heartbeat, rename_tag and delete_tag, so an agent can route without inspecting schemas.

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 states when to use this tool (retag many jobs at once) and names each alternative with the exact condition that selects it: monitors go to bulk_update_monitor_tags, a full replacement on one heartbeat goes to update_heartbeat, and global renames/deletes go to rename_tag or delete_tag. Preconditions (write scope, at least one of add/remove) are spelled out rather than 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?

The annotations already declare the safety profile (not read-only, idempotent, non-destructive), so the bar is lower, yet the description adds substantial behavior: all-or-nothing atomicity, a write-scope key requirement, plan rules that produce a 403, and per-monitor incompatibilities (multiple regions on SSL/DNS/port-list TCP, interval under 300) that produce a 422 keyed by monitors[<i>]. It also warns that the returned rows show the interval but not the other settings, which is a genuinely non-obvious 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?

It is a dense single paragraph that is front-loaded with the core action and limit, followed by exclusions, permissions, failure modes and an example in a sensible order. The change_alerts_enabled explanation is partly duplicated in the changes schema description, and the closing example is fairly long, so it is not maximally tight.

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 nested, atomic bulk-mutation tool this covers everything an agent needs: scope and limits, permissions, plan-level and per-monitor failure semantics with error codes, atomicity, and how to read back the settings that the returned rows omit. The output schema exists, and the description appropriately only summarizes return shape rather than restating 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: change_alerts_enabled is an opt-in whose alerts start in a later release and defaults to false, and conditional per-monitor constraints on regions and interval are stated that the schema's bounds do not capture. The example payload also demonstrates the monitor_ids/changes nesting.

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 opening sentence gives a specific verb (Set), an explicit list of settable settings, a scope limit (up to 100 monitors in one call) and an atomicity guarantee. It also explicitly excludes config/name and tags, naming the sibling tools that handle those, so the tool is distinguishable from update_monitor and bulk_update_monitor_tags 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?

States when to use it, gives a concrete motivating example (moving twenty PING monitors to other regions), and names two alternatives with the exact condition that routes to each (update_monitor for config/name, bulk_update_monitor_tags for tags). That is explicit when, when-not and alternatives.

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 cover safety (readOnly=false, idempotent=true, destructive=false), and the description adds substantial context beyond them: strict all-or-nothing atomicity, the exact set-algebra applied per monitor, required write scope, the 422 conditions (overlapping add/remove, >10 resulting tags, duplicate ids), tag normalization rules, the 10/min shared rate limit with its 429 behaviour, and the monitors_updated return. The destructiveHint=false is consistent with tag removal being an idempotent set operation rather than data deletion.

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 purpose, then alternatives, then preconditions, then limits — a logical order with essentially no filler, and the inline JSON example is compact and directly usable. It is dense and long for a three-parameter tool, and the parenthetical explanation of rate-limit accounting scope could be shortened 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?

Given a bulk mutation with an output schema present, the description supplies everything an agent needs to call it correctly and to recover from failures: atomicity semantics, auth scope, per-item and call-level validation failures, rate-limit and retry hints, and the name of the returned field. No material gap remains for the listed siblings or parameters.

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 already 100%, so 3 would be the floor; the description earns more by adding contract-level semantics the schema cannot express — add and remove must not overlap, at least one is required, the ≤10 resulting-tags ceiling, trim/lowercase/dedupe normalization, and the allowed character set. It stops slightly short on how add and remove interact when the same tag appears in existing state, which is why it is not a 5.

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?

Opens with a specific verb+resource (add/remove tags across up to 300 monitors in one call) and immediately frames the scope ('retag a fleet'), which distinguishes it from update_monitor, bulk_update_monitors, and bulk_update_heartbeat_tags by name. An agent can select this tool 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?

Explicitly routes each neighbouring case: heartbeats -> bulk_update_heartbeat_tags, whole-list replacement for one monitor -> update_monitor, global rename/drop including heartbeats -> rename_tag/delete_tag. It also gives positive guidance ('reuse names from list_tags rather than inventing near-duplicates'), which pre-empts a common misuse.

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?

Adds substantial behavior beyond the annotations: the call returns the monitor record rather than a check result, requires write scope, silently no-ops on repeat calls within 30 seconds or on paused monitors, and returns 429 past 10 calls/minute with the wait seconds in the response. The per-caller rate-limit scoping (address for API keys, user for app connections, never per key/organization) is precisely the kind of operational detail an agent cannot infer from annotations.

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?

Six short sentences, each carrying distinct information: mechanics first, then return semantics, alternatives, auth, no-op edge cases, and limits. 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?

An output schema exists, yet the description still clarifies the crucial return-value trap (monitor record, not a check result) and the follow-up call needed for the outcome. Auth, rate limits, and silent no-op conditions cover the remaining gaps for a mutation-style scheduler 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 coverage is 100% and the single parameter already documents the uuid source and 404 behavior, so the description adds no parameter meaning of its own. 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 and resource: 'Queue one existing monitor to run on the scheduler's next tick instead of waiting out its interval.' It immediately separates this from check_target (no monitor yet) and resume_monitor (paused monitor), so an agent can route correctly without reading 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 an explicit use case ('for example to confirm a fix') and names two alternatives with the condition that selects each: check_target for an unmonitored target, resume_monitor for a paused monitor. It even explains the follow-up workflow ('call get_monitor or list_check_results a moment later').

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses that the region is chosen by Fettle, interprets the 'unknown' status as 'no definite answer came back, not a failure', states the required key scope (write), and describes rate limiting per address/per user with the 429 and retry_after semantics. These are operational facts an agent cannot get from the annotations.

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 and dense: purpose, return fields, usage rule, alternative, auth, rate limit, example — each sentence does work. Minor waste in enumerating return fields (status, region, response_time_ms, status_code, error, failure_kind) that a dedicated output schema already covers.

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 for a probe tool with a nested, highly constrained config schema and an output schema: the description covers purpose, failure semantics of 'unknown', auth scope, throttling behavior, and the one ambiguity an agent would hit (region selection) without duplicating the schema's field-level detail.

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 already 100%, so the schema carries the parameter burden; the description still adds value with a concrete invocation example and the clarification that a probe uses one Fettle-chosen region (so the config region rules do not apply). It does not restate the type enum or target constraints, correctly leaving those 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?

States a specific verb and resource: 'Run one real check of a target from one region chosen by Fettle, without creating anything.' The non-mutating nature and single-region scope are stated up front, so an agent can distinguish it from create_monitor and check_now 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?

Explicit when-to-use: 'Use it before create_monitor to catch a typo or an unreachable host', plus the decision rule 'a down result does not stop you creating the monitor'. It also names the alternative for the other case: 'For a monitor that already exists use check_now'.

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 only declare the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds real behavioral context beyond them: write-scope key requirement, plan caps returning 403, 422 on invalid arguments, how lateness is computed after the first success ping, and that a /fail still marks it DOWN. It also states what comes back (the heartbeat with ping_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?

Front-loaded with purpose, then alternatives, then ping semantics, then preconditions and the example — a sensible order with no filler sentences. It is dense and long for a description, but each clause carries operational information rather than restating the name.

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 creating tool with an output schema, it covers what the description must: prerequisites (write scope), failure modes (403, 422), timing semantics, the sibling alternative, and a sample payload. Nothing an agent needs in order to call it correctly appears to be 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%, so the baseline is 3; the description still adds value by explaining the period_seconds/grace_seconds interaction in terms of when an alert fires and by giving a realistic example configuration. It does not add much for tags, channel_ids or notification_cooldown_seconds beyond the schema 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?

States a concrete verb and resource ('Create a heartbeat') and immediately clarifies the concept as a scheduled job reporting to a ping_url, then names the sibling to use instead for URL/host/port probing (create_monitor). An agent can distinguish this from create_monitor 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 explicit when-to-use cases ('cron jobs, backups and workers that should report in') and an explicit when-not-to-use with the alternative ('to probe a URL, host or port from outside use create_monitor'). It also spells out how the job should call ping_url, /start and /fail, which is usage guidance the schema cannot express.

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 only cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds substantial behavior beyond that: monitors keep being checked but no incident/alert fires, write-scope auth is required, plan caps produce a 403, and invalid args produce a 422 naming the field. Return value is only named, but an output schema exists. Slight gap is that idempotency/duplicate-creation behavior is not discussed, though the annotation hints 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 the purpose in sentence one, then behavior, alternatives, auth, error modes, and a worked example in descending priority. Dense but every sentence carries distinct operational information; nothing is redundant with the name or schema.

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 an 8-param write tool with annotations and an output schema, the description supplies the missing pieces an agent needs: effect on monitoring, sibling routing, auth scope, quota failure mode, validation failure mode, and a concrete call. Nothing material 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%, so the baseline is 3. The description goes modestly beyond by giving a complete example call that demonstrates the MONITOR-scope + monitor_ids + dtstart + duration_minutes combination and pointing at list_monitors as the id source, which helps the agent assemble a valid request rather than just read field docs.

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 ('Create a ... maintenance window') and immediately qualifies scope ('one-time or recurring', 'some or all monitors') and effect ('silences alerts'). It also distinguishes itself from pause_monitor and pause_heartbeat, so an agent can route correctly 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?

Explicit when-to-use ('around a deploy or reboot'), explicit alternative ('instead of pause_monitor'), explicit exclusion ('does not cover heartbeats (use pause_heartbeat)'), and a precondition for the recurring case ('run preview_maintenance_window first'). Nothing is left 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?

Beyond the annotations (which only declare it is a non-destructive, non-idempotent write), the description discloses the write-scope requirement, the 403 plan-limit behavior naming the broken limit, that paused monitors still count toward limits, and that invalid arguments return 422 naming the field. It also explains change_alerts_enabled's deferred-alert semantics. It does not say whether creation is retryable or what happens on partial failure, which keeps it 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?

Front-loaded with purpose, then routing to siblings, then prerequisites, then the example — a sensible order with no filler. A couple of clauses duplicate schema text (the change_alerts_enabled default) and the plan-limit sentence is dense, but nothing is wasted.

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 14-parameter tool with a nested config object and 6 required fields, the description covers the prerequisites, error taxonomy (403/422), plan constraints, and a worked example. Since an output schema exists and the return is described as the get_monitor shape, return values need no further explanation.

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 real meaning the schema cannot: the worked example is explicitly labeled as reflecting a one-region plan and warns not to copy interval_seconds and regions from it. It also reinforces that change_alerts_enabled defaults to false and that an invalid argument is a 422 naming it.

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 with scope: 'Create one monitor that checks a URL, host or port on a schedule from one or more regions', and pins the return shape ('in the get_monitor shape'). The word 'one' plus explicit routing to bulk_create_monitors and create_heartbeat separates it from its nearest siblings without needing their schemas.

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 when-to-use-alternatives: check_target first for typos/unreachable hosts, bulk_create_monitors for several monitors, create_heartbeat for jobs that report in rather than being probed. Adds a prerequisite ordering ('call get_plan_usage first') tied to a named failure mode (403).

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 only supply the generic mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds substantial beyond-annotation behavior: public visibility, subscriber email fan-out, the RESOLVED branch that records a closed incident and emails nobody, required write scope, and a precise 10-per-minute shared rate limit with the 429 wait-seconds behavior and its scoping key.

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 core action and visibility warning, and every sentence carries actionable information (alternatives, prerequisites, rate limits, example). It is a dense single block, though, and would read more cleanly if the side-effect, rate-limit, and example material were 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?

For a non-idempotent create tool with an output schema already covering return values, the description covers auth scope, notification side effects, rate limits, error semantics, and sibling routing. Nothing an agent needs to call it safely and 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 by explaining the side effect of the status parameter (any status but RESOLVED notifies every confirmed subscriber at once; RESOLVED sends nothing) and by giving a concrete example tying page_id to list_status_pages. The enum values themselves are 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?

States a specific verb and resource (open a new incident on a status page with its first message) and explicitly distinguishes itself from the sibling post_status_page_update for adding to an existing incident. An agent can identify this as a create operation for incidents rather than updates without inspecting 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?

Gives explicit routing: use post_status_page_update to append to an existing incident, draft_status_page_post to draft text first, and confirm wording with the user before calling because it is public and emails subscribers. These are concrete when-to-use, when-not-to-use, and prerequisite instructions rather than implied 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 destructiveHint=true and idempotentHint=true, yet the description still adds real behavioral context beyond them: the ping_url returns 404 afterward, no tool can restore it, and a write-scoped key is required. The return shape is restated from the output schema but the irreversibility and auth requirements are genuinely additive.

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 compact sentences, each earning its place: what it does, when to use it versus the alternative, and the auth/return facts. The most consequential fact (permanent deletion) 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?

Covers the destructive nature, the irreversibility, the required scope, and the sibling alternative, while the output schema carries the return value and annotations carry the safety profile. Nothing an agent needs 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% and the single heartbeat_id parameter is fully documented in the schema, including the 404 behavior for foreign or already-deleted ids. The description adds no parameter-level detail 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 ('Delete one heartbeat') and immediately pins down the scope ('for good'), which distinguishes it from pause/update siblings. An agent can tell this apart from pause_heartbeat or delete_monitor 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?

Explicit when-to-use ('only when the user asked for deletion') and names the alternative for the adjacent case ('to stop alerts for a while use pause_heartbeat'). Both the condition and the routing target are given, leaving nothing 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?

Adds substantial context beyond the annotations: the effect is immediate ('alerts for its monitors resume at once'), it is unrecoverable ('no tool restores it'), and it requires a key with the write scope. The annotations declare destructiveHint=true, but the description tells the agent what is actually destroyed and that recovery is impossible.

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 clauses covering effect, alternative, and prerequisites, with the destructive consequence front-loaded. No filler sentences.

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 destructive single-parameter tool, everything needed is present: irreversibility, side effect on monitors, the safer alternative, auth scope, and return shape. The output schema exists, so restating the return value is a minor redundancy rather than a gap.

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 with 100% schema description coverage, so the schema already carries the semantics including the uuid format and the 404 condition. The description adds no additional parameter-level detail, which is the baseline 3 for a fully documented 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?

States a specific verb and resource ('Delete one maintenance window') and immediately distinguishes it from the sibling update_maintenance_window by contrasting deletion with suspension. An agent can route correctly 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?

Explicitly names the alternative and the exact condition that selects it: 'To suspend a window but keep it, use update_maintenance_window with enabled false.' This is genuine when-to-use/when-not guidance rather than implied usage.

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 flag destructiveHint=true and idempotentHint=true, but the description adds the irreversibility guarantee ('no tool restores it'), the side effect on monitoring ('stops being checked'), the authorization prerequisite ('Requires a key with the write scope'), and the 404 semantics on unknown/deleted ids. These go meaningfully beyond the annotation flags.

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 and well front-loaded: the destructive effect and irreversibility come before the alternative and the prerequisite. The trailing 'Returns {"success": true}' restates what the existing output schema already conveys, a minor redundancy that keeps it short of a perfect score.

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 single-parameter destructive tool with full annotation coverage and an output schema, the description supplies exactly the missing pieces: reversibility, authorization, sibling routing, and bulk-delete absence. An agent has everything needed to call it correctly and safely.

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 monitor_id parameter is fully documented in the schema (uuid format, source from list_monitors, 404 on invalid/deleted id). The description therefore does not need to compensate and adds no parameter-level detail the schema lacks — baseline 3 is correct.

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 ('Delete one monitor') and immediately describes the effect: it stops being checked and disappears from the organization's monitors, with no restoration path. It also explicitly contrasts with the closest sibling (pause_monitor) and rules out a bulk variant, so an agent can select it confidently without opening another 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?

Explicit when-to-use ('only when the user explicitly asked for deletion'), explicit when-not ('otherwise prefer pause_monitor, which keeps the monitor and its history'), and an explicit scope exclusion ('There is no bulk delete'). Nothing is left 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 declare destructiveHint=true and readOnlyHint=false, but the description goes further: it states the effect is immediate, that subscribers are not notified, that it is irreversible ('no tool restores it'), and that a write-scoped key is required. That is exactly the extra context annotations cannot carry.

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-loads the destructive outcome and the alternative route in three tight clauses with no filler. The closing 'Returns {"success": true}' is redundant given the output schema exists, a small waste.

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 destructive, irreversible mutation the description covers effect, notification behavior, reversibility, auth scope, and the correct alternative tool; return values are already covered by the output schema. An agent has everything needed to call it safely.

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 schema already explains both page_id and incident_id, including the 404 behavior and which list tool supplies each id. The description adds no parameter-level detail, 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?

Specific verb (remove) plus resource (status page incident and its timeline), and it explicitly distinguishes itself from create_status_page_incident and update_status_page_incident by describing the delete-only semantics. An agent can identify the right sibling 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 an explicit when-to-use ('an incident posted by mistake') and an explicit when-not with the named alternative ('to close a real one use post_status_page_update with RESOLVED'). Nothing is left 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 declare destructive=true, idempotent=true, readOnly=false, but the description adds behavior beyond them: the tagged items survive, no tool can restore the tag (irreversibility), a write-scoped key is required, and deleting an unattached tag is not an error (counts 0). These are meaningful operational facts not derivable from the annotations.

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 effect and its scope, then alternatives, then prerequisites, then edge cases and return shape. Every clause carries distinct information with no filler or repetition.

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 destructive, single-parameter mutation with an output schema present, the description covers effect, irreversibility, alternatives, auth requirement, and the empty-input edge case. An agent has everything needed to invoke it 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?

With one parameter at 100% schema coverage, the schema already documents the 'tag' argument and its format ('exactly as list_tags shows it'). The description adds little parameter-level meaning beyond restating that the tag is echoed back in the response, 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 (remove) and resource (tag) plus the exact scope: 'from every monitor and heartbeat that carries it'. It explicitly contrasts itself with the two nearest siblings (bulk_update_monitor_tags for selective removal, rename_tag for renaming), so an agent can distinguish it 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 explicit when-to-use ('retire a tag across the organization') and two when-not cases with named alternatives and their selecting conditions ('take it off chosen monitors only use bulk_update_monitor_tags with remove'; 'to rename it use rename_tag'). Nothing is left 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?

Consistent with readOnlyHint/idempotentHint and adds meaningful context beyond them: nothing is posted, no subscriber is emailed, and the posting siblings do email subscribers. It further discloses error semantics (Not found, resolved incident 409, incident_id + component_ids "Invalid request:") and the meaning of the basis field (NONE/CAUSE/DIAGNOSIS) with guidance to surface it and let the user edit.

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 side-effect disclaimer and the drafting-vs-posting distinction, which are the highest-value facts. It is dense but slightly overlong, and the long enumeration of return fields (kind, title, status, body, component_ids, basis, source_incident_ids, existing_incident_ids, generated_at) duplicates the output schema.

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?

Covers everything an agent needs: confirmation workflow, draft-vs-post routing, duplicate-avoidance via existing_incident_ids, error strings, a pointer to list_status_page_incidents, and a call example. With an output schema present, the extra return-field prose is redundant rather than 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%, so the baseline would be 3, but the description adds real meaning: the incident_id/component_ids mutual exclusion, the auto-resolve rule ('says resolved once every outage behind it has recovered'), and the resolved-incident 409 interaction. It does not add format details beyond what the schema already states.

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 opening sentence names a specific verb and resource ("Write the text of the page's next incident post from the monitor outages affecting it") and immediately disclaims side effects. It cleanly separates this drafting tool from its siblings create_status_page_incident and post_status_page_update, which it names 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?

Gives explicit when-to-use routing: omit incident_id to draft a new incident, supply it to draft the next update of an open incident. It also names the two downstream posting tools, requires user confirmation before calling them, and tells the agent to prefer updating an existing incident over opening a duplicate when existing_incident_ids is populated.

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, so 'it creates nothing' is largely redundant. The description still adds genuine value by describing what the list contains (port number plus the service that usually listens on it) and by warning how the data is consumed downstream (one monitor counted, fails naming every answering port).

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 purpose in the first clause, then uses. The final sentence is long and packs create_monitor configuration details that arguably belong in that tool's own docs, though they are actionable for completing the workflow.

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 zero-parameter preset lookup with rich annotations and an output schema, this is more than sufficient: purpose, return content, safe-to-call status, and the intended downstream workflow are all covered.

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, which is the baseline-4 case; nothing in the description is needed to disambiguate arguments. The mention of the 1-20 distinct ports / interval_seconds constraints pertains to create_monitor's payload, not this tool's 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?

States a specific verb and resource with scope: 'List the ports that should never be reachable from the internet (databases, queues, admin panels).' It also names the return content, so an agent knows this is a static preset lookup rather than a scan of any particular server, distinguishing it from siblings like check_target or get_monitor.

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 when to use it ('Use it to pick ports when asked to watch a server for exposed services'), what it does not do ('it creates nothing'), and names the follow-up tool with the exact config shape, port/region/interval constraints, and the failure semantics of that call.

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), and the description adds genuinely useful semantic context on returned fields such as last_duration_ms being measured from /start to success ping and overdue_at meaning the late-report time. It stops short of discussing pagination or error behavior beyond the schema's 404 note, so a 4 rather than 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?

Purpose and routing are front-loaded in the first and last sentences, which is good structure. However, the long enumeration of returned fields is partly redundant given an output schema exists, so it is not maximally economical.

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 single-parameter read tool with annotations and a full output schema, the description covers purpose, usage, alternatives, and field interpretation adequately. The field list slightly duplicates the output schema rather than adding new information, leaving a minor gap in efficiency rather than completeness.

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%, with the schema already documenting that heartbeat_id comes from list_heartbeats and that foreign/deleted ids yield 404. The description adds no parameter-specific meaning, 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 ('Read one heartbeat in full') and explicitly distinguishes itself from get_monitor ('probed monitors are get_monitor'), so an agent can separate this from the closest sibling 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 the use case ('answer whether a job ran, how long it took and when it is next due') plus explicit alternatives for the adjacent tasks: list_heartbeats to find one, update_heartbeat to change it, get_monitor for probed monitors. Nothing is left 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 cover the read-only/idempotent safety profile, and the description adds real context beyond them: which alert types (SSL, change, domain expiry) never appear in an incident, and the precise provenance semantics of acknowledged_via (MCP vs stdio fettle-mcp vs API_KEY) and acknowledged_by_label. The cost is that much of this is a field-by-field recital of the response, which the output schema already carries.

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-loading is good, but the body is a ~200-word run-on that enumerates every response field and buries the useful distinctions (alert-type exclusions, acknowledgement provenance) inside nested parentheses. A large share of the text restates the output schema rather than helping the agent call the tool.

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 one-parameter read tool with an output schema and full annotations, nothing an agent needs is missing and the sibling routing is thorough. It overshoots by re-specifying return fields that the output schema already defines, which is redundant rather than incomplete.

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 is fully documented in the schema, including the uuid source and the 404 on cross-organization ids. The description adds nothing further about incident_id, 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?

"Read one incident in full, with every alert sent for it" gives a specific verb and resource and immediately distinguishes this from list_incidents (find), acknowledge_incident (mutate), and get_incident_context (person data), all of which are named or implied. An agent can choose correctly 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?

Explicit routing: use list_incidents to find incidents, acknowledge_incident to stop reminders, get_incident_context for the person's name and email. It also states the positive use case (checking alert delivery and acknowledgement provenance), so both when and when-not are covered.

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?

Beyond the readOnly/idempotent annotations it discloses retention limits (old incidents return empty regions, recent_checks and buckets), the heartbeat exception (no checks, null regions_since and timeline), that an absent bucket means no checks rather than failure, and a prompt-injection warning about last_error/error_message. It also explains why acknowledgement fields can be null per source.

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?

Purpose and usage are front-loaded, but the return-value section is a single dense wall of text that restates field-by-field structure already carried by the output schema. The source/label null-permutations are the worst offender and could be compressed without losing the non-obvious rules.

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 single-parameter read tool, the description covers the real pitfalls an agent would hit: retention gaps, heartbeat incidents, null acknowledgement semantics, and untrusted text. It leans on the output schema for shape rather than repeating it in a structured way, but nothing operationally important 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% and the single incident_id is fully documented in the schema, including the 404 behavior for foreign ids. The description adds no additional meaning about the parameter, so the baseline of 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?

The first sentence states a specific verb and resource ('Read everything around one incident beyond its row') and enumerates the sub-resources returned (acknowledgement, region checks, timeline, downtime). It is explicitly differentiated from get_incident, get_incident_diagnosis and list_check_results by 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?

The description gives a concrete decision rule ('Use it to tell an outage seen everywhere from one region, how long it was really down, and who acknowledged it by name') and then routes away from three named siblings with the condition that selects each. Nothing is left 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?

Beyond the read-only annotations, the description discloses that results are observations rather than proven causes, explains READY/PENDING/UNAVAILABLE states, nullability for agent and repro, redaction behavior, write scope needed by suggested calls, deploy findings, and detail_level effects. This is unusually rich behavioral context with no contradiction of annotations.

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 opening sentence and routing are front-loaded and useful, but the description becomes a long, dense paragraph with many nested parenthetical details. The information is relevant, yet the structure would be much easier to scan as short sections or bullets.

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 complex diagnosis tool, the description covers the important output states, nullable fields, redaction behavior, suggested next calls, deploy-related findings, and detail-level limitations. Together with the output schema and annotations, an agent has enough context to call and interpret it 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%, and the description adds only modest parameter-specific context by clarifying that incident_id comes from an open DOWN monitor incident in list_incidents. The phase semantics are already largely documented in the schema, 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?

The description states a specific verb and resource: read what changed around a monitor incident, computed from existing checks. It distinguishes itself from siblings by naming get_incident and list_check_results and telling the agent to start here for an open DOWN incident or pasted alert.

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 explicit when-to-use guidance: use this first for a DOWN monitor's open incident or a pasted alert, before get_incident or list_check_results. It also routes the agent elsewhere for raw checks and for the incident row and alerts, leaving little ambiguity.

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 closed-world, so the safety profile is fully covered. The description adds the return payload shape (schedule plus next_occurrences with start/end), but with an output schema present this is largely redundant and it says nothing about permissions or rate 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 the usage case, then the sibling routing. Every clause 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?

For a one-parameter read with a full output schema and complete annotations, the description covers purpose, usage, and alternatives. Nothing an agent needs 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 coverage is 100% and there is a single required parameter, so the schema already documents window_id fully. The description adds no syntax, format, or sourcing detail beyond what the schema provides, making the baseline 3 correct.

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 one maintenance window') and immediately scopes it against siblings by naming preview_maintenance_window and list_maintenance_windows. An agent can tell it apart from the other maintenance-window tools 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?

Explicitly gives the selecting condition ('Use it to confirm when a recurring window fires next') and routes to the two alternatives with their own conditions ('to check a schedule before saving it', 'to find a window'). Nothing is left 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 declare readOnly, idempotent and non-destructive, so safety needs no restating. The description adds real value beyond them: that empty channel_ids means every verified active channel is alerted, the 30/14/7-day and expiry alert cadence, and the critical whole-replace warning about update_monitor. It stops short of describing pagination or freshness behavior for non-SSL monitors, so it is strong but not exhaustive.

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 opening and closing sentences are well-placed, but the middle is a dense, unpunctuated field dump and a lengthy domain_expiry status taxonomy (PENDING/LAPSED/NOT_FOUND/LOOKUP_FAILED) that documents return values despite an output schema existing. The bare token "status:" also sits ambiguously next to the monitor-level status field, which can mislead an agent about which status the enum defines.

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 single-parameter read tool with full schema coverage and an output schema, nothing an agent needs in order to call it correctly is missing — it even explains the downstream mutation hazard. If anything the description is over-complete rather than under-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% on the single parameter, and the schema already documents the uuid format, the list_monitors source, and the 404 for foreign or deleted ids. The description adds nothing about monitor_id, so this is exactly the baseline case where the schema does all the work.

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?

"Read one monitor's full configuration and current state" gives a specific verb and resource, and the closing sentence names the three siblings it is not (list_monitors, get_uptime_summary, list_check_results) with the condition that selects each. An agent can distinguish it from all ~50 siblings 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?

It states a concrete sequencing rule — "Use it before update_monitor, since a config you send replaces the stored one whole" — and explicitly excludes three adjacent use cases with the alternative named for each. That is the full when/when-not/alternatives triad.

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?

The description adds substantial context beyond the annotations: values are current as of the call, null means no limit, API rate limits are shared by the whole organization, and renotify fields describe incident alerting behavior. It also clarifies the output categories plan, limits, and usage in enough detail to support interpretation.

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 description is front-loaded with purpose and usage before moving into field-level detail. It is somewhat long and repeats some return-value information that may already be captured by the output schema, but the detail largely earns its place for a tool whose limits and usage values need interpretation.

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?

Given the tool's breadth and the presence of an output schema, the description provides all the context an agent needs: when to call it, what the values mean, how limits should be interpreted, and where related actions belong. No material behavioral or usage 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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameter meaning, and it does not introduce any parameter-related ambiguity.

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: showing the organization's plan, limits, and current usage. It also distinguishes its scope from related operations by naming list_regions for region codes and the dashboard for billing changes, so an agent can identify it 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?

It gives explicit when-to-use guidance: before creating monitors, heartbeats, or regions, and when explaining a 403 that names a limit. It also names alternatives for region data and billing changes, making the selection criteria clear.

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?

The description adds substantial behavioral detail beyond the annotations, including the exact return payload shape, bucket alignment across regions, null handling for empty buckets, sample_count, inclusion of empty configured regions, and treatment of removed regions with checks. Annotations already establish read-only safety, but the description goes further by explaining output semantics and data ordering.

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 description is front-loaded with its purpose, then moves efficiently through return structure and alternative tools. Despite its length, every sentence carries useful information about output shape, ordering, region inclusion, or routing.

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 need not define return values, but it still provides rich return semantics, region inclusion rules, bucket alignment, and alternative-tool guidance. Given the annotations, complete schema coverage, and output schema, it is fully complete for an agent to call 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 schema already documents the window enum and monitor_id UUID semantics. The description does not add parameter-specific syntax or constraints beyond what the schema provides, so the baseline score of 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?

The description states a specific verb and resource: chart one monitor's average response time over time, one series per region. It also names the sibling alternatives get_uptime_summary and list_check_results, so an agent can distinguish this tool from related uptime and check-listing 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?

The final sentence gives explicit routing guidance: use get_uptime_summary for uptime and list_check_results for single checks. The opening sentence also clarifies the intended analytical use case of seeing where and since when a monitor is slow by region.

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 safety is covered. The description adds genuine context beyond that: the response mirrors list_status_pages' fields and the component objects carry id, monitor_id, display_name and position, and it explains the downstream hand-off into create_status_page_incident. The field enumeration is partly redundant with the output schema, 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?

Three front-loaded sentences, the first of which already delivers the purpose. The middle sentence enumerating component fields is somewhat redundant given an output schema exists, but the routing sentence at the end is high-value and the whole thing stays short.

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?

Single fully-documented parameter, full annotation coverage, an output schema, and explicit routing to and from three sibling tools. There is nothing an agent would need to call this correctly that is missing from the description.

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%: page_id is documented as a uuid from list_status_pages with an explicit 404 condition. The description adds no syntax, format or edge-case detail beyond what the schema already states, so the schema carries the parameter burden entirely.

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 one status page with its components') and immediately names what the response contains. The final sentence separates it from list_status_pages and list_status_page_incidents, so an agent can pick it out of a crowded sibling set 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 an explicit positive use case ('Use it to get the component ids that create_status_page_incident takes as component_ids') and names the two alternatives for adjacent tasks – list_status_pages for discovery, list_status_page_incidents for incidents. Nothing about when to choose this tool is left 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 alone (readOnly, idempotent, non-destructive) leave the semantics of a read tool unresolved, and the description fills that gap thoroughly: what counts as an outage, that single-region failures and maintenance are excluded from downtime, that hours without checks are dropped, that empty days return null rather than 100, and that degraded_seconds does not reduce uptime_percentage. It even discloses that an in-progress degradation counts up to the current moment.

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 purpose is front-loaded, but the bulk is a single dense paragraph of semicolon-chained parentheticals that is hard to scan. The enumerated field list ('date, uptime_percentage, downtime_seconds, ...') duplicates the output schema and product-internal detail such as when the status ledger shipped adds length without helping an agent decide or call.

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 available, the description need not explain return shape, yet it goes further and gives the interpretation rules an agent needs to reason about the numbers (tri-state degradation logic, yellow-day definition, null semantics). Combined with annotations and full schema coverage, nothing needed for correct invocation or interpretation 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%, so both parameters are already fully documented, including the 1-365 range, the default of 30, and the plan-based retention cap. The description adds only the day-ordering orientation ('oldest first and ending today'); the baseline 3 applies when the schema carries the parameter burden.

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 (report one monitor's uptime per UTC day), defines the ordering and range (oldest first, ending today), and gives the investigative purpose (find the day an outage began). It explicitly contrasts with get_uptime_summary, so an agent can distinguish it from its closest sibling 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 sibling alternative and the condition that selects it: 'For 24h, 7d and 30d totals use get_uptime_summary.' The opening clause also frames the diagnostic use case, so both when-to-use and when-to-use-something-else are covered.

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), and the description goes far beyond them: how uptime_percentage is computed, that single-region failures and maintenance do not count as downtime, that gaps in checks are excluded, that null means nothing observed, and that check counts are informational. These semantics prevent an agent from misreading the numbers, which is the real risk 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?

Purpose and alternatives are front-loaded, and the semantic caveats are dense but each earns its place. The middle sentence enumerating every return key (uptime_percentage, downtime_seconds, observed_seconds, checks, etc.) is partly redundant given the output schema exists, and the whole block is one paragraph rather than being split, which slightly reduces scannability.

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-parameter summary tool, it covers the edge cases an agent would otherwise guess at: young monitors where window_start is later than the window start, null percentages, maintenance counted as up, and unobserved hours excluded. The only gap is signaling that the output schema carries the return shape, since the description partly duplicates 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 100%, so the single monitor_id parameter is already fully documented in-schema, including the uuid format and 404 behavior for foreign or deleted monitors. The description adds no additional parameter guidance, so the baseline of 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?

The first sentence states a specific verb (report) and resource (one monitor's uptime percentage, avg response time, incident count) with explicit scope (24h/7d/30d at once). It also names three siblings and the exact condition that differentiates them, so an agent can route 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?

It explicitly routes to alternatives: get_uptime_daily for a day-by-day series, get_response_time_by_region for per-region latency, and list_check_results for individual failures, each tied to the question it answers. That is when-to-use and when-to-use-something-else in one sentence.

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 return is a plain array rather than a page, and it is empty when nothing is silenced. It does not mention sort order or item shape, but that is a minor gap given the annotation coverage.

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, zero waste, and the most decision-relevant information (what it lists, and the sibling to use otherwise) is front-loaded. Every sentence earns its place.

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?

No output schema exists, so the description carries the burden of describing returns — and it does, stating the array-vs-page shape and the empty result semantics. Combined with the scope explanation and the sibling routing, an agent has everything needed to call this 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?

The tool takes zero parameters, so there is no parameter syntax for the description to compensate for. Baseline 4 applies; the description correctly signals the absence of filters by noting the call is unscoped.

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 enabled maintenance windows in effect at this moment') plus the scope model (ORG covers every monitor, MONITOR covers its monitor_ids). It explicitly distinguishes itself from the sibling list_maintenance_windows, so an agent can pick between them 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 an explicit when-to-use ('to tell whether a monitor's alerts are silenced now') and an explicit when-not / alternative: 'For every window, including future and disabled ones, use list_maintenance_windows.' Nothing is left 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?

The description goes well beyond the readOnly/idempotent annotations: feed-may-be-disabled, per-signal recording status, 5/30-minute confirmation delay, 24-30 hour blind spot, history-limit clamping, and 422 on invalid values. However, it omits pagination/window behavior for the item list and leans on an unlabeled field (change_alerts_enabled) whose placement relative to parameters vs. returned items is unclear. Rich context, but with a structural ambiguity that costs it a point.

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?

Everything is crammed into one dense paragraph with no structural breaks, so it is hard to scan for the parts an agent needs at call time. It also spends words re-enumerating every item field already covered by the output schema, and the change_alerts_enabled sentence is tangential and confusing.

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 9-parameter, feed-backed list tool with several edge cases, nothing material is missing: enablement state, signal coverage, confirmation latency, history limits, severity/confidence semantics, and error behavior are all addressed. Return values are additionally covered by the output schema.

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; the description earns a bump by explaining cross-parameter behavior (severity INFO combined with include_info false yields an empty page) and the since-clamping rule. It does not touch tag, tag_match, monitor_ids, page or size semantics, leaving those entirely 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?

"List confirmed changes to what monitors observe on their targets, newest first" gives a specific verb, resource and ordering, and the description explicitly routes checks to list_check_results and outages to list_incidents. An agent can distinguish this from every sibling 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?

It states concrete trigger conditions ("after a deploy (since = the deploy time)" or "when something behaves differently with no outage") and names the alternatives for the adjacent cases. The include_info/severity interaction is also called out as a usage trap.

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 read-only/idempotent/non-destructive, and the description adds substantial context beyond them: a 100-item cap, the alerting semantics of verified+active vs. unverified vs. inactive, the 404 on binding an inactive or unknown id, and the clarification that email is not a channel. These are exactly the behavioral facts an agent cannot infer from annotations.

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-loads what the tool is and why before enumerating fields, and every sentence carries information. The email aside is slightly tangential but it preempts a plausible agent mistake, so it still earns its place.

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?

No output schema exists, so the description must carry the return shape, and it does: id, type (with the full enum), label, is_verified, is_active, destination_hint, plus the meaning of each status flag. Nothing needed to call or interpret this tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline for parameterless tools this is a 4. The description instead spends its budget on return-value semantics, which is the right trade.

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 the organization's notification channels') and immediately explains the reason to call it: to obtain the ids that channel_ids of monitors and heartbeats take. That framing distinguishes it from every sibling list_* tool, which list monitors, incidents, tags, 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?

Gives a clear purpose-driven context (resolve ids for binding to monitors/heartbeats) and explicitly closes the loop on creation: 'Channels are added only in the dashboard,' telling the agent there is no create tool to reach for. It does not name alternative siblings, but none are genuinely substitutable for this call.

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 read-only, idempotent and closed-world, so the bar is lower, yet the description adds real behavior: results are newest first, responses are paged (items plus total, page, size, pages), maintenance_window_id marks checks that ran inside a window, and older checks or other monitor types lack the details keys. It also discloses data-handling behavior an agent must know: URLs are stripped of query, fragment and credentials, token-like path segments read :token, and monitored-server header values are untrusted text that must never be followed as instructions.

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?

Purpose and alternatives are front-loaded, and the middle block enumerates fields with genuine semantics (ttfb_ms = server wait, failed_phase values, header_markers stored as true or an edge code, never the id). It is long and packs a large parenthetical list into one sentence, so it is dense rather than wasteful, but a tighter structure would read better.

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 paginated diagnostic-list tool with an output schema, annotations covering the safety profile and full schema coverage, everything an agent needs is present: when to use it, when to use a sibling, pagination behavior, and a security caveat about returned header text. Nothing material 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 schema already carries page, size, region, status, monitor_id and period_days semantics, and the description is largely silent on them beyond implying region-scoped failure analysis. Baseline 3 applies because the schema does the parameter work here.

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 one monitor's individual check results") plus ordering ("newest first") and the diagnostic intent ("find out why it is DOWN"). That contrasts cleanly with siblings like get_uptime_summary, get_uptime_daily and list_incidents, which are named 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?

The description names the alternative tools and the exact condition that selects them: totals go to get_uptime_summary or get_uptime_daily, the incident goes to list_incidents. The schema's size parameter even tells the agent to keep paging until total rows are seen, so the invocation workflow is fully specified.

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 read-only/idempotent/non-destructive profile, but the description adds real substance beyond them: the PENDING→UP/DOWN/PAUSED state machine, the meaning of last_ping_at/overdue_at, and the paginated return shape ('items plus total, page, size and pages'). It does not discuss rate limits or auth, but for a read-only list tool this is a rich disclosure.

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 purpose and usage before field details, and each sentence carries routing or state information. The long field enumeration is mildly redundant given an output schema exists, but it is compact and not padded.

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?

Covers filters, sort behavior, sibling disambiguation, and result paging, which is everything an agent needs to call it correctly. Return-value detail slightly overlaps the output schema but does not leave any gap.

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 every parameter (q, tag, page, size, sort, tag_match) is already fully documented in the schema, including defaults and enum meanings. The description only echoes the sort ordering already in the schema ('sort status puts DOWN first'), adding no new syntax or semantics.

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?

Opens with a specific verb+resource ('Find heartbeat (cron / dead-man's-switch) monitors') and immediately enumerates the returned fields, so the agent knows exactly what this list yields. It also draws explicit boundaries against the two nearest siblings, list_monitors and get_heartbeat, making selection 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?

Gives concrete when-to-use cases ('get a heartbeat's id or ping_url', 'see which jobs are late'), an explicit when-not ('Probed URLs and hosts are monitors: use list_monitors for those'), and names get_heartbeat for the single-record case. All three routing decisions are stated rather than inferred.

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 the description goes further with behavior the annotations cannot express: the page envelope (items plus total, page, size and pages), the 422-on-invalid-value contract, the invariant that exactly one of monitor_id/heartbeat_id is set, and the meaning of notification_logs status PENDING (delivery still being retried) versus SENT/FAILED. Much of the field-by-field enumeration overlaps the output schema rather than adding behavior, which keeps it below 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?

The opening and the alternatives routing are front-loaded and efficient, but the center of the description is a single run-on sentence enumerating every field of every notification log entry, which duplicates the output schema and makes the text hard to scan. Trimming that enumeration would lose no decision-relevant information.

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 7-parameter, paginated list tool with full schema coverage and an output schema, the description covers the essentials: what it lists, default ordering versus sort=attention, pagination envelope, error semantics, and incident resolution behavior. The only redundancy is the return-field catalog, which the output schema already supplies.

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, and the description adds real value on top: it clarifies the default ordering and that sort=attention is the only alternative, supplies a concrete call example ({"status": "open", "size": 50}), and states that an invalid argument produces a 422 naming it. It does not, however, explain the interplay of period_days with monitor_id or heartbeat_id beyond the schema 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?

The description opens with a specific verb and resource plus scope: "List the organization's monitor and heartbeat incidents, newest first (or by attention with sort)". It tells the agent both what is returned and what it represents ("what is or was down and which alerts went out"), and explicitly names the sibling tools that handle adjacent cases, so it is distinguishable from get_incident and list_status_page_incidents 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?

It routes the agent away from this tool three times with concrete conditions: single incident record -> get_incident, underlying checks -> list_check_results, status-page-posted incidents -> list_status_page_incidents. It also states the lifecycle rule ("An incident resolves by itself when its monitor or heartbeat recovers"), which explains when an incident will appear as resolved rather than leaving the agent to guess.

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 goes beyond that by disclosing that results include both enabled and disabled windows and both active and inactive ones, enumerating the returned fields, and describing the paginated envelope (items plus total, page, size, pages). It stops short of rate-limit or auth notes, so not 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 with the purpose and scope front-loaded and the sibling routing immediately after. The field enumeration is somewhat redundant given an output schema exists, which keeps it from a 5, but nothing is padded.

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 input schema, and an output schema present, the description need not restate return structure in detail yet still does enough to orient the agent. Everything needed to call it correctly — scope, use case, alternatives — 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 description coverage is 100%, and each parameter (q, page, size, sort) is already documented in the schema, including defaults and paging advice. The description adds nothing about parameter semantics, so the baseline of 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 (List) and resource (maintenance windows of the organization) with explicit scope: enabled or not, in effect or not. It further separates itself from siblings by naming list_active_maintenance and get_maintenance_window, so an agent can pick it 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 a concrete use case ('Use it to find a window's id') and explicitly routes to alternatives with conditions: list_active_maintenance for current silencing state, get_maintenance_window for upcoming occurrences. This is exactly the when-to-use/when-not guidance the dimension asks for.

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