Status.io MCP by usefulapi

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

Annotations already declare write/destructive/openWorld/non-idempotent, but the description adds material behavior the structured fields cannot convey: public visibility to every visitor immediately, status mutation of affected components, silent-by-default notification channels, and the return of the new incident id. That is exactly the added context the annotations do not supply.

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 short sentences, zero filler, with the write classification and public-visibility warning front-loaded before the notification caveat and the endpoint. Every clause carries information an agent needs.

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 15-parameter public-facing mutation with no output schema, the description covers the critical danger (immediate public exposure, silent notifications) and the return value. It omits mention of the default state value and required fields, but those are fully documented in the schema, so the gap is minor.

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 a 3 is the baseline; the description earns extra by explaining semantic intent beyond the field names — that notify_* flags must be explicitly enabled for any notification to fire, and that scope is expressed either as all_infrastructure_affected or as component-container pairs. It does not add format detail for name/details/status or explain the state vs status distinction.

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

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

States a specific verb and resource ('open a new incident on the PUBLIC status page') plus the side effect (sets affected component status), which cleanly separates it from statusio_update_incident, statusio_resolve_incident, and the maintenance siblings. The 'WRITE:' prefix immediately classifies the operation as a 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?

Clearly frames the context: new public incident, notifications off by default unless notify_* flags are switched on, and how to declare affected scope via all_infrastructure_affected or infrastructure_affected pairs. It does not explicitly say when to prefer statusio_schedule_maintenance or statusio_update_incident instead, so it falls short of a full when/when-not/alternatives treatment.

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

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

Annotations already declare destructive=true, idempotent=true, and readOnly=false, so the safety profile is covered. The description adds valuable behavior beyond that: the event moves to history, components return to operational, the message is public immediately, and notifications are off unless notify_* flags are enabled. It does not discuss permissions or rate limits, so 4 rather than 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 compact clauses front-load the operation type, the effects, and the notification caveat, and end with the endpoint. No sentence 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 destructive, multi-parameter write tool with full schema coverage and no output schema, the description supplies the key operational context: what happens to the event, what happens to components, and how notifications behave. Only ancillary details like auth requirements or error handling are absent, which is 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 the schema already documents all 11 parameters thoroughly. The description only adds meaning to the notify_* family ('No notification is sent unless you switch it on'), which is already implied by the schema defaults. 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 (finish), resource (active maintenance event), and consequences (moves to history, components return to operational). This clearly separates it from siblings like start_maintenance, schedule_maintenance, and update_maintenance without opening their schemas.

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

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

The description establishes clear context: use it to finish an active event, and it is a WRITE operation. It does not explicitly name alternatives or when-not-to-use it (e.g. versus update_maintenance), so it falls short of a 5, but the usage is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the valuable detail that this returns the complete incident record including messages, which is the main behavioral distinction from the message-level sibling; it does not mention rate limits or error behavior, but those are minor here.

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

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

Two compact sentences with zero filler, front-loading what the tool returns and following with the underlying endpoint. 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?

There is no output schema, so the description carries the return-value burden, and it does so by naming the main payload sections. For a single-resource read with full schema coverage and clear annotations, nothing critical is missing, though a note on missing/deleted incidents would be a bonus.

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

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

Schema description coverage is 100%, with both incident_id and statuspage_id fully documented (including the connection-default behavior for statuspage_id), so the baseline is 3. The description adds no parameter-level detail beyond the schema, which is acceptable given the schema does the work.

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

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

States a specific verb and resource ('One incident in full') and enumerates the payload scope: components, containers, infrastructure affected, and all messages. The 'all its messages' phrasing implicitly separates it from statusio_get_incident_message and the list tools, though it never names them outright.

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 by the tool name and the incident_id parameter description ('from statusio_list_incidents or the active/resolved lists'), which is enough to infer the list-then-fetch flow. There is no explicit statement of when to prefer this over get_incident_message or the list variants.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the concrete GET endpoint and the shape of the returned fields, which is mildly useful, but says nothing about permissions, error behavior, or message ordering.

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

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

Two tight sentences with the returned fields front-loaded and no filler. The trailing endpoint string is slightly redundant with the schema but still compact.

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 enumerates what a message contains. An agent has enough to call it correctly; only cross-tool routing guidance is missing.

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

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

Schema description coverage is 100% and both parameters are documented there, including the default behavior of statuspage_id. The endpoint path in the description mirrors the parameter names but adds no new semantics, 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 (get) and resource (one incident message/update) and enumerates the returned fields (text, state, status, time, poster), so it is distinguishable from statusio_get_incident and statusio_get_maintenance_message. It does not explicitly name the siblings it differs from, but the resource scope is unambiguous.

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

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

Usage is only implied: an agent can infer this retrieves a single message rather than the parent incident, but the description never states when to prefer it over statusio_get_incident or statusio_list_incidents, nor any prerequisites.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the response includes all messages and affected infrastructure, which is useful, but says nothing about pagination, auth scope, or error 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?

Two sentences, zero filler, with the response-scope statement front-loaded before the raw endpoint. 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?

There is no output schema, so the description usefully compensates by naming what comes back (messages, affected infrastructure). For a two-parameter read-only getter with full schema coverage and annotations, that is close to complete; only the id-source hint is already covered elsewhere.

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% – both statuspage_id (with its default) and maintenance_id (with its source tools) are fully documented in the schema. The description adds no syntax or format 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 (get one maintenance event) and adds scope detail: 'in full, with all messages and the infrastructure affected.' This implicitly separates it from statusio_list_maintenance (plural) and statusio_get_maintenance_message (single message), but no sibling is named explicitly, 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?

The description implies the use case (retrieve a single maintenance event by id) but never states when to use this versus statusio_list_maintenance or statusio_get_maintenance_message. No prerequisites, no exclusions, no alternatives named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint path, confirming a pure read, but says nothing about pagination, error cases, or what a message object contains.

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 with no filler, and the resource identity is front-loaded before the endpoint. The first sentence is a fragment rather than a full statement, which is the only mild structural weakness.

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 fetch with 100% schema coverage, the description is minimally sufficient, but with no output schema it could hint at what a maintenance message contains (status, body, timestamps) or how it relates to the parent maintenance event.

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%: message_id is documented as coming from statusio_get_maintenance and statuspage_id explains the connection default. The description adds no parameter meaning beyond the schema, 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 pairs a specific resource ('one message of a maintenance event') with the underlying REST endpoint, so the agent knows this retrieves a single message rather than a list. It doesn't explicitly name the sibling it contrasts with (statusio_list_maintenance or statusio_get_maintenance), which keeps it 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?

There is no when-to-use guidance: nothing says this is for drilling into a single message after listing maintenance events via statusio_get_maintenance or statusio_list_maintenance_ids. No exclusions or alternatives are offered; the agent must infer usage from the name alone.

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 destructiveHint=false, so safety is covered structurally. The description adds real operational context beyond that: this is an aggregate snapshot that collapses several sibling list calls into one, and it enumerates the freshness signal ('last update') the agent will receive.

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 returned content is front-loaded in the first sentence, followed by a short directive and the raw endpoint. Efficient and scannable, though the REST path line is mildly redundant for an agent that already has the tool binding.

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

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

No output schema exists, so the description carries the burden of describing return values, and it does so thoroughly (overall status, components, containers, incidents, maintenance windows). For a zero-required-parameter read tool, nothing needed to invoke or interpret it 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 100% schema description coverage and a single optional parameter whose default is documented in the schema, the baseline is 3. The description's endpoint line echoes the '{statuspage_id}' placeholder but adds no format, constraint, or default behavior 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 ('current state of the status page') and enumerates the exact payload: overall status, components/containers with status codes and last update, open incidents, active/upcoming maintenance. The 'in one call' framing distinguishes it from the granular siblings ('list_components', 'list_active_incidents', 'list_maintenance') without opening their schemas.

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

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

'Start here' is an explicit entry-point recommendation, which tells the agent to call this before the per-resource list tools. It stops short of explicitly naming the alternatives or stating exclusions, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the payload contents (messages and affected components) and the underlying endpoint GET /incident/list/active/{statuspage_id}, which helps an agent reason about external data. It does not mention pagination or rate limits, 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?

Two compact sentences that are front-loaded with the scope qualifier and then the endpoint; every clause carries information and 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?

For a read-only list tool with no output schema, the description usefully names the returned content (messages, affected components) and the pagination caveat lives in the schema. Nothing critical is missing, though it could note that an empty page ends iteration.

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% – both page and statuspage_id carry full descriptions including the no-totals/paginate-until-empty behavior – so the schema does the heavy lifting. The description adds nothing about parameters beyond restating the id in the URL path, which is the baseline 3 case.

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 (active incidents) and scopes it as 'Active (unresolved)', which implicitly separates it from statusio_list_incidents and statusio_list_resolved_incidents. It does not name those siblings explicitly, so the differentiation requires the agent to infer it from the scope word.

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: 'Active (unresolved)' tells the agent this is the right tool when it wants open incidents, but there is no explicit when-to-use statement, no mention of the resolved/complete alternatives, and no prerequisites such as required page_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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses that the response contains ids and that these ids take a specific '<component_id>-<container_id>' composite form, which the annotations cannot convey.

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

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

A single dense sentence that front-loads the action and result, then explains downstream use and ends with the endpoint. 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 usefully compensates by describing what is returned (components plus attached containers with ids) and how those ids are consumed downstream. It omits pagination or result-size behavior, but for a single-optional-param read tool this is close to complete.

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

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

Schema coverage is 100% and the single statuspage_id parameter is already fully documented (including its regex and the connection-default behavior). The description adds no syntax or format detail beyond the schema, 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 (List) and resource (components and the containers attached to each), plus the exact endpoint GET /component/list/{statuspage_id}. It clearly distinguishes itself from the incident/maintenance/subscriber listing siblings, so an agent knows exactly what comes back.

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 tells the agent why it would call this: component and container ids are prerequisites for update_component_status and for describing what an incident affects. It even gives the composite id format. It stops short of naming an alternative tool or a when-not-to-use case, so it is not 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=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds one genuinely useful behavioral fact — the response contains ids only, no detail payload — but says nothing about pagination, ordering, or result size for a potentially large collection.

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

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

One tight sentence with the scope ('ids only, no details') front-loaded, followed by the next-step pointer and the endpoint. Little waste, though the raw endpoint path is of marginal value to an agent that already has the schema.

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

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

For a simple read-only list tool with full schema coverage and annotations covering safety, the description covers purpose, output shape, and the follow-up call. The main omission is whether results span all status pages or just the connected default, and whether the list is paginated.

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

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

Schema description coverage is 100% for the single statuspage_id parameter, so the schema already carries the meaning and the default behavior. The description only echoes the parameter indirectly via the endpoint path 'GET /incidents/{statuspage_id}', adding nothing new.

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 ('The ids of all active and resolved incidents') and clarifies scope with 'ids only, no details'. It implies a superset relationship with the narrower siblings statusio_list_active_incidents/statusio_list_resolved_incidents, but never names them, so the distinction requires inference.

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 context ('a quick way to see which incidents exist') and routes the agent to statusio_get_incident when full details are needed. It stops short of stating when to prefer this over the active-only or resolved-only list siblings, so there is no explicit exclusion.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds two genuinely useful behavioral facts: results include messages and affected components, and the underlying endpoint shape. It omits pagination behavior, which the schema happens to document instead.

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 scope in one tight sentence, followed by the endpoint path. Efficient, but the state definitions are redundant with the schema and consume space that could have carried sibling routing.

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

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

With no output schema, the description usefully discloses what a result contains (maintenance event, messages, affected components), and annotations cover safety. What remains unspecified is response sizing/pagination and error behavior, which is a modest gap for a 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?

Schema description coverage is 100%, so page, state, and statuspage_id are already fully documented by the schema, including the paging-until-empty convention. The description only restates the enum meanings, adding no syntax or defaulting detail beyond what the schema provides, 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?

Names the resource (maintenance events), the scoping dimension (one state, with the three states enumerated), and the payload content (messages and affected components), which implicitly separates it from get_maintenance (single item) and list_maintenance_ids (ids only). It never names a sibling explicitly, so it lands at 4 rather than 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?

Usage is implied by the state breakdown, but there is no explicit when-to-use guidance or 'use X instead' routing against the many sibling list/get tools. The state glosses ('pending = scheduled and not started') duplicate the enum description in the schema verbatim, so they add no routing information.

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 destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond them: the returned payload is ids only, the states included (active, closed, upcoming), and the underlying endpoint GET /maintenances/{statuspage_id}.

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, well front-loaded sentences with no filler; the scoping detail and the follow-up tool are both stated economically.

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

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

With no output schema, the description compensates by stating the return is ids only and which maintenance states are covered. A minor gap remains around ordering or volume of ids, but an agent has enough to call and use it correctly.

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

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

Schema description coverage is 100% for the single statuspage_id parameter, including its default behavior, so the schema already carries the semantics. The description adds nothing about the parameter, making the baseline 3 appropriate here.

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

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

States a specific verb and resource ('ids of all active, closed and upcoming maintenance events') and clarifies the scope with '(ids only)', which distinguishes it from the fuller statusio_list_maintenance. It also flags the sibling used to fetch a single record, though it never explicitly contrasts itself with statusio_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?

Gives clear routing guidance: use this to enumerate ids, then 'Fetch one with statusio_get_maintenance'. There is no explicit when-not-to-use clause or direct comparison against the other list siblings, so it stops short of full alternative coverage.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context by naming the response contents (messages and affected components), but says nothing about ordering, volume, or pagination behaviour beyond what the schema already documents.

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, front-loaded with what the tool returns. The trailing REST endpoint (GET /incident/list/resolved/{statuspage_id}) is minor filler for an agent that never calls the API directly, but nothing else is padded.

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

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

With no output schema, the description usefully covers what comes back (messages and affected components), and pagination nuances live in the schema. For a simple read-only list of two optional parameters, this is close to sufficient; only incident ordering/limits remain 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% and both parameters are documented there, including the paging-until-empty convention and the default status page id. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Resolved incidents (history)') and enriches it with the returned payload ('their messages and affected components'), which cleanly separates it from the active-incident siblings. It does not, however, name an alternative tool explicitly, so an agent still has to infer the routing from the adjective 'resolved'.

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: reading the list implies you want historical/resolved incidents rather than active ones. There is no when-to-use statement, no when-not, and no named alternative (e.g. statusio_list_active_incidents or statusio_list_incidents), leaving the agent to infer the choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely non-obvious behavior: the payload is subscriber personal data and webhook URLs are deliberately truncated to their host because they can carry secrets. It also names the underlying GET endpoint, though it omits pagination or volume characteristics.

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

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

Three tight sentences, front-loaded with what the tool returns, then the data-sensitivity caveat, then the endpoint. No filler or restatement of the title.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does name the entity types and fields returned. It stops short of detailing the shape of the preference objects or pagination, leaving a small gap for an agent that needs to parse results.

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

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

Schema coverage is 100% and the single statuspage_id parameter is fully documented in the schema, including its pattern and the default to the connected page. The description adds nothing beyond that, 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 ('List') and resource ('subscribers to the status page') and enumerates exactly what comes back: email addresses, phone numbers, webhook hosts, ids, and granular preferences. No sibling tool covers subscriber data, so the scope is unambiguous.

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

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

Usage is implied by the description of the returned subscriber data, but there is no explicit statement of when to call this versus other tools or any prerequisite (e.g., admin scope required to read personal data). The caution about personal data hints at intended care but not at usage conditions.

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

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

Annotations cover the safety profile (readOnly=false, destructive=true, idempotent=true), but the description adds real value beyond them: the state transitions (components to operational, incident to history), the HTTP endpoint, and critically that no notification fires unless a notify_* flag is enabled. It doesn't clarify what happens to in-flight notifications or the effect of incident_id on a history record.

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?

Short and front-loaded: the 'WRITE:' marker and the core action come first, followed by side effects and the notification caveat. The trailing 'POST /incident/resolve' is largely redundant with the schema, but overall the text is 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 destructive mutation tool with no output schema, the critical behavioral facts (state changes, notification defaults) are present and correct. Missing only auth/permission expectations and confirmation of idempotency behavior, which the annotations already hint at.

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 11 parameters are already documented by the schema, and the description adds little parameter-specific detail. It does generalize the notify_* flags ('switch it on') and references the closing message, which maps to details, but adds no new syntax or semantic nuance.

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 ('resolve an incident') and immediately clarifies the terminal outcome: components return to operational and the incident moves to history. This implicitly separates it from statusio_update_incident, but no sibling is named, so it stops short of explicit differentiation.

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 verb: call this to close out an incident. There is no explicit when-to-use vs. statusio_update_incident or statusio_finish_maintenance guidance, and no stated prerequisites, so an agent must infer the 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?

Adds substantial context beyond the annotations: public visibility to visitors, subscriber notification gating on the four notify flags (all default off), the effect of automation=true, and the return value (maintenance id). The 'WRITE' framing is consistent with readOnlyHint=false and destructiveHint=true, so there is 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 tight sentences with the write scope front-loaded, followed by visibility, notification gating, automation, and return value. No filler and every sentence carries an operational fact.

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 15-parameter mutation tool with no output schema, the description covers the key unknowns: what becomes publicly visible, when subscribers are contacted, how automation governs lifecycle, and what the call returns. Remaining details are fully covered by the schema and annotations.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by emphasizing that subscribers are only told when a notify switch is enabled and that all notify flags default off, plus clarifying the self-managing behavior of automation. It does not add format details for start/end, which the schema already covers.

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 ('WRITE: schedule a planned maintenance on the PUBLIC status page') and names the endpoint POST /maintenance/schedule. This cleanly separates it from start_maintenance, finish_maintenance, and update_maintenance among its siblings.

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

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

Gives clear context: it is for planned/upcoming maintenance, visible publicly, with subscriber notification only via explicit notify flags. It does not explicitly say when to prefer start_maintenance or finish_maintenance instead, so the routing to alternatives is implied 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?

Goes well beyond the annotations by disclosing that the message becomes public immediately, that notifications are opt-in via notify_* flags, and that affected components display planned maintenance. It does not address reversibility or behavior when the maintenance is not pending, which are relevant for a destructiveHint=true operation.

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

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

One dense sentence with the WRITE marker and endpoint up front, then the key state change and the notification caveat. No filler; 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?

For an 11-parameter mutation with no output schema, the description covers the critical semantics: state transition, immediate public visibility, and opt-in notifications. Annotations already carry the safety profile, so the remaining gaps (error conditions, default status page resolution) are minor.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds meaning by grouping the notify_* booleans as the notification opt-in switch and noting the message is published regardless. It does not clarify statuspage_id's default or message_subject usage beyond the schema text.

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

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

States a specific verb (start), resource (scheduled maintenance), and the exact state transition (pending to active), including the visible effect on components. This clearly separates it from finish_maintenance, schedule_maintenance, and update_maintenance siblings.

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

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

The phrase 'start a scheduled maintenance now' makes the precondition clear (a pending/scheduled maintenance must already exist), which routes the agent away from schedule_maintenance. It stops short of naming siblings or stating what to do if the maintenance is not in pending state.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=true, so the safety profile is covered. The description adds real behavioral context beyond that: the change is public and visible to visitors immediately, and it does not create an incident. It omits auth requirements or rate limits, so not a 5.

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

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

Front-loads the WRITE marker, then purpose, immediate-visibility impact, revert guidance, id source, and endpoint in a tight sequence. Every sentence earns its place with no filler.

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

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

No output schema exists, but for a public-facing status write the description covers what changes, who sees it, reversibility, where ids come from, and the underlying call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds operational value by pointing to statusio_list_components as the id source and giving a concrete status example (degraded_performance), which the schema alone does not supply.

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 (the PUBLIC status of one component/container pair), and explicitly distinguishes itself from statusio_create_incident with 'without creating an incident'. An agent can tell exactly what this does and how it differs from the incident-creation sibling without opening a schema.

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

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

Explains the selecting condition clearly ('without creating an incident') and routes the agent to statusio_list_components for ids, plus gives lifecycle guidance ('Set it back to operational when done'). It stops short of naming the alternative tool (statusio_create_incident) explicitly, but the intent is unambiguous.

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

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

Adds meaningful context beyond annotations: the update message becomes public immediately, and subscriber/channel notifications are off by default unless notify_* flags are set. Annotations already declare the destructive, non-idempotent, open-world write profile, so this additional notification behavior is valuable but not exhaustive.

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

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

Four tight sentences, front-loaded with 'WRITE:' to signal the operation type. The public immediacy, notification default, alternative tool, and endpoint are all stated 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?

Covers purpose, key side effects, notification defaults, and the primary alternative for closing incidents. With no output schema, it need not explain return values. It could mention what happens to existing incident state or component statuses in more detail, but it is largely complete for a mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters including enum meanings and notify_* defaults. The description reinforces the notify_* behavior but does not add syntax, format, or constraint details beyond what the schema provides, matching the baseline for high coverage.

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 a new update message on an existing incident and set its state and component status.' It also names the sibling tool for closing incidents, so an agent can distinguish this from statusio_resolve_incident without opening either schema.

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

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

Explicitly routes the agent away from this tool for closing incidents ('To close an incident use statusio_resolve_incident'). It provides clear context for posting updates, but does not compare against other mutation siblings like statusio_create_incident or statusio_update_component_status.

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

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

Annotations already declare a non-read-only, destructive, non-idempotent write with open-world effects. The description adds genuinely new behavioral facts beyond those hints: the message goes public immediately and no notifications fire unless the notify_* flags are enabled.

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, front-loaded sentences with zero filler: the WRITE framing, the public/notification semantics, and the endpoint. 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?

For an 11-parameter mutation with no output schema, the description covers the safety-relevant behaviors an agent needs (immediate public visibility, opt-in notifications). It is only slightly thin on which maintenance states are eligible and whether the update can be reversed.

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 every parameter including the notify_* booleans is already documented in the schema. The description reinforces the notify_* default-off behavior but adds no syntax or format detail beyond what the schema provides, 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 ('post a new status message on an active maintenance event') and even names the endpoint. It is clearly distinguishable from sibling mutations like schedule_maintenance, start_maintenance, finish_maintenance, and update_incident.

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 implies the precondition that the maintenance event must be 'active' and explains the notify switch behavior, but it never explicitly says when to choose this tool over start_maintenance, finish_maintenance, or schedule_maintenance, nor does it state any exclusion.

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