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

Goes well beyond the annotations: explains that only repeat alerts are suppressed while the recovery alert still sends, that the incident is closed by monitor recovery rather than by this call, that a write-scoped key is required, and the exact semantics of double-acknowledgement and acknowledging a resolved incident. These are non-obvious behaviors an agent could not derive from idempotentHint/destructiveHint alone.

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 effect and then layers constraints, auth, and edge-case semantics in four tight sentences. Dense but nearly every clause earns its place; only the trailing return-shape note is arguably redundant given 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?

With rich annotations, a fully documented single parameter, and an output schema (the description just points at the get_incident shape), the description covers everything an agent needs: effect, exclusions, auth scope, idempotency, and error behavior.

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 parameter's uuid origin and 404 failure mode are fully documented in the schema, so the description adds no parameter detail. Baseline 3 is appropriate 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+resource ('Mark an open incident as being handled') plus the precise effect (repeat alerts stop, recovery alert still fires). It explicitly disambiguates from the sibling that handles status page incidents, so an agent can route correctly without opening 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 ('when someone is working on the outage'), when-not ('it does not close the incident'), and names the alternative for the adjacent case ('post_status_page_update'). 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?

Goes well beyond the annotations: atomicity (nothing is created on any failure), plan-limit behavior, per-item vs batch error discrimination, the exact status codes inherited from create_monitor (403/404/422), and the monitors[N] prefix contract for locating the offending item. This is exactly the kind of operational detail 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?

Purpose and the create_monitor alternative are front-loaded, but the long middle paragraph about regex-parsing the monitors[N] prefix ('only the first such item is reported', quoting several lead-in variants) is verbose and could be tightened without losing meaning. It is information-dense rather than padded, but not as lean as it could be.

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 adds the ordering guarantee ('one list_monitors row per created monitor, in request order'), which the schema alone may not convey. Combined with atomicity, prerequisite checks, and error semantics, an agent has everything needed for a 100-item batch call.

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 field set and rules. The description adds value with a complete worked example payload (TCP monitor with ports config) and clarifies error-path semantics like monitors.3.target, but does not restate field-level constraints, keeping it modestly above the baseline.

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 ('Create 1 to 100 monitors in one call') plus the batch cardinality and all-or-nothing semantics, and explicitly distinguishes from the sibling create_monitor for the single-item case. An agent can identify the tool 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?

Gives explicit routing ('for a single monitor use create_monitor') and an actionable prerequisite ('call get_plan_usage first to check the batch fits'). The failure-and-retry guidance ('Fix the item or shrink the batch and send the whole call again') tells the agent how to recover, which is rare and genuinely useful.

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 cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real behavior beyond them: atomic all-or-nothing semantics, 403 plan-rule failures, 422 per-monitor errors with the monitors[<i>] ("<name>") format, and the caveat that returned list_monitors rows omit most settings so get_monitor is needed.

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 exclusions are front-loaded, and every sentence carries distinct information (scope, alternatives, auth, limits, error shapes, return caveat, example). It is dense and long, but no sentence is 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?

Given a 2-param tool with a nested changes object and an output schema, the description covers invocation, gating rules, partial-failure behavior, and result interpretation. An agent has everything needed to call 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 coverage is 100% and the nested changes object is fully documented in the schema, so baseline is 3. The description goes further with a concrete example payload and the semantics of channel_ids replacement/clearing and monitor_ids uniqueness/404 behavior, adding meaning beyond the raw 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?

Opens with a specific verb and resource ("Set the same interval, timeout, regions...") and bounds scope (up to 100 monitors, all-or-nothing). Explicitly names the siblings it is not (update_monitor, bulk_update_monitor_tags), so an agent can route correctly without opening 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?

States when-not to use it: not for config or name (use update_monitor) and not for tags (use bulk_update_monitor_tags). Also names the prerequisite (a key with write scope), which is the condition that gates invocation.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses real behavior: all-or-nothing atomicity, write-scope key requirement, the exact 422 failure conditions (shared tag, >10 tags, duplicate id), tag normalization on write, and the return field monitors_updated. This is far more than the annotations provide.

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 dense but front-loaded with the core contract, then alternatives, then requirements, then an example. Every sentence carries usable information, though the packed constraint list and example make it longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema plus rich annotations already present, the description still covers scope, prerequisites, failure modes, normalization rules and return value, leaving nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds constraints the schema omits: at least one of add/remove is required and the two must not share a tag (422), plus a concrete example payload. It adds meaningful semantics beyond the documented fields.

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 pair and resource ('Add and/or remove tags across up to 300 monitors in one call'), states the all-or-nothing scope, and names exactly which siblings handle the adjacent cases (update_monitor, rename_tag, delete_tag). An agent can distinguish this from every bulk_* and tag 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 gives explicit routing: 'Use it to retag a fleet; to replace one monitor's whole tag list use update_monitor, to rename or drop a tag everywhere (heartbeats too) use rename_tag or delete_tag.' When-to-use and when-to-use-something-else are both spelled out with the selecting condition.

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 declare the safety profile, but the description adds substantial non-structured context: it returns the monitor record rather than a check result, the 30-second and paused-monitor no-op semantics, the write scope requirement, and a per-address rate limit with 429 behavior and a pacing recommendation. This is exactly the operational detail an agent needs before calling.

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 effect, then layered: return-value caveat, sibling routing, auth requirement, no-op conditions, rate limit. Every sentence carries actionable information with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the gaps an output schema cannot: latency of the result, silent no-op conditions, auth scope, and rate limiting with pacing guidance. The explicit note that the return is the monitor record, not a check result, is the key clarification for correct agent follow-up.

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 parameter is fully documented there (uuid source from list_monitors, 404 conditions). The description adds no additional parameter-level syntax or format meaning, 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 ('Queue one existing monitor to run on the scheduler's next tick instead of waiting out its interval') and explicitly distinguishes itself from check_target and resume_monitor. The purpose and scope are unambiguous 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?

Gives an explicit use case ('to confirm a fix'), names two sibling alternatives with the condition that selects each (check_target for no monitor yet, resume_monitor for a paused monitor), and flags the silent no-op cases that make the call pointless. 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 safety (readOnly, idempotent, non-destructive), and the description still adds real operational context: the write-scope auth requirement, per-address rate limiting with a 429/retry_after contract, and the semantic that 'unknown' means no definite answer rather than a failure. That last point is behavior an agent cannot infer from schema or 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?

Well front-loaded: purpose, then outputs, then the confusing 'unknown' semantics, then usage, then auth/rate limits, then the example. Slightly dinged because enumerating the returned fields (region, response_time_ms, status_code, error, failure_kind) duplicates what the 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 probe tool with an output schema in place, the description covers everything an agent needs: auth scope, rate-limit failure mode, the meaning of each status value, and how this call relates to create_monitor and check_now. No gaps remain for correct invocation.

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 enum values and config sub-fields are thoroughly documented in the schema itself, so the baseline is 3. The description only adds a single worked example ({"type": "HTTP", "target": "https://api.example.com/health"}) and a note that TCP/DNS need config; it does not meaningfully extend parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource ('Run one real check of a target') with an explicit scope qualifier ('without creating anything'), and it enumerates the result fields. It also distinguishes itself from both siblings it could be confused with: create_monitor and check_now.

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'), an explicit non-blocking caveat ('a down result does not stop you creating the monitor'), and the alternative for the other case ('For a monitor that already exists use check_now'). 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 only declare the mutation safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantial behavior: the ping_url contract (/start restarts the clock, /fail goes DOWN immediately), the never-late-before-first-ping rule, the period_seconds + grace_seconds alert timing, the write-scope requirement, the plan cap returning 403, and invalid args returning 422. This is exactly the 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?

It is a single dense paragraph, but it is front-loaded with the purpose and then the ping_url contract, error behavior, and example in a logical order. Every sentence carries distinct information, though the run-on density slightly taxes readability compared to a cleaner separation.

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 6-parameter mutation tool with an output schema, the description covers the gaps an agent actually needs: purpose, alternative tool, ping contract, auth scope, plan limits, and error codes. Return values are summarized ('returns the heartbeat, with ping_url') without redundantly re-specifying 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 description coverage is 100%, so the baseline is 3. The description adds value on top: a worked example tying name/period_seconds/grace_seconds together and the timing rule (alert fires period_seconds + grace_seconds after the last ping), which explains how the two numeric params interact. It does not add detail for tags, channel_ids, or notification_cooldown_seconds beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Create) and resource (a heartbeat), then immediately defines what a heartbeat is: 'Fettle alerts when a scheduled job stops calling its ping_url.' It explicitly distinguishes itself from the sibling create_monitor ('to probe a URL, host or port from outside use create_monitor'), so 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?

Gives concrete when-to-use cases (cron jobs, backups, workers that report in) and an explicit alternative with its condition (use create_monitor to probe a URL/host/port from outside). It also routes to get_plan_usage for quota and names the write scope requirement. Nothing about selection 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 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?

Annotations already declare this is a non-read-only, non-destructive create, and the description adds substantial context beyond them: write scope required, plan limits (count, min interval, fast-monitor cap, regions per monitor) failing as a 403 that names the limit, paused monitors still counting, and 422 behavior for invalid arguments.

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?

Content is front-loaded with purpose, then alternatives, then error/limit semantics, then an example. It is dense but every clause carries useful information; the single-paragraph format is slightly heavy though not wasteful.

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 12-parameter create tool with an output schema, the description covers purpose, routing to siblings, required scope, limit/quota failure modes, the get_monitor return shape, and a valid example. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds value by including a full worked example that shows how name, type, target, interval_seconds, timeout_seconds, regions, config and tags combine in a valid call. It does not restate individual field semantics, which the schema handles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Create one monitor'), its scope (checks a URL, host or port on a schedule from one or more regions) and its return shape. It clearly distinguishes itself from bulk_create_monitors and create_heartbeat, 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?

It names the alternatives and the condition selecting each: check_target first to catch typos/unreachable hosts, bulk_create_monitors for several, create_heartbeat for report-in jobs, and get_plan_usage before hitting limits. When-to-use routing is fully explicit.

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 annotations: discloses that the incident is public, that it emails confirmed subscribers, the exact divergence between RESOLVED (records a closed incident/postmortem, emails nobody) and any other status (emails everyone at once), and the required write-scope key. The annotations only say it is a non-idempotent, non-destructive write; the description supplies the real blast radius.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: purpose, then notification behavior, then the sibling escape hatch, then auth, then an example. Every sentence carries information, though the example is somewhat redundant given a 100%-covered 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 public, notification-triggering mutation with an output schema already present, the description covers purpose, routing, side effects and auth. Nothing material an agent needs to invoke it safely 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 the baseline is 3, and the description earns an upgrade by explaining the subscriber-notification semantics of the status enum and by showing a concrete call example with page_id, title and body. Component_ids and the length limits are left to the schema, which already documents them.

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, which adds to an existing incident. An agent can route between these two 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 when (tell visitors about an outage), the when-not (adding to an existing incident → post_status_page_update), and a procedural precondition ('confirm the wording with the user before calling'). 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 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?

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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds valuable context beyond annotations: exactly one of monitor_id or heartbeat_id is set, notification_logs fields with event/status/error semantics, and destination formats. Missing only auth or rate-limit details, which are minor for a read tool.

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 core purpose. The long enumeration of return fields is somewhat redundant with the existing output schema, making the description longer than strictly necessary. Still well-structured and every sentence serves a purpose for an agent.

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 an output schema and rich annotations, the description covers purpose, usage, alternatives, return content, and destination formats. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single required parameter is fully documented in the schema (uuid from list_incidents, 404 for wrong organization). The description adds no parameter-specific syntax or constraints beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'Read' and resource 'incident' with scope 'in full, with every alert sent for it'. Explicitly distinguishes from siblings by naming list_incidents and acknowledge_incident, so an agent can tell it apart without opening 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?

Explicitly states the use case: 'Use it to tell who acknowledged an incident and whether its alerts were delivered.' Names alternatives: list_incidents to find incidents and acknowledge_incident to stop reminders. Provides both when-to-use and when-to-use-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 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 the tool as read-only, idempotent, and non-destructive, but the description adds important operational context beyond those hints. It explains the whole-config replacement behavior of update_monitor, clarifies that an empty channel_ids means all verified active channels are alerted, and notes SSL-specific fields.

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 the core purpose, followed by usage guidance and exclusions in a logical order. The long field list is relevant to understanding what a full configuration includes, though it is somewhat redundant because an output schema exists.

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 simplicity, the detailed schema, annotations, and presence of an output schema, the description is complete enough for correct invocation. It covers purpose, pre-update usage, field semantics, and sibling routing without needing to explain return formatting.

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 monitor_id parameter is already documented as a UUID from list_monitors with 404 semantics for unknown or deleted monitors. The description does not add meaning beyond the schema for this single parameter, 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?

The description uses a specific verb and resource: read one monitor's full configuration and current state. It enumerates the key fields returned and explicitly distinguishes the tool from list_monitors, get_uptime_summary, and list_check_results, so an agent can identify its role without ambiguity.

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 usage condition: call it before update_monitor because update configs replace the stored configuration wholesale. It also names when not to use it and routes the agent to the correct alternatives for listing, uptime, and failure investigation.

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 behavior is covered. The description adds value beyond that by disclosing the shape of the returned components (id, monitor_id, display_name, position) and the downstream consumer of the ids, which annotations cannot 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-loaded with the core action, then the routing guidance, with no filler sentences. The middle sentence describing component fields is slightly dense but earns its place by telling the agent what it will get back for the component_ids use case.

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 return values need not be re-explained, yet the description still summarizes component fields relevant to the chained call. Combined with a fully documented parameter and read-only annotations, nothing an agent needs to invoke 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 the single parameter's description already states the UUID source (list_status_pages) and the 404 for foreign ids. The description adds essentially no syntax or format detail beyond the schema, so the baseline 3 for a fully documented single parameter 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 and resource ('Read one status page with its components') and immediately differentiates it from the closely related list_status_pages and list_status_page_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?

Explicitly names the alternative for discovery ('To find a page use list_status_pages'), the alternative for the related sub-resource ('for the incidents posted on it use list_status_page_incidents'), and states a concrete downstream use case (feeding component_ids into create_status_page_incident). When-to-use is fully spelled out.

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 profile, and the description adds real behavioral semantics beyond them: degraded checks count as up, days with only maintenance checks yield null uptime_percentage rather than 100, ordering is oldest-first, and results are capped at the plan's history retention. These are exactly the non-obvious traits an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: purpose and ordering first, then field semantics and the null-edge case, then the sibling hand-off. Dense but every clause carries 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?

For a 2-param read tool with annotations and an output schema, the description covers purpose, ordering, edge cases, retention behavior, and the alternative tool. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are documented, giving a baseline of 3. The description adds value beyond the schema by reinforcing the retention cap and noting that fewer days than requested can be returned, clarifying the effective behavior of 'days'.

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 for each UTC day') with explicit scope (oldest first, ending today). It distinguishes itself from get_uptime_summary by naming that sibling as the alternative for aggregate totals.

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 ('to find the day an outage or degradation began') and explicitly routes the agent to get_uptime_summary for 24h/7d/30d totals. Both when-to-use and the alternative are spelled out.

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, but the description adds real behavioral semantics beyond them: DEGRADED checks count as up, uptime_percentage is null when there were no checks, and incident_count/avg_response_time_ms are surfaced. It omits anything about permissions or rate limits, but the key interpretive caveats are disclosed.

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 is front-loaded, followed by routing and then the return shape; every sentence carries information. The long enumeration of return fields is somewhat heavy given an output schema already exists, which is the only reason this isn't a 5.

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 annotations and an output schema present, the description is more than adequate; it even spells out the window keys and metric names. The return-value detail is partly redundant with the output schema, but nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter and schema coverage is 100%, so the schema already documents monitor_id fully, including the uuid format and the 404 behavior. The description adds no further parameter 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 (uptime percentage, average response time, incident count for one monitor) and scopes it precisely to three fixed windows (24h, 7d, 30d). It also names the sibling tools it is not, so an agent can distinguish it from get_uptime_daily and get_response_time_by_region 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 routes the agent: 'For a day-by-day series use get_uptime_daily; for response time per region use get_response_time_by_region; for the individual failures use list_check_results.' This is textbook when-to-use/when-not guidance with named 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 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?

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds ordering (newest first), the semantics of maintenance_window_id (set when the check ran inside a window), and the paging contract. It does not discuss result retention limits or any rate/volume caveats, so it falls short of the richest disclosure but clearly adds context beyond 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 diagnostic purpose, then the returned fields, then routing to alternatives, then the pagination contract — a logical order with near-zero filler. The 'Returns a page: items plus total, page, size and pages' sentence is largely redundant given an output schema exists, which keeps it from a 5.

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 six-parameter paginated read tool with full schema coverage, an output schema and read-only annotations, the description supplies everything an agent needs: purpose, the diagnostic use case, sibling routing, field-level meaning for maintenance_window_id, and how to page. No material gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so page, size, region, status, monitor_id and period_days are already documented, including enum values and the 404 case. The description adds no filter syntax or semantics beyond the field names it enumerates, 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 (list one monitor's individual check results) plus scope (newest first) and diagnostic intent ('to find out why it is DOWN'). An agent can distinguish it from list_monitors, get_uptime_summary and list_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?

Explicitly frames the when ('to find out why it is DOWN: which regions fail and with what status code or error') and names two alternatives with their selecting conditions: get_uptime_summary/get_uptime_daily for totals, list_incidents for the incident they opened. 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 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 cover safety (readOnlyHint, idempotentHint, non-destructive, closed-world), yet the description adds substantial context: newest-first ordering, the self-resolving lifecycle, the 422 error shape on invalid values, and the notification delivery state machine (PENDING while a webhook/Slack/Discord delivery is retried, then SENT or FAILED with the last error). This goes well beyond the structured fields.

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, but the body is one dense run-on paragraph enumerating return fields (id, started_at, resolved_at, cause, notification_logs, channel_type, destination, event, sent_at, status, error) that an output schema already carries. Much of that inventory does not earn its place against a structured output contract.

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 filtered list with 6 optional parameters, the description covers scope, ordering, alternatives, resolution semantics, pagination and error behavior. 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 description coverage is 100%, so the baseline is 3, but the description adds a worked example ({'status': 'open', 'size': 50}) showing a valid filter combination and reinforces pagination intent. It does not add per-parameter syntax beyond the schema, so it does not reach 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?

States a specific verb and resource ('List the organization's monitor and heartbeat incidents, newest first') and immediately bounds the scope to what is or was down. It explicitly distinguishes itself from get_incident, list_check_results and list_status_page_incidents, so an agent can route 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?

Names the three alternative tools and the condition selecting each ('For one incident's full record use get_incident; for the checks behind it use list_check_results; incidents posted on a status page are list_status_page_incidents'). It also explains the resolution lifecycle, telling the agent an incident clears itself on monitor/heartbeat recovery.

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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: the exact row fields returned, the pagination model (items plus total, page, size, pages), and the 422 error behavior naming the bad argument. It stops short of describing rate limits or ordering guarantees beyond sort, 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?

Front-loaded with purpose, then usage, then return shape, error behavior, and an example — each sentence carries information. The bare field-list enumeration is slightly dense but earns its place given there is no 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?

With no output schema, the description compensates by spelling out the returned row fields and the page envelope, and even notes the error shape. For an 8-parameter read tool with rich annotations, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline is 3. The description still adds cross-parameter meaning the schema lacks: a worked example combining status and size, and the intent mapping (status ['DOWN','DEGRADED'] for outages, type ['SSL'] + sort ssl_expiry for certificates), which helps agents compose parameters correctly.

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 ('Find monitors in the organization') plus the filterable dimensions, and explicitly contrasts itself with siblings get_monitor and list_heartbeats. An agent can select this over get_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?

It gives concrete when-to-use cases ('use it first to get a monitor's id', 'answer what is broken now', 'which certificates expire first') and names the alternatives plus the condition that selects them (full settings vs. heartbeats). Exclusions are explicit.

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, so the safety profile is covered. The description adds real context by noting the organization may use only some regions, steering the agent to get_plan_usage for the actual allowed set. It does not add further behavioral traits like 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 tight sentences, front-loaded with purpose. The enumerated return fields are somewhat redundant against the output schema, though the note on 'code' justifies inclusion.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain returns, yet it covers purpose, alternatives, and the allowed-region caveat. 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?

Zero parameters, so the baseline is 4. The description still earns its keep by explaining that the returned 'code' field is what a 'regions' argument elsewhere consumes, linking this tool's output to other tools' inputs.

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 every check region of the platform') plus the intent ('to show the user where checks can run'). It also disambiguates from two siblings, 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?

Explicitly routes the agent away: use limits.allowed_regions/max_regions from get_plan_usage to choose a monitor's regions, and get_response_time_by_region for per-region timings. Both the when-to-use and clear alternatives are named.

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, so the bar is lower. The description adds ordering behavior ('newest first', updates 'oldest first') and field semantics such as is_auto meaning Fettle-opened from a monitor and notified_at being null if never emailed. It does not discuss filtering or rate limits, but the added behavioral context is substantive.

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 verb and scope, then the returned fields, then the sibling routing. It is dense and slightly long, but nearly every clause conveys return shape or routing information rather than 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?

Combined with a 100%-covered schema, full annotations, and an output schema, the description supplies ordering, field semantics, pagination behavior, and sibling routing. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters (page, size, page_id) are fully documented in the schema, including defaults and the 404 case for page_id. The description adds nothing beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the incidents shown on one status page'), scopes it to a single page, and explicitly distinguishes itself from the sibling list_incidents ('Monitor outages behind the scenes are list_incidents'). An agent can route 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?

Gives both the when-to-use rationale ('Use it to find the incident_id for post_status_page_update') and the when-not/alternative ('Monitor outages behind the scenes are list_incidents'). This is explicit routing guidance, not 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 a safe, idempotent, read-only operation, so the description only needs to add context beyond that. It usefully adds that pages are public, lists returned fields, and explains the paginated result shape, though some field detail overlaps with the output schema.

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 and efficient, with the primary purpose and alternative tool stated early. The returned-field enumeration is somewhat detailed but still relevant to the task.

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 an output schema and full annotation coverage, the description supplies enough context for an agent to call the tool correctly. It covers purpose, alternative, pagination behavior, and creation/edit constraints.

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 parameters page, size, and sort are already documented in the schema. The description does not add syntax or selection guidance beyond 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 gives a specific verb and resource: listing the organization's public status pages. It also distinguishes this list operation from the sibling get_status_page for a single page.

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 states the main use case: finding a page's id before posting an incident. It also names get_status_page as the alternative for one page and clarifies that creation and editing happen only in the dashboard.

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 read-only/idempotent/non-destructive, so the bar is lower, yet the description adds real behavior: result ordering (most-used first), the returned counts, and critically that there is no pagination ('Returns every tag at once, not a page'). It stops short of describing anything about auth scope or what happens with very large tag sets, 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?

Four tight sentences, each doing distinct work: purpose, pre-tagging guidance, disambiguation from filtering tools, and pagination behavior. The most decision-relevant information (what it is, when to call it) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the description still surfaces the salient ones (counts, ordering, no paging). Combined with full schema coverage and read-only annotations, an agent has everything needed to call this correctly and to avoid misusing it as a filter.

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 enum values for 'kind' are fully documented in the schema, so the baseline is 3. The description adds no additional semantics for 'kind' (e.g., which count corresponds to which kind), instead spending its parameter-adjacent text on sibling routing.

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 tags used in the organization') and goes further by specifying ordering ('most-used first') and the per-item payload ('monitor_count and heartbeat_count'). It also distinguishes itself from siblings like list_monitors/list_heartbeats by clarifying it is not a filter.

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 ('Call it before tagging anything so you reuse an existing name') and explicit when-not ('Not a filter'), with the correct alternative named ('pass tag to list_monitors or list_heartbeats'). Nothing about tool selection 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?

Goes well beyond the annotations: pings are accepted but ignored, an open incident is closed without an alert, a write-scoped key is required, and pausing an already-paused heartbeat is a no-op. This is exactly the operational context the annotations (idempotentHint, destructiveHint) cannot 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?

Four tightly packed sentences, front-loaded with the effect of pausing, then usage, then alternatives and prerequisites. No filler sentences; even the trailing 'Returns the heartbeat' is one short clause.

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?

Mutation tool with an output schema and full annotation coverage, and the description still covers side effects, auth scope, idempotency, and sibling routing. 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 the single heartbeat_id parameter is already fully documented in the schema (uuid source, 404 semantics). The description adds no parameter-level detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Pause one heartbeat') and immediately qualifies scope by naming the sibling alternatives resume_heartbeat and delete_heartbeat. An agent can distinguish this from resume/delete without opening 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?

Explicit when-to-use condition ('when the job is stopped on purpose, such as a runner taken out of service'), plus explicit when-not/alternatives: resume_heartbeat undoes it, delete_heartbeat removes it permanently, and maintenance windows do not cover heartbeats.

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 annotations: it discloses that an open incident closes without a recovery alert, that write scope is required, that pausing a paused monitor is a no-op (consistent with idempotentHint), and what shape the result takes. These are exactly the mutation side effects an agent cannot infer from readOnlyHint/destructiveHint alone.

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 action and its state change are front-loaded, followed tightly by routing rules and constraints. Every sentence carries distinct, actionable information 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?

Annotations cover the safety/idempotency profile, the output schema covers the return value, and the description covers semantics, prerequisites, and alternatives. 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?

Schema coverage is 100% and the single monitor_id parameter is fully documented in the schema (uuid source plus 404 behavior), so the baseline is 3. The description adds nothing further about the parameter itself, leaving the schema to do 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?

States a specific verb and resource ('stop checking one monitor without deleting it') plus the resulting state (PAUSED) and the side effect on incidents. It explicitly distinguishes itself from create_maintenance_window, bulk_pause_monitors, and resume_monitor 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?

Gives an explicit when-to-use ('monitor off for an open-ended time') and multiple when-not-to-use conditions with named alternatives: planned deploy/reboot -> create_maintenance_window, many monitors -> bulk_pause_monitors, restart checks -> resume_monitor. Routing is fully determined.

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