statuscake

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

Annotations only declare destructiveHint=true, so the description carries most of the burden: it explains the failure semantics (check goes down when no ping arrives within period), discloses the returned identifier (data.new_id), and routes to the tool that exposes the ping URL. It does not cover auth/permission requirements or what happens to pings before the check is live.

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 plus the endpoint note, all front-loaded: purpose, failure condition, return value, and follow-up tool. 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?

With no output schema, the description usefully documents the return field (data.new_id) and the next step to get the ping URL, which is essential for actually using a heartbeat check. Remaining gaps (auth needs, initial ping state) are minor for a straightforward create call.

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

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

Schema description coverage is 100%, so every parameter is already documented (period range, empty-list clearing for tags/contact_groups). The description reinforces the meaning of `period` in the failure lifecycle but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a heartbeat (push) check') and immediately scopes it to cron jobs/workers, which cleanly separates it from the sibling create tools for uptime/SSL checks. The mechanism (down if StatusCake is not pinged within `period` seconds) makes the resource 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?

Explains the use case (monitoring a cron job or worker) and prescribes the follow-up step: fetch with statuscake_get_heartbeat_check to obtain the ping URL. It does not explicitly say when to prefer this over statuscake_create_uptime_check, but the cron/push framing implies the boundary well.

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 (destructiveHint=true) by disclosing that only date/time are used from the RFC3339 values and that they are interpreted as local time in `timezone`, plus the account-feature gate. It omits auth requirements and success behaviour (e.g. what is returned), but the timestamp handling is a genuinely non-obvious trait.

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

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

Four dense sentences, front-loaded with the action and the silencing effect, then constraints, then endpoint. 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 7-parameter mutation with no output schema, it covers the operation, the required-input rule, timezone semantics, and the account gate. It does not say what a successful call yields (window id?) or how errors surface, a minor gap given no output schema is declared.

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 would be 3; the description earns extra by supplying cross-parameter semantics the schema cannot express ('at least one of tests or tags') and by clarifying the interplay between start_at/end_at and timezone.

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 ('Schedule a maintenance window') plus the effect on the system ('silences alerts for the given uptime checks'). The resource is distinct from every sibling create_* tool, so an agent can route to 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?

Gives real preconditions: at least one of tests or tags required, and it only works on accounts with the newer maintenance-windows feature. It does not name alternatives (e.g. update/get maintenance window) or say when-not-to-use, 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?

Beyond the annotations, the description discloses the return contract ('Returns the new id as data.new_id') and the underlying API call ('StatusCake: POST /ssl'), which is genuinely useful for a create tool with no output schema. It does not address permission requirements, duplicate-URL behavior, or the meaning of destructiveHint=true for a creation operation, so it is not fully complete.

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

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

Three short sentences with zero filler: purpose first, return value second, API endpoint third. Nothing is repeated from structured fields and nothing is missing that belongs here.

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

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

For a 12-parameter mutation tool, the schema carries all parameter detail and the description supplies the return shape in lieu of an output schema, which is a good division of labor. The remaining gap is usage/prerequisite context and the unexplained destructive annotation.

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

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

Schema description coverage is 100%, so every one of the 12 parameters is already documented in the schema, including enum values, the exactly-three alert_at constraint, and the https:// pattern. The description adds no parameter detail, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Start monitoring a site's SSL certificate') and scopes the concern to 'expiry and problems', which separates it from statuscake_create_uptime_check. It does not, however, explicitly name or contrast a sibling, so it stops 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 explicit guidance on when to choose this over create_uptime_check or create_heartbeat_check, nor any stated prerequisites (e.g. contact groups must exist first). Usage is only implied by the tool name and the SSL wording.

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 no output schema, the description usefully discloses that the new check's id is returned as data.new_id, and it warns that faster check rates and certain regions are plan-gated. The destructiveHint=true annotation is not contradicted (the description makes no read-only claim), though it does not explain any auth or permission requirements either.

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

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

Three short sentences, front-loaded with the purpose and information-dense; the return-value hint and plan caveat both earn their place. The trailing "StatusCake: POST /uptime." is minor trivia but not harmful.

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 29-parameter creation tool it covers the essentials that structured data does not: the return value (no output schema exists) and plan-dependency caveats. It stops short of auth/prerequisite context and any guidance on the many optional parameters, so it is adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents all 29 parameters thoroughly. The description only alludes to check_rate and regions via the plan caveat, adding marginal meaning beyond the schema. Baseline 3 is appropriate when the schema carries the load.

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

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

The description opens with a concrete verb and resource ("Start monitoring a URL, host or IP"), which maps directly to creating an uptime check and clearly separates it from the heartbeat/SSL create siblings. What it lacks is an explicit call-out of those siblings, so an agent must infer the boundary from the tool name rather than the text.

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 statement of when to choose this tool over create_ssl_check, create_heartbeat_check, or create_maintenance_window, and no preconditions or exclusions. Usage is only implied by the word "monitoring," which is weak given four sibling creation tools.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by enumerating what is returned (ping URL, period, status, last ping), though it omits error behavior for a missing/invalid test_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?

One economical sentence followed by the API endpoint reference; the resource and scope are 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 and a trivial single-parameter input, the description does the needed work by summarizing the returned fields. A note on lookup failures would make it fully complete, but nothing essential is missing.

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

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

Schema coverage is 100% and the single test_id parameter is fully documented in the schema, so the baseline is 3. The REST fragment 'GET /heartbeat/{test_id}' reinforces that test_id is a path identifier but adds no meaning 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 (Fetch) and resource (one heartbeat check) with explicit scope ('one') that cleanly separates it from statuscake_list_heartbeat_checks in the sibling set. 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?

Usage is implied by 'one' versus the sibling list tool, but the description never explicitly states when to use this versus list_heartbeat_checks or what condition selects a single-check fetch. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying API mapping (GET /maintenance-windows/{window_id}), which is useful context, but says nothing about not-found behavior, error semantics, or what the response 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 short, front-loaded sentences with zero filler: the purpose comes first and the API endpoint second. Nothing is wasted.

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

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

For a one-parameter read tool whose annotations cover safety and which has no output schema, the definition supplies enough to invoke correctly. Return-shape expectations are the only real omission, and the description need not document them.

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 window_id parameter, so the schema already carries the semantics. The description adds only that the id selects one window, matching the baseline 3 when the schema does the heavy lifting.

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

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

The description gives a specific verb ("Fetch") and resource ("one maintenance window") and scopes it to a single item by id, which implicitly distinguishes it from the sibling list_maintenance_windows. It stops short of naming the alternative tool outright, so it is clear but not fully sibling-differentiated.

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 lookup to use when it already holds a window_id and needs the record rather than a listing. There is no explicit statement of when to prefer this over statuscake_list_maintenance_windows or of any prerequisite.

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), so the bar is lower; the description adds genuine value by describing the returned metrics and the endpoint, telling the agent what data it will get back. It does not discuss ordering or page size, though the schema covers limits.

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

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

A single front-loaded sentence naming the resource and payload, followed by a compact API mapping. No filler or redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields, and parameter semantics are fully covered by the schema. It is nearly complete, lacking only a note on pagination/ordering behavior.

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

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

Schema description coverage is 100%, so test_id, after, before and limit are already documented in the schema. The description adds no extra syntax or usage nuance 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?

It states a specific verb and resource ('Past runs of one pagespeed check') and enumerates the returned metrics (load time, file size, request count, throttling, HAR location), which clearly distinguishes it from statuscake_list_pagespeed_checks and statuscake_get_uptime_history.

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 scope ('one pagespeed check') but the description never states when to prefer this over sibling history/list tools or any prerequisites. No explicit when/when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description usefully adds which data fields the response contains, but says nothing about permissions, rate limits, or error behavior when test_id is invalid.

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 return content front-loaded and the underlying API endpoint appended as a compact reference. 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?

With no output schema, the description compensates by listing the returned fields, and the single required param is fully documented. Slightly incomplete on error/permission behavior, but adequate for a simple read.

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

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

Only one parameter (test_id) and schema coverage is 100%, with the schema describing it as 'The SSL check id.' The description adds no format, source, or acquisition guidance for the id, 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 (Fetch) and resource (one SSL certificate check) with scope ('in full'), and enumerates what is retrieved (expiry, issuer, cipher, scores, flags, mixed-content resources). This clearly distinguishes it from statuscake_list_ssl_checks and statuscake_create_ssl_check.

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 word 'one' plus 'in full' implies this is for a specific check rather than a listing, but no sibling is named and no when-to-use/when-not guidance is given. The agent must infer the list-vs-get split from the tool 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, so the safety profile is covered. The description adds useful behavioral context by disclosing the scope of the response (settings, current status, last test time, next location, monitoring servers) and the underlying StatusCake endpoint. No auth or rate-limit notes, but nothing contradicts 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 with zero padding; the resource and the returned-field summary are front-loaded, and the endpoint is a brief trailing reference.

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

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

For a single-parameter getter with no output schema, the description compensates well by listing the returned fields so the agent knows what to expect. Only minor gaps remain, such as error/not-found behavior.

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

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

There is one parameter with 100% schema description coverage, so the schema already documents test_id fully. The description adds no syntax, format, or constraint detail beyond what the schema provides, making the baseline 3 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 ('Fetch one uptime check') and enumerates what the payload contains, which implicitly separates it from the list and history siblings. It stops short of naming those siblings explicitly, so an agent must infer the singular-vs-plural 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?

The word 'one' and the full-detail framing imply this is the single-record lookup versus statuscake_list_uptime_checks and statuscake_get_uptime_history, but the description never states when to prefer it or what it excludes. Usage is left to inference.

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

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

With readOnlyHint=true already covering safety, the description adds real behavioral context: results are ordered newest first, pagination works via links.next or the before parameter, and each run carries location, status code, and response time in ms. It also discloses the underlying REST endpoint (GET /uptime/{test_id}/history), which helps an agent understand the data shape.

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: the first establishes what a row contains and the sort order, the second covers pagination and cites the backing endpoint. Nothing is redundant or buried.

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, and the description compensates by enumerating the returned fields (when, location, status code, response time). Combined with the paging explanation, an agent has enough to call and interpret the result, though error or empty-history behavior is unaddressed.

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

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

Schema description coverage is 100%, so after/before/limit/test_id are already documented. The description reinforces the before/links.next paging relationship but adds no syntax or format detail beyond what the schema states; 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 ('Individual test runs for one uptime check') plus the exact fields returned (location, status code, response time). This implicitly separates it from aggregate siblings like statuscake_get_uptime_periods, but it never names an alternative to make the distinction explicit.

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 through the paging instruction ('follow links.next (or pass before) to page back'). There is no guidance on when to reach for this tool versus statuscake_get_uptime_check or statuscake_get_uptime_periods, nor any stated preconditions.

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 supply readOnlyHint=true, so the description usefully adds what actually comes back (per-period start/end timestamps and duration in ms) — valuable since there is no output schema. It omits pagination behavior, though the schema's 'before'/links.next note partially covers that.

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: what it returns, the intent it answers, and the backing API endpoint. 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?

For a read-only, single-resource query tool with full schema coverage, the description supplies the return shape it would otherwise lack. Only paging guidance is absent, and that is already implied by the 'before' parameter description.

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% — after, before, limit and test_id are all documented with types, ranges and defaults in the schema. The description adds no parameter-level information, 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 ('the up and down periods of one uptime check') and names the returned facts — start, end, duration in ms — which distinguishes it from siblings like statuscake_get_uptime_history or statuscake_list_uptime_alerts without opening a schema.

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

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

The line 'the direct answer to how long was it down?' gives a clear intent-based routing cue for when this tool is the right pick. It stops short of naming an explicit alternative (e.g. uptime_history for aggregate percentages) or a when-not-to-use condition, so it does not reach 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, non-mutating read, and the description adds a useful mapping to the underlying GET /contact-groups endpoint plus the returned field set. It does not disclose pagination behavior or list size/rate considerations, which is the remaining gap.

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-loaded with purpose followed by returned content and the API mapping. No filler sentences and nothing repeated from 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?

With no output schema, the description compensates well by enumerating the fields a contact group carries, so the agent knows what comes back. Only pagination/total-count behavior for a paged list is left unaddressed.

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

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

Schema description coverage is 100% — page and limit are fully documented inline with ranges and default. The description adds no parameter detail, so the baseline of 3 for schema-driven params is correct.

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

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

States a specific verb (list) and resource (contact groups), then immediately defines what a contact group actually is — alert destinations with emails, mobile numbers, integration ids, and ping URL. No sibling tool covers contact groups, so the distinction from the get_/list_ check tools 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?

Tells the agent the downstream purpose: the returned ids are meant to be plugged into a check's contact_groups field, which effectively tells you when to call this. It stops short of naming an alternative tool or stating exclusions, but for a leaf list endpoint there is no meaningful alternative to route against.

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 adds value by disclosing what each record carries (status, period, ping URL) — useful given there is no output schema — but says nothing about pagination behavior or uptime-skip side effects.

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

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

A single well-formed sentence with the resource and concept front-loaded, plus a compact API hint ('StatusCake: GET /heartbeat'). No filler; the parenthetical definition earns its place, though the trailing endpoint reference is marginally 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?

For a read-only, zero-required-parameter list tool with 100% schema coverage and no output schema, the description is nearly sufficient: it names the resource, the concept, and the fields returned. It could add a note on pagination/result size to be fully complete.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters (page, tags, limit, status, matchany, nouptime). The description mentions none of them, so per the rubric the baseline 3 applies — the schema carries the full parameter burden.

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

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

States a specific verb+resource ('List heartbeat (push) checks'), defines the concept ('jobs that must ping a StatusCake URL within a period'), and enumerates returned fields (status, period, ping URL). It is trivially distinguishable from the single-check sibling statuscake_get_heartbeat_check and from statuscake_list_uptime_checks by resource.

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 'List' — an agent can infer it returns all heartbeat checks. However, no when-to-use/when-not guidance or alternative routing (e.g. 'use get_heartbeat_check for a single check') is provided, leaving scope inference to the caller.

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

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

The readOnlyHint annotation already establishes this is a safe read. Beyond that, the description adds genuinely non-obvious context: the account-level feature requirement that gates whether the call succeeds, and the shape of what is returned. It omits pagination behavior despite exposing page/limit parameters.

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 tightly packed sentences, front-loaded with the action and return payload, with the applicability caveat and the underlying API path trailing. No filler or redundancy.

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

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

For a read-only listing with fully documented parameters and annotations covering safety, the description is nearly sufficient – it tells the agent what a window contains and the account prerequisite. The only mild gap is the absence of any note on pagination or result volume, which matters for a list 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?

Schema description coverage is 100%, so all three parameters (page, limit, state) are already documented, including the default and the enum. The description adds no syntax or filtering nuance 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?

Names a specific verb+resource ('List maintenance windows') and immediately clarifies the domain concept as 'scheduled alert silences', then enumerates the fields returned (start/end, timezone, repeat interval, state, covered checks/tags). This clearly distinguishes it from the singular statuscake_get_maintenance_window and the create/update 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?

Provides an explicit applicability precondition ('Only works on accounts using the newer maintenance-windows feature'), which tells the agent when this tool will fail. It does not, however, route the agent to alternatives (e.g., get_maintenance_window for a single window by ID), so it stops short of full when-to-use 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, so the safe-read profile is covered. The description adds worthwhile disclosure about what each record contains (location, alert thresholds, load time, page size, request count, latest issue), but says nothing about pagination behavior, defaults, or rate limits for this collection endpoint.

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 tightly written sentence front-loads the verb and resource, followed by a compact API mapping line. No filler, no redundancy, and the return-field list is the most valuable content.

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 carries the return-shape burden and does describe the payload fields adequately for an agent to know what it gets back. Pagination and result-size expectations are left to the schema, a minor gap rather than a blocking one.

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 (page, limit) are fully documented in the schema including ranges and the default of 25. The description adds no parameter meaning 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 (List) and resource (pagespeed checks), and enumerates the returned fields (location, alert thresholds, latest stats), which clearly distinguishes it from sibling list tools for uptime, SSL, heartbeat and maintenance windows. It stops short of naming an alternative like get_pagespeed_history, 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?

There is no when-to-use statement, no prerequisite, and no routing to alternatives; an agent must infer from the resource name that this is the inventory call and get_pagespeed_history is the per-check one. The pagination intent of the parameters is only visible in the schema, not the description.

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, non-mutating read. The description adds the useful detail that results are reference data (region, IPs, status) and maps to the underlying endpoint, but says nothing about rate limits, pagination, or whether the endpoint requires auth or a paid plan.

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 delivering purpose plus return fields, followed by a short endpoint mapping. The 'StatusCake: GET /pagespeed-locations' line is traceability rather than agent-facing guidance, but it costs little.

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 parameterless-in-practice read tool with readOnlyHint set, a fully documented single param, and no output schema, the description covers what the agent needs. Only the absence of sibling routing guidance (uptime vs pagespeed locations) 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 coverage is 100%, with the single 'location' parameter fully documented in the schema including ISO 3166-1 alpha-2 format and an example. The description adds no parameter detail, so the baseline 3 applies since the schema already 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 ('List') and resource ('pagespeed monitoring servers') and even enumerates the returned fields (region, IPs, status), so the agent knows exactly what comes back. The 'pagespeed' qualifier implicitly separates it from statuscake_list_uptime_locations, but the sibling is never named.

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 supports choosing a region/location for pagespeed checks. There is no statement of when to use this versus statuscake_list_uptime_locations, nor any prerequisite (e.g. auth) or 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?

readOnlyHint=true already declares the safe-read profile, so the description carries a lighter burden. It adds real value by disclosing the return payload contents (issuer, cipher, score, expired/broken/revoked/mixed-content flags) and the backing endpoint, but says nothing about pagination or result ordering 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 compact sentences with zero filler: the resource and its returned fields come first, the API mapping trails as a reference. 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 enumerates the fields returned, and the annotations cover safety, so an agent has enough to call it correctly. The only shortfall is lack of any pagination guidance despite page/limit params.

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 only page and limit, both fully documented in the schema. The description adds no meaning beyond the schema (no default/cap reminders or interaction between pagination params), so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('List SSL certificate checks') and immediately differentiates it from the singular get_ssl_check sibling by describing the collection and its per-item payload (validity window, issuer, cipher, score, status flags). An agent can tell what it returns without opening any schema.

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

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

Usage is only implied by the verb 'List' — nothing states when to prefer it over statuscake_get_ssl_check for a single check, nor any condition or prerequisite. No exclusions or alternatives are named, leaving routing to inference.

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

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

readOnlyHint=true already establishes this as a safe read, so the description need not restate safety. It adds the useful content of the returned alerts (timestamp, changed-to status, status code) but says nothing about pagination behavior, defaults, or rate limits beyond what the schema implies.

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 front-loads the resource scope, and the appended API mapping (GET /uptime/{test_id}/alerts) is compact and useful for disambiguation. 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 full schema coverage and no output schema, the description covers the operation and even sketches the return fields. Some pagination nuance is only in the schema, but nothing critical to a correct call 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 all four parameters already carry their own descriptions (after/before windows, limit, test_id). The description adds no syntax or value-format detail beyond the schema, making the baseline 3 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 resource (alerts) scoped to one uptime check, plus what each alert carries (when, target status, status code). It is clearly distinct from siblings like list_uptime_checks or get_uptime_check, though it never names a sibling explicitly.

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

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

No when-to-use guidance, no prerequisites, and no alternatives are mentioned. The requirement to supply test_id is implied only by the phrase 'one uptime check' and the endpoint template, leaving the agent to infer selection criteria from the schema.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds which fields come back, which is useful context, but says nothing about pagination behaviour or that nouptime trades uptime accuracy for speed on large accounts — both of which the schema only gestures at.

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 no padding: what it lists, what can be filtered, and the underlying endpoint. The trailing 'StatusCake: GET /uptime' is marginally useful API context rather than filler.

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

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

For a read-only list tool with no output schema, the description usefully enumerates the returned fields and the two filter dimensions, and annotations cover the safety profile. Remaining gaps (pagination semantics, when to prefer a sibling tool) 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 every one of the six parameters is already documented in the schema; baseline 3 applies. The description restates the status and tags filters but adds no syntax or interaction detail (e.g. tags+matchany interplay) beyond the schema.

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

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

Specific verb+resource ('List uptime checks') plus an enumeration of the fields returned (status, type, URL, check rate, tags, uptime percentage), which lets an agent distinguish it from statuscake_list_ssl_checks / list_heartbeat_checks / list_pagespeed_checks. It does not explicitly contrast with get_uptime_check or list_uptime_alerts, so no sibling routing is spelled out.

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

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

The description says 'Filter by status or tags,' implying the supported use, but gives no when-to-use/when-not guidance and names no alternative tool (e.g. get_uptime_check for a single check, list_uptime_alerts for alerts). Usage is inferable but not stated.

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

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

The readOnlyHint annotation already establishes this is a safe read, but the description adds real value beyond it: the exact fields returned, the practical firewall-allowlist use case, and the underlying API mapping (GET /uptime-locations). It does not discuss pagination or result size, but for a static reference list that is minor.

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 tightly packed sentences plus a short API identifier. The purpose and return fields are front-loaded, and every clause (field list, region-code usage, IP usage, endpoint) carries distinct information with no filler.

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

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

For a no-required-param listing tool with readOnlyHint and no output schema, the description is largely self-sufficient: it names the return fields and the two main consumption use cases. It leaves minor gaps around result ordering/volume, but nothing essential for correct invocation 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 on a single optional region_code parameter, the schema already documents the filter fully. The description reinforces the concept of region codes but adds no syntax or filtering 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?

The description gives a specific verb ('List') and resource ('StatusCake's uptime monitoring servers') and even enumerates the returned fields (region, region code, IPv4/IPv6, status). It is clearly distinct from the similarly named statuscake_list_pagespeed_locations, but it never explicitly names or contrasts a sibling tool.

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

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

It gives concrete application context — use region codes in a check's regions, use the IPs for firewall allowlists — which tells the agent why it would call this and what to do with the result. It stops short of stating when-not-to-use or naming an alternative location 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 flag destructiveHint=true; the description adds the critical behavioral detail an agent needs — list fields (tags, contact_groups, regions, dns_ips) are REPLACED rather than merged, and an empty list clears them, which is exactly the destructive data-loss scenario. This is meaningful context well beyond the annotation.

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

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

Three compact sentences, front-loaded with the mutation contract and the destructive caveat before the pause/resume helper and endpoint reference. 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 29-parameter destructive mutation with no output schema and full schema coverage, the description supplies the missing cross-field semantics well. It omits anything about permissions/auth or error behavior, but those are not essential to calling it correctly.

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

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

Schema coverage is 100%, so per-parameter descriptions already carry most semantics (baseline 3). The description adds cross-cutting meaning the schema cannot express: that omitted fields are untouched and that list parameters overwrite rather than append — non-obvious behavior for 29 parameters.

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

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

States a specific verb and resource ('Change an uptime check's settings') and even names the underlying endpoint (PUT /uptime/{test_id}). It is immediately distinguishable from the create/get/list siblings by the update semantics conveyed.

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 partial-update contract (only passed fields change) and gives a concrete use case for paused (true=pause, false=resume), which tells the agent how to invoke it. It stops short of naming when NOT to use it or pointing to alternatives among the many sibling tools.

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