Uptimepage

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

Adds behavioral context beyond annotations: it mentions confirmation prompts and token scope execution ('Asks for confirmation where the client can show a prompt; otherwise runs on the token's scope') and explicitly states it is not read-only, aligning with readOnlyHint=false. No contradiction with annotations.

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

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

The description is compact yet complete, with each sentence serving a purpose: state the action, scope, alternatives, execution behavior, and read-only status. It is front-loaded with the primary purpose and avoids redundancy.

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 presence of an output schema and annotations, the description covers all necessary context: purpose, usage boundaries, mutation behavior, and authorization. Nothing critical is missing for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, and the schema already describes both id and note clearly. The description does not add parameter-specific meaning; it only reinforces that the note is internal via 'Internal/operational only' but doesn't elaborate on the parameters themselves.

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 clearly states the action: 'Acknowledge an incident: take ownership and halt escalation.' It identifies the specific resource and distinguishes it from sibling tools by explicitly saying it is internal/operational only and does not post to the public status page, pointing to post_incident_update for customer-facing updates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-not-to-use guidance ('does NOT post anything to the public status page') and names the alternative tool ('Use post_incident_update for customer-facing updates'). Also clarifies it's not read-only, helping agents decide between mutation and read tools.

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 meaningfully beyond the annotations: discloses that already-present monitors are reported rather than duplicated, that group membership is live-synced (join/leave propagates to the page), that members beyond the plan's public component limit silently stay off, and that detail_link_enabled publishes the operator-facing name and address. That last point is a genuine privacy/leak warning an agent would not get from the schema. The trailing 'Not read-only' merely restates readOnlyHint=false, but it is a minor redundancy rather than a contradiction.

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 in the first clause and every subsequent sentence carries operational content; no filler. Some sentences are long and run-on ('groups adds monitor groups as live sections: a heading with...'), which slightly hurts scanability, and 'Not read-only' is dead weight given the annotations.

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

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

Output schema exists, so return values need not be explained, and the description covers the input semantics plus the non-obvious effects (dedup, live group sync, plan-limit truncation, detail-link exposure). What is missing is any mention of ordering interactions between components and groups in the final page layout, and explicit guidance on partial failure when only some monitors are beyond the limit.

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 baseline is 3; the description earns extra credit by supplying intent the schema lacks — why public_name matters (monitor name is operator-facing), what public_group does operationally, and the non-obvious consequence of detail_link_enabled (real name/address exposed, not public_name). It does not cover slug, sort_order, or the 50/80/200-char limits, which the schema already handles.

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

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

Opens with a specific verb+resource+scope: 'Add monitors to a status page as public components,' and immediately distinguishes the two payload shapes (components vs. groups as live sections). An agent can tell this is a create/attach operation on a status page rather than a page create (create_status_page) or a component edit (update_status_page_component).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the semantics (use when attaching monitors or groups to an existing page, with slug coming from list_status_pages), and the duplicate-handling sentence hints at safe re-invocation. However, it never explicitly contrasts with update_status_page_component or says when to prefer adding a group over individual components beyond a one-line behavioral note. Guidance exists but must be 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 cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), yet the description still adds real behavior: the window leaves status pages, stops holding paging, remains listed under past, subscribers are not notified of cancellation, and confirmation is requested when the client supports a prompt. That is materially more than the annotations convey.

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

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

Front-loads the action and its precondition, then routes to the alternative and covers side effects efficiently. The closing 'Not read-only' restates what the annotations already declare, which is the one sentence that doesn't fully earn 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?

With an output schema present, return values need no explanation, and the description covers the mutation's side effects, subscriber impact, confirmation behavior, and scope fallback. 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?

Only one parameter and schema coverage is 100%, so the schema already documents 'id' and its provenance from list_maintenance. The description adds no format, syntax, or ambiguity resolution beyond that, which matches the baseline for fully-covered schemas.

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 ('Cancel a maintenance window') plus a decisive precondition ('that has not ended'), and explicitly distinguishes its effect from the sibling update_maintenance. An agent can separate it from update_maintenance without reading 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 an explicit alternative and the condition that selects it: 'To stop a running window early and keep it as completed work, use update_maintenance with end_now instead.' This is a direct when-to-use-this vs when-to-use-that routing statement.

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 explains the status-page display during the window, that alerts are suppressed by default but checks keep running and incidents still open, that an incident still open at the end pages then, and that subscribers are notified on schedule and on end. It also states the tool is not read-only, matching readOnlyHint=false, and gives the RFC 3339 and 30-day constraints.

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 the sibling routing, and every sentence carries information about behavior. The one weak spot is the clause 'Shows the window, its monitors, whether paging is held and where it is announced, where the client can show a prompt; otherwise runs on the token's scope', which is compressed to the point of being hard to parse.

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

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

An output schema exists, so return values need no explanation, and the description covers the full lifecycle of a maintenance window plus validation limits. An agent has everything needed to invoke this six-parameter mutation 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, and the description still adds real meaning: the consequence of suppress_alerts ('unless suppress_alerts is false nobody is paged') and the RFC 3339 / 30-day rules for the time parameters. It does not add much for title, description or monitor_ids beyond what the schema already says.

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

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

States a specific verb and resource ('Schedule a maintenance window') plus the scope ('on some monitors'), and explicitly distinguishes itself from the sibling pause_monitor. An agent can pick the right tool 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?

'Prefer this over pause_monitor for planned work' names the alternative and the condition that selects it, which is the main routing ambiguity among the siblings. The rest of the description makes the consequences of choosing it clear enough to confirm the decision.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) are consistent with the closing "Not read-only." The description adds substantial behavior beyond them: a trial check runs before anything is saved, a prompt gates creation where the client supports it, and credentials are refused if pasted. Useful operational context rather than restated safety 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?

Front-loads purpose then layers behavioral constraints; every sentence carries a distinct rule (trial check, approval gate, alerts, regions, credentials). It is dense and long for a single paragraph, 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 12-parameter tool, an output schema that already carries return shape, and annotations covering safety, the description supplies the missing operational rules (approval flow, region defaults and caps, credential-by-reference, alert binding) that 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 already 92%, so the baseline is 3; the description still adds real meaning, e.g. that omitted regions fall back to the operator's default set, that an oversized region set is refused rather than trimmed, and the credential-reference syntax for headers/body. Some content (credential rules, header format) duplicates the schema text, which keeps it from a 5.

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

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

States a specific verb ("Create") and resource ("monitor") and enumerates the eight supported check kinds (http, tcp, ping, dns, tls_cert, domain_expiry, heartbeat, manual). This lets an agent distinguish it immediately from sibling create_monitors and from update_monitor without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when/when-not and alternatives: manual monitors use set_monitor_state afterwards, regions should be left unset unless the user named locations, browser flows must be added in the app rather than here, and channels come from list_notification_channels. It names the exact sibling tools that complete the workflow.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds behavior an agent cannot get from those: the batch is pre-flight probed before saving, all results are surfaced together, and partial failure is non-fatal (a failing item is reported while 'the rest are still created'). That partial-success contract is the single most important thing to know before calling a batch-creation 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?

The purpose and the when-to-use rule are front-loaded in the first and fourth sentences, which is the right ordering. Six sentences is slightly more than needed, and the trailing 'Not read-only' merely restates readOnlyHint=false rather than earning 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?

An output schema exists, so return shape need not be described. Combined with the schema, the description covers what an agent needs: batch semantics, the pre-save probe, the confirmation prompt, and the partial-failure outcome. Nothing material is left unstated.

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 $defs already document every per-monitor field in depth, so the baseline is 3. The description adds a useful pointer beyond the schema: 'Same per-monitor fields and same limits as create_monitor' tells the agent to mirror a sibling tool's accepted fields and limits rather than infer 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?

The opening sentence states a specific verb and resource with scope: 'Create several monitors at once.' It goes further and names the sibling it replaces, explicitly contrasting with 'repeated create_monitor calls', so an agent can distinguish it 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 selection rule: 'Prefer this over repeated create_monitor calls whenever the user names more than one thing to watch.' The alternative (create_monitor) is named and the condition that selects it is stated, 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?

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description reinforces 'Not read-only' while adding genuine context beyond them: the unpublished-by-default state, the platform-wide first-come slug semantics with link-breakage warning, the private-access sign-in flow with email codes (Team plan), and the password caveat that the secret never passes through this call.

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?

Five dense sentences, front-loaded with purpose and default state before drilling into slug and access semantics. Every sentence carries information relevant to correct invocation, though the access/plan parenthetical is slightly heavy for a description of this length.

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 no explanation, and the description covers the remaining gaps: the default unpublished state, slug permanence and uniqueness, privacy semantics, and the follow-up tool for adding monitors. 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%, so the baseline is 3; the description nonetheless adds meaning the schema does not carry, such as the platform-wide slug uniqueness and the instruction to confirm it with the user, plus the practical effect of enabling the page and of setting access.protected=true. This is additive rather than redundant.

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 a status page') and immediately distinguishes its scope from siblings by naming the companion tool add_status_page_components for monitor attachment. An agent can tell this apart from update_status_page or create_monitor 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 clear operating context: pages are created dark, add components separately, and confirm the slug with the user rather than inventing one. It stops short of explicitly naming when to prefer update_status_page or the conditions under which creation should be refused (e.g., slug collision handling), but the when-to guidance is strong.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces it with 'Read-only.' The description adds behavioral context by specifying the time window options (1h/24h/7d/30d) and the type of data returned (every declared step, failure step, page). This adds value beyond the schema and annotation without contradicting them. No hidden side effects are mentioned, but the bar is met given the annotation.

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 two sentences, with the first packing all essential facts about the resource, data, and scope, and the second giving a practical use case. There is no redundant or filler language; every phrase contributes.

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 detail return formats. It explains what the tool returns conceptually, the windows, the monitor type, and a motivating use case. For a two-parameter read-only tool, this is complete.

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

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

The input schema already provides descriptions for both parameters with 100% coverage. The description only restates the window choices and confirms the id must be a flow monitor (already in the schema). No additional parameter semantics are added, so the baseline of 3 applies.

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

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

The description opens with a specific noun phrase ('A browser flow monitor's recent runs') and details the contents (steps, outcomes, durations, failure step, page). It clearly specifies the resource (flow monitor runs) and the action (get). It also distinguishes from siblings by focusing on recent runs with failure details, and even offers a concrete use case ('why a login check failed').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear context for when to use the tool: 'Use this to answer why a login check failed.' It implies this is the diagnostic tool for inspecting individual runs and step outcomes. However, it does not name alternative tools or specify exclusions, so it falls short of full alternative guidance.

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

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

In addition to the read-only annotation, the description discloses the exact output semantics: per-step earliest/latest mean duration, ratio, and pass/fail run counts. It also notes the window values (1h/24h/7d/30d), making the tool's behavior more transparent beyond the annotation.

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 two sentences, front-loading the core purpose and then the use case. Though the first sentence is dense, every clause adds value and there is no filler or redundancy.

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-parameter read-only tool with an output schema, the description is quite complete: it explains the kind of analysis, the exact metrics returned, and the intended diagnostic use. It does not cover edge cases like empty data, but the output schema likely addresses return structure, and the tool is simple enough that this is sufficient.

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?

Input schema covers 100% of parameters, with descriptions for both 'id' and 'window'. The description largely repeats the window values and adds no new parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it reports the duration of each step in a browser flow monitor over a window, including trend metrics like earliest/latest mean, ratio, and pass/fail counts. This explicitly focuses on 'browser flow monitor' steps, distinguishing it from general monitor or run-level 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 description gives an explicit use case: 'Use this to spot a step drifting toward failure while the monitor still reports up.' This clearly indicates when to employ the tool, though it does not explicitly name alternative tools or conditions when not to use it.

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

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

Annotations already carry readOnlyHint=true, so 'Read-only' merely restates structured data. What the description does add is the shape of the payload, including the non-obvious edge case that incidents without a monitor resolve to status pages. It says nothing about behavior on a missing or invalid id, which matters for a lookup 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?

A single front-loaded sentence names the resource first and then enumerates contents; every clause is informative. The field list is dense but does not sprawl, and the trailing 'Read-only' is the only redundant element.

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

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

With an output schema, read-only annotations, and a fully documented single parameter, the description only needs to frame the scope and it does. The remaining gap is routing guidance relative to get_incident_metrics and the incident mutation siblings.

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 id property already documents its source (list_incidents or get_org_health). The description contributes no additional 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?

The description names a specific resource and scope ('One incident') plus the concrete contents returned: affected monitor, severity, open/resolved times, error sample, operator-update timeline, status pages. 'One incident' immediately separates it from the sibling list_incidents, so an agent can pick between the single-item and list variants without reading 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?

Usage is only implied: single-item retrieval is signposted by 'One incident', and the id parameter description points at list_incidents/get_org_health as sources. There is no explicit statement of when to reach for this instead of get_incident_metrics or list_incidents, and no prerequisites or error conditions are given.

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?

'Read-only' merely restates readOnlyHint=true, so no credit there. The description does add the aggregation semantics (trailing window, default 30 days, time units in seconds) which is genuine context, but it says nothing about whether figures are org-wide, how freshness/latency behaves, or cost of the call.

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

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

A single dense sentence with the window scope front-loaded and the metric list following. Efficient, though the metric enumeration overlaps with what the output schema already defines.

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

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

An output schema exists, so the description need not explain return values, and it still covers read-only status plus window semantics. The only real gap is the aggregation scope (organization-wide vs monitor-specific) and any relationship to get_org_health.

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 documents window_days with range 1..=365 and the 30-day default. The description's 'trailing window (default 30 days)' adds no syntax or semantic detail beyond that, so baseline 3 applies.

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

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

States a specific verb+resource (incident metrics) and enumerates exactly what is aggregated: MTTA/MTTR in seconds, totals, severity/state breakdowns, auto-vs-human resolution, noisiest monitors. That content signature cleanly separates it from list_incidents, get_incident and get_org_health without needing to name them.

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 'trailing window (default 30 days)' phrasing implies the reporting context, but there is no explicit when-to-use, when-not-to-use, or routing toward list_incidents or get_org_health for other needs. Usage is inferable rather than stated.

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

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

The trailing 'Read-only' merely restates the readOnlyHint annotation and earns no credit. The field enumeration adds some value about what comes back, but with an output schema present and annotations already covering the safety profile, nothing new is disclosed about auth needs, error behavior, or permissions.

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

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

Front-loaded and essentially one sentence plus a two-word tag. The closing 'Read-only' is redundant against readOnlyHint=true, a minor bit of waste, but otherwise every clause is informative.

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

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

For a one-parameter read tool with an output schema and a readOnlyHint annotation, the description is sufficient to invoke it correctly. The only shortfall is that enumerating return fields duplicates the output schema rather than adding routing or behavioral context.

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 a single parameter with 100% schema description coverage, and the schema already explains that the id comes from list_maintenance. The description contributes 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 resource (a single maintenance window) and enumerates the exact fields returned: title, description, start/end, phase, covered monitors, and paging behavior. The singular framing implicitly contrasts with the sibling list_maintenance, so an agent can tell fetch-one from list-many 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?

Usage is only implied: an agent infers this is the read-one-by-id companion to list_maintenance. There is no explicit when-to-use statement, no mention of prerequisites, and no named alternative for cases where the caller has no id.

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?

With readOnlyHint already set, the description still adds real context: 'Credentials are withheld' warns the agent that secrets will be absent and prevents false assumptions, and the round-trip guarantee ('every field update_monitor can change is readable here, in the shape that tool takes') tells the agent it can safely read-modify-write. 'Read-only' merely restates the annotation.

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

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

Three sentences, front-loaded with the core identity, then usage conditions. The long parenthetical enumeration of alerting fields is dense but each item maps to actual returned data, so it earns its place; only slightly over-packed for a single-screen read.

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

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

An output schema exists so return shape needn't be spelled out, and the description still covers what's included and what's deliberately excluded (credentials). Combined with the safety hint and the read-before-update advice, 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?

Single parameter with 100% schema coverage, and the schema already says the id comes from list_monitors. The description adds nothing beyond that about the id (format, prefix, or failure mode for a bad id), so baseline 3 applies.

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

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

States a specific verb and resource ('One monitor's full configuration') and enumerates exactly what is returned: assertion fields, probe regions, alerting behavior, current state, last error, uptime windows. This clearly separates it from get_monitor_history (history), list_monitors (enumeration), and update_monitor (mutation).

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 conditions: 'before judging whether a response should have passed, or before changing a monitor.' Implicitly positions itself against update_monitor by guaranteeing field parity. No explicit when-not guidance or direct naming of get_monitor_history as the alternative for historical data.

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?

readOnlyHint=true already covers the safety profile, and the description reinforces it with 'Read-only.' It adds genuine value by disclosing the payload composition (per-region split, failure error text, incident windows), though the existing output schema would carry some of that weight.

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

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

A single front-loaded sentence plus one purpose clause and a safety tag — dense but every listed item is informative. The comma-separated enumeration is slightly heavy but 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?

With a full input schema, an output schema, and a readOnly annotation, the description supplies everything else an agent needs: what the payload covers, the purpose of region filtering, and the safety profile. No material gaps.

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 baseline is 3; the description earns above baseline by explaining what `region` actually scopes (uptime, latency series, region breakdown) and why an agent would narrow it, which goes beyond the schema's wording. `id` and `window` need no extra explanation given the schema's enumerations.

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 ('one monitor's history') and enumerates exactly what the response contains (uptime, latency, region split, failures, incident windows). This clearly separates it from get_monitor (config) and list_monitors (enumeration).

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?

Explains the operational purpose of the `region` param — telling a partial outage from a total one — which gives concrete when-to-use context. It does not explicitly contrast with get_monitor or list_monitors, so it stops short of full alternative routing.

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 readOnlyHint annotation already indicates this is a safe read operation. The description adds value by explaining the output content (per-state totals and worst failing monitors) and the 'current' snapshot nature, which goes beyond the annotation. The explicit 'Read-only' statement is consistent with the annotation.

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 two short sentences, front-loaded with the key summary and immediately followed by the use case. Every word earns its place, and the redundant 'Read-only' is minimal and harmless.

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

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

For a simple no-parameter tool with an output schema present, the description is complete: it states what the tool does, what data it returns, and when to use it. There are no significant gaps given the tool's simplicity.

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 has zero parameters, so there is nothing to explain. The empty schema is fully covered, and the description correctly omits unnecessary parameter details. Baseline 4 is appropriate for a no-parameter tool.

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 clearly identifies the tool as providing an org health summary with per-state monitor totals and the worst currently-failing monitors. This is specific and distinguishes it from sibling tools like list_monitors and get_incident, and the 'one-shot answer' phrase further clarifies its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the use case: 'The one-shot answer to what is broken right now?'. It does not mention alternative tools or exclusions, but the positioning as a summary tool is clear enough to guide appropriate selection.

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

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

Annotations already declare readOnlyHint=true, so the trailing 'Read-only' adds nothing. However, the description contributes a genuinely non-obvious behavioral fact: caps are pooled across every org the account owns, so counts can exceed what this org holds. That caveat prevents a wrong interpretation of the numbers.

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

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

Two sentences, zero filler, and the identity-plus-metrics content is front-loaded ahead of the pooling caveat. Every clause carries information.

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

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

With an output schema present, return-value structure needn't be restated, and with zero parameters there is no input contract to cover. The description supplies the data semantics (pooling) and safety profile needed to use the result correctly, leaving nothing material 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 the baseline of 4 applies. There is no parameter semantics to add beyond the schema, and the description correctly spends no space on 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 resource pair — the org a connector is bound to plus the account's resource usage against plan limits — and enumerates the exact metrics returned (monitors, status pages, members, components, policy values). That level of specificity clearly separates it from the nearest sibling, get_org_health, 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?

Usage is implied by the content (call it when you need org binding or plan-limit consumption), but the description never states when to prefer it over get_org_health or list_monitors. No exclusions or alternatives are named, so the agent must infer the trigger 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?

The trailing 'Read-only.' merely restates readOnlyHint=true, adding no new safety context. What does add value is the disclosure that the response expands nested data (components carry each linked monitor's current state; groups are rendered as sections with members), which tells the agent this is an aggregated read rather than a flat record. No mention of errors, permission scope, or freshness of the embedded monitor state.

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

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

A single dense sentence front-loads the resource and its returned contents, with no filler. The appended 'Read-only.' fragment is redundant with the annotation and is the one piece that does not earn 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?

With an output schema present and a fully documented single parameter, the description only needs to frame what the call retrieves, and it does so thoroughly by listing the payload's major sections. It stops short of signaling the read-only/aggregated nature relative to sibling tools, which would fully close the 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 exists and schema coverage is 100%, with the schema itself stating the slug comes from list_status_pages. The description does not mention the slug or its format, so it neither adds nor detracts; 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?

The description names a specific resource ('One status page') and enumerates its returned facets: name, public URL, enabled flag, components with linked monitor state, and groups as sections. This clearly distinguishes it from list_status_pages and from monitor-level siblings, though it never names those alternatives 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?

Usage is only implied: 'One status page' plus a required slug suggests fetching detail for a known page. There is no explicit when-to-use guidance, no mention of when to prefer list_status_pages, and no note about what happens if the slug is unknown.

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

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

The annotations already declare readOnlyHint=true, and the description's 'Read-only' statement simply repeats that. However, the description adds useful behavioral context beyond annotations: default filtering to open incidents and a default 30-day window for resolved history. Pagination behavior is left to the schema's cursor documentation.

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 two compact sentences, front-loads the purpose and returned fields, then packs the filter defaults and usage conditions without 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?

Given the output schema exists and the input schema has full parameter descriptions, the description covers the operational essentials: default state, resolved-history window, monitor filtering, and read-only nature. 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?

Schema description coverage is 100%, so the input schema already documents every parameter, including state, from/to defaults, cursor behavior, and monitor_id. The description repeats the key semantics but adds little 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?

The description states a specific verb and resource ('List the org's incidents') and enumerates the returned fields (id, monitor, severity, times, latest update phase). It is clearly a plural listing tool, but it does not explicitly differentiate itself from siblings like get_incident or list_maintenance.

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 explains the default behavior (currently open), when to pass state="all" with from/to for resolved history, and how monitor_id narrows scope. It gives clear usage conditions, though it does not explicitly name get_incident as the alternative for retrieving a single incident.

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, and the description adds real value on top: cursor-based pagination and per-status ordering behavior (soonest first, most recent first, latest start first). It doesn't mention permission/auth requirements, but the pagination and ordering contract is the important operational detail here.

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

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

Single dense paragraph, front-loaded with what is returned before the filtering and pagination mechanics, and every clause conveys usable information. The trailing 'Read-only' duplicates the readOnlyHint annotation, a small redundancy.

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, yet the description still covers field content, filtering semantics, default behavior, ordering, and pagination. Nothing an agent needs in order 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 MaintenanceStatus enum already documents each value plus its ordering, so the description's status explanation largely restates structured data. It reinforces the default and filtering intent but adds no syntax or format detail the schema lacks; 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?

Names a specific verb and resource ('List maintenance windows') and enumerates exactly what each entry contains (title, start/end, phase, covered monitors, paging hold). This clearly separates it from the single-window sibling get_maintenance and from the other list_* 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?

Explains precisely how the status filter narrows results (active, upcoming, past = ended or cancelled) and what the default is, which tells an agent when to reach for this tool versus get_maintenance. It stops short of naming an explicit alternative for single-window lookups, so it gives clear context but no exclusion guidance.

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

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

The trailing 'Read-only' merely restates readOnlyHint=true, earning no extra credit, but the parenthetical genuinely explains the group-alerting model (a member failure opens one group incident and suppresses member alerts), which helps an agent interpret results. It says nothing about rate limits, ordering, or result size, so it adds only moderate value over 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?

A single front-loaded sentence with the scope ('the org's monitor groups, empty ones included') stated first. The long field enumeration somewhat duplicates the output schema that already exists, which is the only inefficiency.

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 does not need to document return shapes, and it usefully defines the one non-obvious concept (the group incident). A note on ordering or result volume would make it fully complete for an argument-free list tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline for a no-param tool is 4. The description correctly spends its words on scope and returned fields instead.

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 resource and scope: the org's monitor groups, explicitly including empty ones, and enumerates the salient fields. It is clearly distinguishable from get_monitor (single monitor) and update_monitor_group (mutation), though it never names those siblings or says 'returns all'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied – an agent infers it should call this to survey monitor groups. There is no explicit 'use this when…' guidance, no mention of when to prefer get_monitor or list_monitors, and no note on ordering or pagination for an unpaginated list.

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?

readOnlyHint=true already declares the safety profile, and "Read-only" merely restates it. The note that each item carries current state and last-checked time is useful, but with an output schema present that information is already available structurally, and nothing is said about page size limits or ordering of results.

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, zero filler, and the filter/pagination scope is front-loaded before the return-shape note. Nothing could be cut without losing information.

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

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

With annotations covering read-only status, a full schema, and an output schema, the description covers the essentials for a filtered list call. It stops short of telling the agent how pagination terminates or whether results are ordered, the only real remaining 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% and the schema already enumerates the valid type and state values plus the cursor's origin. The description only names the same three filter categories, adding no semantics (e.g., whether tag matching is exact or whether filters combine with AND) 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 and resource ("List monitors") plus the scope of its filters and pagination, so the agent knows exactly what the call returns conceptually. It never explicitly contrasts itself with get_monitor or list_monitor_groups, so the sibling distinction is only implied by the verb.

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?

"Optional" filters imply you call it bare to enumerate everything, which is usable guidance, but there is no explicit when-to-use/when-not, no pointer to get_monitor for a single record, and no note on when to prefer filtered listing over client-side filtering.

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 assert readOnlyHint=true, but the description adds substantial behavioral context: the meaning of awaiting_verification and not_delivering (a channel can read as ready yet be broken), how auto_bind_tags extends coverage to tagged monitors, and that channel settings are withheld because they contain webhook URLs and bot tokens. This is real disclosure beyond the annotation.

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 resource and its fields, then layers the two health flags, the auto_bind_tags rule, and the security caveat. Dense but every clause carries information; only mildly 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?

Given an output schema exists, the description need not explain return values, yet it usefully annotates the non-obvious flags (awaiting_verification, not_delivering, auto_bind_tags) that a raw schema would not interpret. Combined with the creation-boundary note and withheld-settings warning, nothing an agent needs 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 input parameters, so the baseline is 4; there is nothing for the description to add or compensate for on the input side. It correctly spends no words pretending there are parameters.

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 ('The org's notification channels') and enumerates the fields returned (id, name, kind, enabled), so the agent knows exactly what it will get. No sibling tool covers notification channels, making it trivially distinguishable from the rest of the catalog.

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?

Clarifies the boundary that channels are created in the Uptimepage app, not via this tool, implicitly steering the agent away from looking for a create sibling. However, it does not state explicit when-to-use/when-not conditions or name an alternative read path, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, and the description reinforces it with 'Read-only.' It adds valuable behavioral detail about `max_regions` appearing only when the plan limit is lower than catalog count, which is beyond 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, each earning its place: the catalog contents, the max_regions behavior, and usage guidance. The most critical usage warning is placed last but clearly marked, and the text is front-loaded with the resource description.

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 doesn't need to detail return values. It covers the fields, the edge case of max_regions, and proper usage, making it fully complete for an agent to call correctly without ambiguity.

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 has zero parameters, so the description carries no parameter burden. The description focuses on output and usage, which is appropriate for a parameterless tool; a 4 reflects the baseline for 0-param tools.

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 clearly states the tool lists probe regions and specifies the exact fields returned: id, display name, city, country, continent, and default status. It also explains its role in supplying valid `region` values for other tools, distinguishing it from sibling list 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 description explicitly directs when to use it: to pass a valid `region` to get_monitor_history and to read where a check runs. It also gives a clear exclusion: not to use it as a menu to fill create_monitor.regions unless the user named specific places.

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 behavioral details beyond the readOnlyHint annotation by disclosing cursor-based pagination and the specific fields returned. While 'read-only' repeats the annotation, the pagination behavior is valuable and not present in 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?

The description is three short sentences, front-loaded with the action and resource. Every phrase contributes to the tool's understanding, with no filler or redundant clauses beyond the optional 'Read-only' which is also in annotations.

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

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

For a simple list operation with a single optional cursor parameter and an existing output schema, the description sufficiently conveys purpose, pagination, and output fields. It lacks explicit default page size or contrast with get_status_page, but these are not critical given the schema and 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?

The input schema already provides a complete description of the cursor parameter (opaque cursor from next_cursor), achieving 100% schema coverage. The description merely mentions cursor-paginated, which aligns with the schema but adds no new syntax or semantics beyond what the schema documents.

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 'List', identifies the resource 'status pages', specifies scope 'org's', and enumerates the fields returned (slug, name, public URL, enabled). This clearly distinguishes it from sibling tools that list incidents, monitors, regions, etc., and from get_status_page which retrieves 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?

The description clearly communicates the tool's function for listing all status pages and notes cursor-based pagination, which implies its use case for enumerating status pages. It does not explicitly contrast with get_status_page or provide exclusionary guidance, but the purpose is self-evident among siblings.

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 readOnlyHint annotation already covers the safety profile, yet the description adds real value beyond it: it flags 'Addresses are customer data' (a PII/privacy warning) and discloses the returned behavioral data such as blocked status and wrong-try counts. It stops short of describing auth/permission prerequisites for reading this sensitive data.

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

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

Front-loaded with the verb and resource, and every clause names concrete return data or a constraint, so little is wasted. It is a single dense sentence, but it is appropriately sized for the amount of information conveyed.

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 enumerate return values, yet it usefully previews them, and annotations carry the read-only guarantee. The only gap is the absence of guidance on prerequisites for accessing customer data on private pages.

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 slug parameter is fully documented in the schema (including its provenance from list_status_pages), so the baseline of 3 applies. The description adds no additional meaning about the slug itself.

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 who signed in to a private status page') and enumerates exactly what the result contains. It is clearly distinct from siblings such as list_status_pages and get_status_page, so an agent can pick 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?

The description scopes applicability to private status pages, which implies when the tool is relevant, but it names no alternative and gives no explicit when-to-use/when-not guidance against siblings like get_status_page or list_status_pages.

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

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

Annotations already declare readOnlyHint=true, and the description redundantly states 'Read-only.' However, it adds behavioral details beyond annotations: it lists tags sorted by usage ('most-used first') and includes per-tag monitor counts, plus the scope covers 'every tag in use across the org's monitors.' This enriches the agent's understanding of output formatting and data scope.

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

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

Two sentences, front-loaded with the essential output description, immediately followed by a usage hint and read-only note. No wasted words.

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 has no parameters and an output schema exists, the description is fully sufficient. It explains the ordering, counting, and how to use the results with list_monitors. No gaps for a simple read-only list tool.

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

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

The tool has zero parameters, so the schema fully covers parameter semantics. The description adds no parameter-specific detail, but none is needed. Baseline for 0 parameters is 4.

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 clearly states the tool lists tags in use across the org's monitors, ordered by usage frequency, and includes monitor counts. It also distinguishes itself by explaining how the output feeds into list_monitors, which is its primary use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: pass a returned tag as the `tag` filter to list_monitors. It implies the tool is a precursor to filtering monitors, but does not explicitly state exclusions or alternatives beyond that. The context is clear and actionable.

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 readOnlyHint annotation, the description discloses that values are never returned and that secret values are never even read. It also explains the security context around credential pasting being refused. This gives the agent an accurate mental model of the tool's safety and behavior.

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

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

The description is compact and front-loaded with the core purpose. Each sentence contributes meaningful context: the resource, the privacy behavior, the usage pattern, and the mutation boundary. There is no redundant 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?

The tool has no parameters and an output schema, so the description only needs to convey what is listed and any important behavioral caveats. It does both thoroughly, including the critical guarantee that secret values are never read or returned. Nothing an agent needs to safely call 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 input schema has no parameters, so there are no parameter semantics to document. The baseline for a zero-parameter tool is 4, and the description appropriately signals that the tool simply lists all variables without requiring input.

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 clearly states the tool lists the org's reusable variables with their keys and secret status. It is distinct from every sibling list_* tool because no other sibling targets variables, and it names the exact resource being operated on.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains why and how variables are used: they go into a monitor's header or body as {{ key }} and are resolved at check time to build authenticated checks. It also explicitly says variables are created and edited in the app, not here, which prevents an agent from attempting mutations. It does not name sibling alternatives, but none are direct alternatives for this resource.

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=false, idempotentHint=true, destructiveHint=true, so the closing 'Not read-only; idempotent' is largely a restatement. The genuinely additive content is the confirmation behavior ('Asks for confirmation where the client can show a prompt; otherwise runs on the token's scope'), which tells the agent about interactive and auth-fallback behavior not captured in 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?

Three tight sentences, each carrying distinct information: the core action, the sibling alternative for planned work, and the confirmation/scope behavior. The core action is front-loaded and 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?

An output schema exists, so return values need no explanation. For a single-param mutation the description covers the effect, the alternative tool, the confirmation prompt, and the token-scope fallback — enough for an agent 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?

There is a single parameter with 100% schema description coverage, and the schema already tells the agent the id comes from list_monitors. The description adds no format or sourcing 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+resource ('Pause a monitor') and immediately clarifies the scope of the effect ('stop its checks until resumed'), which an agent can distinguish from sibling operations like resume_monitor or create_monitor 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 routes the agent: 'For planned work, create_maintenance holds paging instead while the checks keep running' names the alternative and the condition that selects it. It also implies the resume_monitor counterpart ('until resumed').

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=false and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavior: a confirmation prompt where the client supports one, fallback to the token's scope otherwise, and the fact that the message becomes publicly visible. It does not mention whether posting a 'resolved' phase mutates incident state or any rate limits, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the core action and audience before the confirmation caveat. 'Not read-only' is largely redundant with the readOnlyHint annotation, a minor wasted clause, but nothing else is padding.

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

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

With an output schema present and annotations covering mutability, the description supplies the missing pieces an agent needs: public visibility of the content, the confirmation/token-scope auth behavior, and the phase+message shape. It stops short of describing side effects on incident status or failure modes, which is a small residual 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 coverage is 100% and the schema already documents the id, the full phase list with default, and Markdown formatting rules. The description only restates 'phase + message' without adding syntax or constraint detail, so it earns the baseline 3 for a schema that does the heavy lifting.

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

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

States a specific verb and resource (post an update to an incident's status-page timeline) plus the fields it carries (phase + message). The incident focus cleanly separates it from the sibling post_maintenance_update, and the 'public, customer-facing' qualifier tells the agent this is outward-visible output, not an internal note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description establishes the audience ('what your subscribers and status-page visitors see'), which implies when this tool is appropriate, but never states explicit when-to-use or when-not conditions versus siblings like publish_incident, resolve_incident, or post_maintenance_update. The agent must infer the routing decision.

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, the description explains the downstream effects: updates appear on status pages and go to email and webhook subscribers, and cannot be edited or removed. It also discloses the confirmation-prompt behavior and token-scope fallback, which are important operational details for a non-read-only action.

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 action and then adds scope, effects, and confirmation behavior in compact sentences. Every sentence provides useful operational context without 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?

The description covers the tool's action, valid window states, user-visible effects, immutability, and confirmation behavior. With an output schema present and 100% parameter documentation, no critical information is missing 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 description coverage is 100%, so the schema already documents both parameters in detail, including the message length and Markdown support. The description reinforces the message intent but does not add syntax or constraints beyond the schema.

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

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

The description uses a specific verb and resource: posting an update to a maintenance window, with concrete examples of what the update can say. It also distinguishes this from window-editing operations by noting that a completed window is read-only otherwise, so this is the way to add a closing note.

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 clearly states when the tool works: upcoming, running, or completed windows, and explicitly excludes cancelled windows. It does not explicitly name update_maintenance or cancel_maintenance as alternatives, but the state-based guidance is clear enough for correct use.

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 annotations (readOnlyHint=false, idempotentHint=true), the description discloses that subscribers may be notified, that confirmation may be requested, and that the status_page_ids list replaces existing pages—behavioral details not captured in annotations. No contradiction.

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 sentences, front-loaded with the main action. Each sentence adds necessary context (monitor vs no monitor, replacement behavior, notification, confirmation, idempotency). Slightly long but no redundancy.

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 all critical aspects: the publishing behavior, the conditional use of status_page_ids, replacement semantics, notification side effects, confirmation behavior, and idempotency. The output schema exists, so return values are covered. No missing information 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% with detailed descriptions for all parameters, including the replacement semantics for status_page_ids. The tool description adds only a general 'optionally seeding' phrase, which adds little beyond the schema. 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 clearly states the verb 'publish' and the resource 'incident', and explains the effect (appears on status pages). It differentiates from siblings like unpublish_incident and post_incident_update by focusing on the publishing action and its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to set status_page_ids (incidents with no monitor) and when not to (monitor incidents). Mentions starting from get_incident's status_page_ids. While it doesn't name alternative tools, it gives clear when/when-not conditions for parameter 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?

The description adds meaningful behavioral detail beyond the annotations: it states the operation is not read-only, confirms the internal-only status page behavior, and explains the confirmation/authorization behavior ('Asks for confirmation where the client can show a prompt; otherwise runs on the token's scope'). This is valuable context that annotations alone do not provide, and it does not contradict the destructiveHint or idempotentHint.

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 three concise sentences with no filler. It front-loads the core purpose, then adds behavioral caveats and a scope clarification. Every sentence contributes useful information for tool selection and invocation.

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 output schema exists, the 100% schema coverage, and the annotations describing read-only, idempotency, and destructiveness, the description adds the remaining essential context: internal scope, public status page exclusion, and confirmation behavior. An agent has enough information to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the internal-only nature of the note, which is already documented in the schema, and does not add new parameter-level meaning beyond what the schema provides. The required 'id' parameter is also already described adequately in the schema.

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

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

The description states a specific verb and resource ('Resolve an incident') and clarifies the exact meaning with 'mark the operational state resolved.' It also distinguishes itself from sibling tools by explicitly noting 'Internal only — does not post to the public status page,' which differentiates it from publish_incident and related public-facing 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 description provides clear context for when to use the tool: resolving an incident internally without public status page impact. It does not explicitly name alternative tools, but the 'Internal only' and 'does not post to the public status page' exclusions effectively guide tool selection among siblings like publish_incident and post_incident_update.

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 mark the tool as not read-only and idempotent, and the description restates those facts. It also adds meaningful behavioral context beyond annotations: the confirmation prompt behavior and the fallback to the token's scope when a prompt cannot be shown.

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 short, front-loaded with the primary action, and uses only three sentences. The 'Not read-only; idempotent' sentence partially duplicates annotations, but it is brief and does not bloat the description.

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 tool with an output schema and annotations covering safety/idempotency, the description gives enough context to call it correctly. It explains the effect, the confirmation behavior, and token scope, and the output schema covers return values.

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 that `id` is the monitor id from `list_monitors`. The tool description does not add extra 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?

The description states a specific verb and resource: 'Resume a paused monitor (restart its checks).' This clearly separates it from pause_monitor and run_check_now, making the tool's purpose immediately obvious.

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 phrase 'Resume a paused monitor' implies when to use it, but it does not explicitly name alternatives or state when not to use it. It gives some contextual guidance about confirmation and token scope, but no direct comparison to sibling tools.

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 it discloses meaningful behavior: a confirmation prompt is requested where the client can show one, otherwise it executes on the token's scope, a down result can fire the org's normal alerts, and heartbeat monitors cannot be probed. These are exactly the side effects, auth/scope, and constraint details an agent needs for a non-idempotent action.

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, front-loaded with the action, then confirmation behavior, side effects, and the heartbeat limitation. Every sentence carries distinct information and none is redundant.

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 fully covers side effects, confirmation semantics, scope behavior, and the one hard exclusion. 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?

There is one parameter (id) with 100% schema description coverage, and the schema already points to list_monitors for the source. The description adds no syntax or format detail for the id beyond what the schema provides, 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: 'Run a check on a monitor immediately and record the result.' This is clearly distinct from sibling read tools like get_monitor and get_monitor_history, and from state tools like pause_monitor/resume_monitor, so an agent can route to 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?

Gives clear usage context (immediate check, confirmation prompt behavior) and an explicit exclusion (heartbeat monitors cannot be probed). However, it does not name an alternative tool or spell out when to prefer this over simply reading monitor state via get_monitor, so it stops short of full when/when-not/alternatives guidance.

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

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

Far exceeds the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true) by disclosing the ~30-second incident-open latency, that channels are paged unless a maintenance window holds it, the status-page presentation per state, that up closes the incident, that the note becomes the incident cause, and the confirmation/token-scope behavior. This is exactly the mutation side-effect 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-loads the core action and legal values in the first sentence, then layers consequences. Dense and mostly waste-free, though the note guidance ('make it a reason a responder can act on') partially duplicates the schema's own note description.

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

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

An output schema exists so return values need no explanation, and the description covers the remaining risk surface for a mutating tool: incident lifecycle, paging, maintenance suppression, paused-plan edge case, refusal conditions, and confirmation/auth behavior. Nothing material is missing.

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

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

With 67% schema coverage the schema already documents id, state and note, but the description adds intent-level guidance the schema lacks: why the state matters (outage vs degraded on status pages), that the note must be actionable for a responder, and the monitor-kind constraint on id. It adds real semantic value over the structured 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?

States the exact verb and resource (set the state of a manual monitor) plus the three legal values, and immediately scopes it to manual monitors with no probe, distinguishing it from every update_monitor/pause_monitor sibling. An agent knows precisely what this does 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 a strong when-to-use rationale ('a service only people can judge, such as a SIP trunk, a carrier link or a partner's back office') and an explicit when-not ('Refused for any other kind of monitor'), plus the paused/no-longer-covered caveat. It stops short of naming sibling alternatives such as pause_monitor or update_monitor for adjacent operations.

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, the description adds genuinely useful behavioral context: the operator timeline is untouched, and it 'asks for confirmation where the client can show a prompt; otherwise runs on the token's scope,' covering both interactive and non-interactive paths. The final sentence ('Not read-only; idempotent') restates the annotations rather than adding value, but the other disclosures lift this above baseline. No contradiction with readOnlyHint=false, idempotentHint=true, or destructiveHint=true.

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 is front-loaded in the first sentence, with behavioral caveats following in short, separate sentences. The only waste is the final 'Not read-only; idempotent,' which duplicates the annotations — a minor redundancy in an otherwise tight definition.

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

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

For a single-parameter tool with a full output schema and safety annotations, the description covers the essential added context: the reversible nature of the action, the unaffected operator timeline, and the confirmation/token-scope behavior. No critical call-blocking information 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 schema already documents the single id parameter at 100% coverage, including a provenance hint ('from list_incidents or get_org_health'), so the schema carries the full load. The description adds no parameter-specific meaning, which per the baseline rule for high schema coverage warrants a 3.

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

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

The description uses a specific verb and resource — 'Hide a published incident from the public status pages again' — clearly identifying what the tool does. The 'again' phrasing and the unpublish/publish pairing with sibling publish_incident make the action unambiguous, though it doesn't explicitly name the sibling it inverts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: call this when an incident is currently published and you want to remove it from public status pages, and 'again' signals it reverses a prior publish action. However, it doesn't explicitly name alternatives such as publish_incident or state conditions for when not to use it, leaving the routing decision 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 and idempotent=true; the description adds genuinely new behavior: a pre-execution diff of old vs new values shown where the client supports a prompt, falling back to the token's scope. It also clarifies that end_now marks the window completed rather than deleting it. Slight repetition of 'not read-only' is the only wasted clause.

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 dense sentences, front-loaded with the purpose and scope before the field-level and behavioral details. Every sentence carries information, though the closing 'Not read-only' is redundant with readOnlyHint=false.

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 and full parameter documentation, the description need only cover mutation semantics — and it does, including refusal of history windows and the confirmation prompt. Missing only an explicit pointer to cancel_maintenance for permanent termination.

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 documents replace semantics, end_now exclusivity, RFC 3339 formats, and length limits. The description's restatement of monitor_ids replacing the whole set and end_now's outcome adds marginal meaning beyond the schema, so this sits at 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?

Opens with a specific verb+resource and an explicit scope constraint ('Edit an upcoming or running maintenance window'), then enumerates the editable fields. An agent can distinguish it from create_maintenance, cancel_maintenance, and get_maintenance without consulting 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?

States the preconditions clearly (only upcoming or running windows; completed/cancelled are refused) and explains when to use end_now instead of end dates. It does not name cancel_maintenance as the alternative for terminating a window permanently, which is the one obvious routing gap.

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 channel_ids and tags are full replacements (not merges), that Terraform-managed monitors are refused outright, and that the client previews old vs. new values before running or else acts on the token's scope. This is exactly the kind of consequence detail a destructiveHint=true mutation 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?

Front-loaded with the core purpose and tightly organized into editable fields, refused fields, and execution behavior. It is dense but every clause carries operational weight; only the density of the long opening sentence slightly taxes readability.

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 10-parameter mutation with an output schema present, the description covers scope requirements, refusal conditions, replacement semantics, and preview behavior, leaving nothing an agent needs to call it correctly unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top of it: replacement vs. additive semantics for channel_ids and tags, the scope requirement, and the explicit list of non-editable parameters that error rather than no-op. This meaningfully compensates beyond what the schema states.

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

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

States a precise verb (change) and resource (monitor), then enumerates exactly which fields are mutable (interval, alert confirmations, recovery, renotify, tags, group, region quorum, channels) and which are refused. This distinguishes it clearly from create_monitor, pause_monitor, and set_monitor_state without needing to name them.

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 strong when/when-not guidance: it names the preconditions (channels:read scope for channel_ids, Terraform-managed monitors are refused) and the excluded field set. It does not explicitly route to a sibling for the refused operations, but the constraints are clear enough to prevent misuse.

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

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

Goes well beyond the annotations by disclosing the dry-run preview (old and new value of every field, prompting where the client supports it, otherwise token-scope fallback), the hard refusal for Terraform-managed groups, the non-retroactive semantics of alert_as_one, and the scope requirement on channel_ids. Annotations only say destructive/idempotent; the description explains what is actually destroyed and what is refused.

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 verb and the enumerated mutable fields, then constraints. The long parenthetical describing alert-as-one is dense but carries real semantics; a few clauses (e.g., restating channel_ids replacement already in the schema) could be trimmed without loss.

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

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

For a destructive mutation with an output schema already covering returns, the description supplies everything else an agent needs: confirmation/preview behavior, scope fallback, Terraform refusal, and retroactivity rules. Nothing material is left for the agent to guess.

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 baseline is 3, but the description adds genuinely new parameter-level meaning: channel_ids requires the channels:read scope, and alert_as_one is explicitly non-retroactive for already-open incidents. The explanations of alert-as-one fan-out and alert_again largely restate the schema descriptions, keeping it below a full 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 (change) and resource (monitor group) and enumerates exactly which fields are mutable: name, alert-as-one, channel set, reminder interval, alert_again. An agent can distinguish this from update_monitor and list_monitor_groups 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 concrete gating context: Terraform-managed groups are refused outright, channel_ids requires the channels:read scope, and turning alert-as-one on/off only affects failures that start afterwards. It does not name a sibling alternative (e.g., update_monitor for individual monitors) or state exclusions for when not to use it, so it stops short of a 5.

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

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

Strongly exceeds the annotations: it spells out that slug changes move the public URL and break links, that access replaces the whole settings object, that protected=true removes uncovered subscribers and requires Team plan, that protected=false keeps the list, and that it is not read-only and idempotent. These are the destructive/side-effect facts an agent needs beyond destructiveHint=true and idempotentHint=true.

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 four capabilities, then gives the partial-update rule, then the highest-risk consequence (URL breakage), then access semantics. Well ordered and dense; the access sentence is long but every clause carries actionable meaning.

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

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

Given annotations that already flag destructiveness and idempotence, plus a 100%-covered schema and an output schema, the description supplies exactly the missing behavioral context: partial-update semantics, URL migration risk, and access replacement/subscriber-removal consequences. Nothing critical is absent 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 already 100% and includes good field descriptions, but the tool description adds cross-parameter semantics the schema cannot: omitted fields are left alone, access replaces rather than merges, and the protected true/false consequences on subscriber removal and list retention. It does not add much on name/enabled specifically, but those are self-explanatory.

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, then enumerates exactly the four kinds of change this tool makes: rename, re-slug, publish/unpublish, change access. It is immediately distinguishable from siblings like get_status_page, list_status_pages, create_status_page and update_status_page_component.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description establishes when to use this tool (an existing page, partial updates) and implicitly contrasts with create_status_page by saying 'An omitted field is left alone.' It does not name alternatives explicitly, but the update-vs-create and update-page-vs-update-component boundaries are clear enough from the phrasing.

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=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavior beyond those annotations: omitted fields are left alone, section member headings come from the section, and public_group is ignored in that case. It does not add auth or rate-limit context.

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 tightly written sentences front-load the main action and then add the critical exception and field-preservation rule. There is 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?

The tool is a mutation with annotations and an output schema, so the description need not explain return values. It covers the key mutation semantics and section/member exception. It could say more about monitor_id vs section_id exclusivity and error behavior, but is sufficient 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 63%, with key parameters like slug, heading, monitor_id, section_id, and public_group documented in the schema. The description adds meaningful semantics: omitted fields are preserved, section_id targets a section heading, and public_group has no effect on section members. This compensates well for the remaining gaps such as sort_order and public_name details.

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: changing how one monitor is presented on a status page, or with section_id, a section heading. It clearly scopes the tool to component-level curation, distinguishing it from the page-level sibling update_status_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 explains the two usage paths: monitor curation by default, or section heading via section_id. It also warns that public_group does nothing for a section member. It does not name alternative tools such as update_status_page or add_status_page_components, but the context is otherwise clear.

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