updown-io

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

Adds substantial context beyond the destructiveHint annotation: it is idempotent ('new (or already-existing) recipient'), it mutates existing checks by default via the selection side-effect, and it requires the read/write API key. This explains why destructiveHint=true on a seemingly additive operation. Minor gaps remain (no rate-limit or duplicate-handling detail).

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

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

Dense but front-loaded: purpose first, then return value, then the important default side-effect, then prerequisites and auth. Every sentence carries distinct, non-redundant information.

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

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

For a mutation tool with no output schema, the description covers auth requirements, the selection side-effect, idempotent return behavior, and an external prerequisite. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so all four parameters are already documented with types, enums, and defaults. The description reinforces the type list and the selected=false behavior but adds no syntax or format detail beyond what the schema already supplies; 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 ('Add an alert recipient') and enumerates the exact accepted recipient kinds (email, sms, webhook, slack_compatible, msteams). An agent can distinguish this from updown_list_recipients 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?

Provides clear context: the default is to attach the recipient to ALL existing checks, pass selected=false to leave it unattached, and Slack/Telegram/Zapier/Statuspage integrations must be pre-configured in the web UI. It does not explicitly name sibling alternatives (e.g. use list_recipients to view), so it stops short of full when/when-not 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?

Goes beyond the sparse annotations (only destructiveHint=true) by disclosing that each check consumes updown credits while enabled and that the read/write API key is required — practical operational context an agent cannot infer from the schema. It omits what the response returns, but the credit/consumption and auth disclosures are genuinely useful.

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 compact sentences, front-loaded with purpose and the type-inference rule, then auth/credit constraints. The trailing API breadcrumb ('updown: POST /api/checks') is slightly extraneous but not disruptive.

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

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

For a 14-parameter create tool with no required params, the description covers the key decision logic (type vs URL, pulse mode) and side effects (credits, auth). The notable gap is not describing what is returned (e.g., the new check id) when no output schema exists, which an agent would need for follow-up calls.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema only partially conveys: that type is inferred from the URL scheme and that 'pulse' requires omitting the URL entirely. This clarifies the relationship between url and type rather than just restating field docs.

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

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

States a specific verb and resource ('Add a new monitoring check') and immediately covers the two primary modes of creation: URL-derived type inference and the URL-less 'pulse' cron/heartbeat case. It is clearly distinguishable from siblings like updown_update_check, updown_get_check, and updown_list_checks.

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 conditional guidance — pass type 'pulse' with no URL for heartbeat checks, otherwise let the type be inferred from the URL scheme — and states the read/write API key requirement. It does not explicitly contrast with updown_update_check or note limits on check count, but the creation context is well established.

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

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

Annotations only provide destructiveHint=true, so the description usefully adds that the operation requires the read/write API key and that it returns the new page's token and URL. It does not contradict the annotation. It still omits side effects such as whether creating a page affects existing checks or quota, 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?

Three tight sentences that front-load the action, follow with the return value, auth requirement, and endpoint tag. No filler, though the raw 'POST /api/status_pages' endpoint string adds little for an agent.

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

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

With no output schema, the description correctly compensates by naming the returned values (token and URL), and it covers the auth requirement. All five parameters are fully documented in the schema, so the remaining gap is only the absence of when-to-use and side-effect context.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the checks ordering and access_key default. The description's 'showing the given checks, in order' merely echoes what the schema says, adding no new syntax or constraint detail. 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 ('Create a status page') plus the scoping detail that the checks appear in order, which distinguishes it from updown_update_status_page and updown_list_status_pages. It does not explicitly name siblings, but the create-vs-update-vs-list split 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?

Use is implied by 'Create a status page' and the auth note, but there is no explicit when-to-use guidance, no statement of when to prefer update_status_page instead, and no mention of prerequisites such as needing existing check tokens from updown_list_checks. Adequate but with clear gaps.

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

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

readOnlyHint=true already establishes it is a safe read, so the description's job is lighter. It adds real behavioral context beyond the annotations: the four problem categories it aggregates, the 'since when' detail on downtime, and that it is derived from GET /api/checks. It does not describe result shape or pagination, but for an aggregate reader that is a minor omission.

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

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

A single dense sentence, front-loaded with the 'One-call health overview' hook, followed by the enumerated problem categories. Every clause earns its place and nothing is padded.

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

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

No output schema exists, so the description must convey the returned content, and it effectively enumerates the problem categories an agent will receive. Combined with only two optional, fully-documented params and a readOnly annotation, this is nearly complete; it only lacks return-format specifics.

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

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

Schema coverage is 100%, so both parameters (ssl_days, domain_days) including their defaults and bounds are already documented in the schema. The description mentions 'expire within N days' conceptually but adds no syntax, units, or default details beyond what the schema provides. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource (health overview across every check) and enumerates exactly what it surfaces: DOWN checks with since-when/error, invalid SSL, certificate/domain expiry, paused/muted checks. This clearly differentiates it from siblings like updown_list_checks or updown_get_check, which return raw check data rather than a problem-focused summary.

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 'one-call health overview' framing implies when to reach for this aggregate rather than iterating per-check tools. However, it never names an explicit alternative (e.g. list_checks) or states a when-not condition, so the routing guidance is clear but not fully spelled out.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that metrics and results are optional enrichments, but that detail largely duplicates the schema and it says nothing about response size, rate limits, or failure modes for an invalid token.

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

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

Front-loaded with the core action in a single tight sentence; the trailing 'updown: GET /api/checks/:token' endpoint mapping is mildly redundant but cheap and confirmatory rather than wasteful.

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

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

For a small read-only tool with full schema coverage and one required param, the description covers the action, the scoping key, and the optional enrichments. Since there is no output schema, a hint about the returned shape would be the only missing piece.

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's mention of 'last hour of performance metrics' and 'last 5 requests' matches the schema text for metrics/results without adding syntax or format detail beyond it.

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

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

States a specific verb (Fetch) and resource (a single check) scoped to one token, which clearly distinguishes it from updown_list_checks (plural listing) and updown_get_check_metrics (metrics-only sibling). An agent can identify the operation 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?

No explicit guidance on when to use this versus updown_list_checks, updown_get_check_metrics, or the other get/update siblings, and no prerequisites stated. Usage is only weakly implied by 'by token'.

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

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

With only readOnlyHint available, the description carries the real behavioral load: it discloses data granularity (hourly, daily after 2 days, monthly after 40 days), the minimum range constraint, and the non-obvious rule that uptime is omitted when grouping. These are genuinely useful facts not derivable from the annotations or schema.

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

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

Return contents are front-loaded, followed by the grouping option, then the granularity/constraint caveats. Every sentence adds distinct information with no repetition.

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

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

No output schema exists, but the description enumerates the response fields and their granularity, covers the grouping caveat, and states the range precondition. An agent has everything needed to call and interpret the result correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning: it clarifies the group enum ('time' vs 'host', with host glossed as monitoring location) and that grouping suppresses uptime. It does not re-explain token/from/to formats, but the schema already does that well.

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 aggregated metrics for one check') and enumerates exactly what is returned: uptime, apdex, timings, request counts. This clearly distinguishes it from sibling updown_get_check, which returns check config rather than metrics.

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

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

Gives the operating context (over a time range, optionally grouped) and the hard precondition that the range must span at least one hour. It does not explicitly route the agent between this and updown_get_check/find_problems, so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds a genuinely useful behavioral detail beyond the annotation: filtering happens client-side, so the full check set is always fetched. No pagination or rate-limit behavior is mentioned, keeping it below a 5.

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

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

Front-loaded with the core action and returned fields, then the filtering caveat. Mostly tight, though the trailing 'updown: GET /api/checks.' is a minor API-reference fragment that does not aid tool selection.

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 enumerating the key returned fields (down, uptime, last_status, error, period, SSL, domain expiry), which is sufficient for a simple list tool. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it clarifies that both filters are applied client-side rather than server-side. That is a semantic detail not present in the parameter descriptions.

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+resource ('List all monitoring checks on the account') and enumerates the returned fields (status, period, SSL, domain expiry). It is clearly distinct from mutation siblings, but it never explicitly contrasts itself with updown_get_check or updown_find_problems, so an agent must infer the list-vs-single distinction.

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 notes that filtering by status or text is optional and done client-side, which implies usage, but there is no statement of when to prefer this over updown_get_check, updown_find_problems, or updown_list_downtimes. Usage is implied rather than guided.

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

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

readOnlyHint=true already marks this as a safe read. The description goes beyond the annotation by disclosing return ordering (newest first), pagination size (100 per page), the returned fields, and the underlying API endpoint, though it says nothing about authentication requirements.

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 compact sentence plus the endpoint reference; the resource, ordering, pagination, and payload fields are all front-loaded with zero 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?

With no output schema, the description usefully enumerates the returned fields and pagination behavior. Only minor gaps remain, such as auth requirements and how the optional results parameter expands the payload (the schema does note it can be large).

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 parameters are fully documented in the schema itself. The description only restates page size and ordering; it adds no syntax or format detail beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb and resource ('List the downtimes of one check') plus ordering and page size. It is the only downtime-oriented tool among its siblings, so an agent can select it without ambiguity.

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

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

Usage is implied rather than stated: the token example points at updown_list_checks as the source of the input, which implies the call flow. There is no explicit when-to-use/when-not guidance or reference to an alternative tool.

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

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

Annotations only carry readOnlyHint=true, so the description usefully adds that the endpoint is public and requires no API key — a real operational fact an agent needs. It does not cover rate limits or the shape of the response, 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?

Three tight clauses: what it returns, why you'd want it, and the parameter choice — all front-loaded with zero filler. The endpoint mapping is compact supporting detail, not padding.

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

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

For a single optional-enum read tool with no output schema and no nested objects, the description covers purpose, auth requirements, use case, and parameter selection. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% including the enum and default, so the baseline is 3. The description adds value by mapping each choice to a distinct upstream endpoint (/api/nodes/ips, /ipv4, /ipv6), clarifying that family changes the resource fetched rather than just filtering.

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 updown.io's server IP addresses') with the concrete entity being returned, plus the upstream API route. This is clearly distinguishable from sibling list tools like updown_list_nodes or updown_list_checks.

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

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

Gives a concrete motivating scenario ('to allowlist the monitors in a firewall') and tells the agent how to select the family argument. It does not name an alternative tool or an explicit when-not-to-use condition, but no sibling overlaps enough to require one.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the no-API-key/public access requirement and the underlying endpoint (GET /api/nodes), though it says nothing about rate limits or response size.

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 front-loads the resource and returned fields, followed by a short access note and endpoint mapping. Every clause carries information; nothing is redundant.

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

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

With no parameters and no output schema, the description fully carries the burden and does so: it names the returned attributes (IPv4, IPv6, city, country, coordinates), the keying scheme, and the public access model. Nothing an agent needs to call 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?

Zero parameters, so there is no schema surface for the description to compensate for; baseline 4 applies. It sensibly lists the location codes that key the returned data, giving semantic context for interpreting results.

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 (updown.io's monitoring/webhook servers), and enumerates the return fields and location-code keying, which distinguishes it from updown_list_node_ips and the other list_* siblings without opening a schema.

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

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

It notes the endpoint is public and needs no API key, which is useful operational context, but gives no explicit when-to-use versus when-not or a pointer to the closely related updown_list_node_ips. Usage must be inferred from the enumerated fields.

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

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

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It contributes the underlying API call (GET /api/recipients) and the id format returned, but says nothing about pagination, result size, or authorization — modest incremental value over the annotations.

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

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

Two compact sentences, front-loaded with the resource and scope, then the id explanation, then the endpoint reference. No filler or repetition.

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

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

For a zero-parameter read-only tool with no output schema, the description conveys what entity is listed and the key identifier shape the caller will need. It stops short of describing the result envelope or whether results are paginated, which 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description's mention of id syntax describes return data rather than inputs, and no input semantics are needed 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?

The description gives a clear verb+resource ('List the alert recipients/channels on the account') and enumerates the channel types (email, sms, slack, telegram, webhook, zapier), which makes the returned entity concrete. It does not explicitly differentiate itself from the sibling updown_add_recipient, but the list-vs-add distinction is obvious from the name and verb.

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

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

Usage is only implied: the note that the `id` (e.g. email:3719031852) 'is what check `recipients` take' hints this is the step you run before creating/updating a check's recipients. There is no explicit when-to-use, when-not-to-use, or named alternative among the 13 siblings.

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower; the description goes further by disclosing the returned shape (token, public URL, name, description, visibility, ordered check tokens), which is valuable because no output schema exists. It omits pagination, ordering and authorization scope details, preventing 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?

One front-loaded sentence carrying the resource and the return contract, plus a short API reference. No filler, no restatement of the title.

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

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

For a no-parameter read tool with no output schema, the enumerated return fields supply most of what an agent needs, and annotations carry the safety profile. Remaining gaps are pagination/response volume, which are minor for this endpoint.

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 per the rubric the baseline is 4; there is no argument surface the description needs to explain. Nothing here adds or detracts from that baseline.

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

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

States a specific verb (List) and resource (the account's status pages), and enumerates the returned fields, so it is unmistakable against sibling list tools like updown_list_checks or updown_list_recipients. The trailing API mapping (GET /api/status_pages) removes any remaining ambiguity.

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

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

Usage is only implied: an agent can infer this is the way to enumerate status pages, but the description gives no explicit when-to-use guidance and names no alternative (e.g., updown_update_status_page for mutations, or when a per-page lookup would be preferred). Adequate for a trivial read-only list, but no routing help.

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

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

Annotations only carry destructiveHint=true, so the description does the heavy lifting: it discloses partial-update/merge semantics, the read/write auth requirement, and a concrete destructive hazard (re-sending a read-only-key URL erases hidden basic-auth credentials). That is precisely the kind of beyond-annotation context an agent needs before mutating state.

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

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

Front-loaded with the core action and field list, then the merge rule, the caution, and finally the auth/endpoint. Every clause carries information, though the credential caveat and API-key sentence could be tightened slightly.

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

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

For a 14-parameter mutation tool with thin annotations and no output schema, it covers the essentials: scope, merge behavior, auth, and a data-loss warning. Return-value/pagination detail is unnecessary here since no output schema exists, leaving only minor gaps.

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

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

Schema coverage is 100%, so the schema baseline is 3, but the description adds real meaning by mapping fields to intents (enabled = pause/resume, mute_until = mute alerts) and summarizing the category of settings covered. It does not add syntax detail beyond the schema, so it lands just above 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?

Specific verb plus resource ('Change a check's settings') with an enumerated list of updatable fields and the distinct pause/resume and mute sub-actions. It is immediately separable from updown_create_check, updown_get_check, and updown_list_checks.

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

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

Gives the key operating rule ('Only the fields you pass are changed') and states the credential requirement ('Requires the read/write API key'), which is exactly the gate an agent needs before calling. It stops short of naming alternatives such as updown_get_check for read-only inspection, so it is clear context without explicit 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 only declare destructiveHint=true; the description earns credit by specifying the destructive mechanism ('replaces the list, order respected') and the auth prerequisite (read/write API key). It stops short of describing failure modes or whether omitted fields revert to defaults.

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

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

Three tight sentences with the mutation scope front-loaded and no filler. The trailing API endpoint reference is mildly extraneous but harmless.

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

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

With no output schema and six fully documented parameters, the description covers auth, partial-update semantics, and the destructive checks replacement, which is enough for correct invocation. Only the response shape and error behavior remain unstated, and those are secondary here.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by stating that the checks list is order-sensitive and fully replacing, and by confirming the partial-update contract for all fields. That is genuine added semantics over the field-level descriptions.

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 (status page), then enumerates exactly which fields are mutable (checks, name, description, visibility, access key). This distinguishes it from updown_create_status_page and from updown_update_check, whose resource is a check rather than a page.

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

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

The description clarifies patch semantics ('Only the fields you pass are changed') and the auth requirement, which is useful context, but it never names when to reach for this over create_status_page or which fields warrant which call. Usage is implied rather than directed.

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