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

Annotations declare openWorldHint=true and non-destructive/non-idempotent, but the description adds the key consequence: the incident is published publicly on the status page and wording should be drafted with the user first. It doesn't detail permission requirements or whether a draft (publish=false) can be edited later, so it's good but not exhaustive.

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

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

Three short sentences, front-loaded with the create action, then scoping detail, then the workflow caution. The componentStatus default repeats the schema, a minor redundancy, but overall tight.

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

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

For a 9-parameter mutation with no output schema, the description covers the public-facing consequence, default component status, and a caution about drafting wording. Remaining gaps (pagination/return shape not needed; auth/permissions) are modest given the rich annotations and full schema coverage.

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 parameters are already fully documented with descriptions and defaults. The description only restates the componentStatus default (PARTIALOUTAGE), which the schema already provides, adding no new syntax or format detail.

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 (publish a new incident) and scope (public status page), which cleanly separates it from siblings like post_incident_update, resolve_incident, and delete_incident. An agent can identify the create action without opening the schema.

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

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

The line 'Draft the wording with the user before publishing' gives useful procedural advice for this specific workflow, and the schema reinforces confirming before notifying subscribers. However, it never states when to use this versus alternatives (e.g., post_incident_update for later updates) or any exclusions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by clarifying the blast radius (history is removed too) and irreversibility ('Cannot be undone, so confirm first').

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 short sentences, zero waste, with the permanence/blast-radius warning front-loaded and the confirmation requirement attached. Nothing could be trimmed without losing signal.

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 two-parameter destructive tool with full schema coverage and annotation-declared safety, the description covers what an agent needs: what is destroyed, that it is irreversible, and to confirm first. Minor gaps remain around side effects on linked incident updates or components, but nothing critical 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 both parameters carry their own descriptions pointing at list_status_pages and list_incidents. The description adds no meaning about pageId or incidentId, 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 (delete an incident) plus scope detail ('and its history from the status page'), which separates it from the non-destructive sibling resolve_incident. It does not explicitly name resolve_incident as the alternative, so the routing is implicit rather than spelled out.

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 one useful operational guideline – confirm before calling, since the action is irreversible – but never states when to delete versus resolving or archiving via siblings like resolve_incident. Usage context is implied by the destructive nature rather than explained.

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 openWorldHint=true, so the safety profile is covered. The description does add value by enumerating what is returned (description, status, group, uptime settings), useful since there is no output schema, but it says nothing about error behavior, missing components, 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?

A single sentence, front-loaded with the verb and resource, with the returned fields listed compactly. 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?

For a simple read-only getter with no output schema, the description usefully discloses the shape of the response and annotations cover safety. It is nearly complete; only failure/not-found behavior is unaddressed, which is a minor gap for this tool class.

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 both parameters are documented there, including provenance hints (from list_status_pages, from list_components), so the schema does the heavy lifting. The description adds no parameter-level detail beyond implying the component is already identified; 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 names a specific verb (Get) and resource (component), and the phrase 'one component' implicitly contrasts with the sibling list_components. It is clear what the tool returns, though it never explicitly names list_components as its collection counterpart the way a top-tier definition would.

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 can infer this is for fetching a single already-known component (which is why both pageId and componentId are required), but the description offers no explicit when-to-use guidance or named alternatives. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the key behavioral trait that the returned user is the owner of the API key, plus the concrete fields returned. It stops short of mentioning auth failure behavior, so it is not a 5.

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

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

A single sentence that front-loads the action and resource, with the returned fields in a compact parenthesis. 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?

For a zero-parameter, read-only identity lookup with no output schema, the description supplies the essential facts: what is fetched and which fields come back. It omits only edge behavior such as invalid or expired API keys, a minor gap for this complexity level.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The parenthetical field list (id, name, email) usefully pre-announces the response shape in the absence of an output 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 (Get) and resource (the Instatus user that owns the API key), and names the returned fields (id, name, email). This clearly distinguishes it from all siblings, which operate on status pages, components, incidents, and maintenances rather than the authenticated user.

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 usage context is implied rather than stated: 'the user that owns the API key' hints that this identifies the caller associated with the credentials, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Adequate but with a clear 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety semantics are covered. The description's added value is disclosing the return shape — full update timeline and affected components — which matters because there is no output schema. It omits error behavior for unknown IDs, keeping it short of a 5.

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

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

A single front-loaded sentence with no filler; the resource and the returned content are stated immediately.

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

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

With no output schema, the description usefully summarizes what comes back (timeline, components), and annotations cover the read-only nature. It is largely complete for a two-parameter read tool, though it could note behavior for missing/invalid IDs.

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

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

Schema description coverage is 100%, so both pageId and incidentId are already documented with their source tools (list_status_pages, list_incidents). The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one incident') and adds scope beyond the name by specifying the payload includes the full update timeline and affected components. It implicitly distinguishes itself from list_incidents by saying 'one incident', but never names the sibling, so it falls short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no mention of how it differs from list_incidents or get_status_overview. The agent can infer it is a single-record fetch, but nothing in the text routes it explicitly.

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=true, openWorldHint=true), and the description adds genuinely useful context by enumerating what the aggregate contains, which is not derivable from the annotations. It does not mention rate limits, pagination, or whether incident lists are truncated, which slightly limits full transparency.

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 well-formed sentence that front-loads the core value proposition ('One-call answer to is anything down right now?') and then enumerates the payload. 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?

With no output schema, the description usefully carries the return-value burden, and a one-parameter read-only tool needs little else. Minor gap: it does not indicate result size limits or completeness guarantees for the aggregated incident/maintenance lists.

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, so the schema already documents pageId and its source (list_status_pages). The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description states exactly what the tool returns: overall state, components grouped by status, open incidents with their latest update, and upcoming/in-progress maintenance. This composite scope is clearly distinguishable from sibling read tools like list_components, list_incidents, and list_maintenances, which return single resource types.

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 framing 'One-call answer to is anything down right now?' gives a clear context for use and implicitly recommends it over making several sibling calls. It stops short of explicitly naming those alternatives or stating when not to use it (e.g., when detailed per-incident data is needed).

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 openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond that: no pagination behavior (even though page/per_page exist), no rate limits, no note on what happens with an invalid or unknown pageId.

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 that names the resource, its scope (a status page), and the payload fields returned. Nothing dangles and nothing is wasted.

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

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

No output schema exists, and the description does mention the key returned fields (current status and group), which is the right compensation. It stops short of describing pagination behavior for a three-parameter list tool, leaving a minor gap.

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

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

Schema description coverage is 100%, so page, pageId, and per_page are all documented in the schema (including defaults and ranges), making 3 the baseline. The description adds no parameter-level detail such as the format of pageId or how pagination interacts with the result set.

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

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

States a specific verb (List) and resource (components), and helpfully clarifies that components mean services and that results include current status and group. It is distinguishable from get_component (singular fetch) and set_component_status (mutation), though it never names those siblings explicitly.

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

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

Usage is only implied — list the components of a status page. There is no statement of when to prefer this over get_component for a single service or over get_status_overview, and no prerequisites beyond the pageId requirement visible in the schema.

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 openWorldHint=true, so the safety profile is covered by structured data. The description adds ordering (newest first) and the fact that updates and affected components are bundled in, but says nothing about the page size default, total counts, or truncation behavior, so it adds only moderate context beyond 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?

Two tight sentences with the core behavior front-loaded and the filter example second. Nothing is wasted, though the example values partially duplicate what the schema's status description already lists.

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

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

For a read-only list tool with no output schema, the description covers what is returned (incidents with updates and affected components) and the ordering, and the schema carries pagination and filter details. The relationship to get_incident and pagination semantics is the only meaningful gap.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema and the baseline is 3. The description reinforces the status filter with an example of open-incident statuses but never mentions excludeStatus, and adds no format or syntax detail the schema lacks.

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 incidents on a status page) plus the return shape (updates and affected components) and ordering (newest first). It does not explicitly distinguish itself from siblings like get_incident or list_maintenances, but the resource is unambiguous enough to route an agent correctly.

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 second sentence gives a concrete usage cue: pass comma-separated statuses such as 'INVESTIGATING,IDENTIFIED,MONITORING' to get open incidents. That is genuinely helpful, but there is no guidance on when to use this versus get_incident or how it relates to the paginated listing workflow, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that all three lifecycle states are returned, which is useful context, but says nothing about ordering, pagination behavior, or result volume.

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 resource and scope stated immediately and zero 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?

For a simple read-only list with a fully documented schema and annotations carrying the safety profile, the description covers what is needed to call it. The only minor gap is the unexplained return shape, since no output schema exists.

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

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

Schema description coverage is 100%, so all three parameters (page, pageId, per_page) are already documented in the schema. The description adds no format, default, or sourcing detail beyond what the schema provides, which is the expected 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?

Names a specific verb (List) and resource (maintenance windows) and scopes it to a status page, with the covered statuses (scheduled, in-progress, past) spelled out. It does not explicitly distinguish itself from the sibling write tool schedule_maintenance, but the read/write split is inferable.

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 can infer this is the way to read maintenance windows — but there is no explicit when-to-use statement, no note that pageId must come from list_status_pages (that lives only in the schema), and no mention of alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value by naming the return payload (id, name, subdomain, custom domain, overall status), which matters because there is no output schema; it stops short of describing pagination behavior or access scoping.

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 no filler; the parenthetical field list is the only extra content and it earns its place given the absent output schema. Slightly terse, but nothing is wasted.

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

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

For a simple read-only listing tool with annotations covering safety and a schema covering both parameters, the description is nearly sufficient. The one gap is any mention of pagination or result limits, which an agent calling with defaults might want to know.

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?

Both parameters (page, per_page) are fully documented in the schema at 100% coverage, so the baseline of 3 applies. The description adds no pagination guidance beyond what the schema already states.

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

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

States a specific verb (List) and resource (the user's Instatus status pages) and enumerates the fields returned. The resource is clearly distinct from sibling list tools (list_components, list_incidents, list_maintenances), though the description never explicitly contrasts itself with 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?

Usage is only implied: an agent can infer this is the entry point for enumerating the account's status pages. There is no statement of when to use it versus alternatives, no prerequisites, and no note that it returns the pages the authenticated user owns or can access.

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 a non-read-only, non-idempotent, non-destructive mutation, and the description usefully adds that the update is PUBLIC (customer-visible) and that componentStatus is propagated to components. It still omits the subscriber-notification side effect, which is the highest-impact behavior, so it is not fully transparent.

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

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

Two tight sentences with the primary action front-loaded and the conditional componentStatus side effect placed second. Every clause earns its place; no filler.

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

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

For a mutation tool with no output schema, the description covers the main action and the componentStatus side effect adequately. It leaves the notify-customer behavior to the schema, which is acceptable, though a note on public visibility risk would round it out.

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 83% schema description coverage, the schema already carries most parameter meaning. The description adds the transition example for status and the conditional application of componentStatus, but adds no syntax or format detail 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?

States a specific verb and resource ('Add a public update to an incident') and clarifies the meaning with a concrete status-transition example. Distinguishes itself from read tools, but does not differentiate from the sibling resolve_incident given that RESOLVED is part of the status enum.

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 example ('move from INVESTIGATING to IDENTIFIED') implies when this tool is used, but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as resolve_incident for the terminal transition. Usage is only indirectly conveyed.

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 (non-read-only, non-destructive, non-idempotent, open-world), and the description adds real behavioral value by disclosing the cascade: a RESOLVED update plus mass component reset to OPERATIONAL. It stops short of stating permission requirements or what happens to components already operational.

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 that names the action first and the two side effects after. No filler; every clause earns its place.

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

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

With no output schema, the description adequately conveys the outcome shape. Combined with fully documented parameters and annotations, an agent has enough to call it correctly, though permission/edge-case behavior remains 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 description coverage is 100%, so all four parameters (including the notable subscriber-notification warning on 'notify' and the message default) are already documented in the schema. The description adds nothing parameter-specific, 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 (Resolve) and resource (incident), and uniquely explains what the operation actually does — posts a RESOLVED update and flips affected components to OPERATIONAL. This clearly separates it from siblings like post_incident_update or set_component_status, which each perform only half of the work.

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 'in one step' implies this is the preferred composite action over manually posting an update plus resetting components, but no explicit when-to-use/when-not guidance or named alternative is given. Usage is only indirectly inferable from the sibling set.

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, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds genuine behavioral context beyond that: auto-start/auto-end defaults and the fact that affected components display UNDERMAINTENANCE while running. Useful effect disclosure, though it omits notification side effects.

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

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

Two tight sentences, front-loaded with the core action and then the default behavior/effect. No waste, though it is very short relative to a 10-parameter mutation tool.

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

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

For a write tool with no output schema and rich annotations, the description covers the action, defaults, and visible effect. It does not mention the notify/customer-communication implication, but the schema handles that, so the definition is largely complete.

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

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

Schema description coverage is 90%, so the schema already documents nearly every parameter (including defaults for autoStart/autoEnd and the customer-facing warning for notify). The description only echoes the auto start/end default and adds no syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Announce a planned maintenance window.' The resource (maintenance window) is distinct from incident-oriented siblings, but the description never names an adjacent tool explicitly to differentiate. Clear purpose, mild gap on sibling routing.

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 'planned maintenance window' (vs unplanned incidents handled by create_incident), but there is no explicit when-to-use, no exclusions, and no named alternative. Adequate but leaves routing 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 it is a non-readonly, idempotent, non-destructive, open-world mutation, so the safety profile is covered. The description adds a genuinely useful behavioral trait not in the annotations: the change is customer-visible. It does not mention permission requirements or error behavior, which keeps it short of a 5.

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

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

Two compact sentences, front-loaded with the action and scope, with the customer-visibility caveat attached immediately after the examples. No filler.

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

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

For a 3-parameter, no-output-schema mutation, the description covers what it does, how it differs from the incident path, and the customer-facing consequence. It omits auth/prerequisite notes and any mention of success/failure behavior, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 67%: pageId and componentId carry their own source hints, and status is a closed enum that already enumerates the legal values. The description's examples (DEGRADEDPERFORMANCE, OPERATIONAL) merely restate enum members, so it 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 gives a specific verb and resource ('Change a component's status') plus scope ('on the public status page') and explicitly distinguishes the action from opening an incident. An agent can separate it from create_incident/post_incident_update without reading the schema.

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

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

It clarifies this route is for direct status changes rather than incident creation, effectively naming the alternative mechanism by negation ('without opening an incident'). It lacks an explicit when-not or prerequisite statement, but the selection context is clear.

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