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

Beyond the annotations, the description discloses important side effects and defaults: the new check notifies every integration unless channels says otherwise, and setting unique may UPDATE an existing check. It also explains the rationale behind the channels default, which is genuinely useful for an agent invoking this tool.

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

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

Four focused sentences with no filler. The core action is front-loaded, followed immediately by the most important constraint, then the default behavior and the key side-effect. Every sentence 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?

Given 19 parameters, full schema coverage, and an output schema, the description covers the critical decisions an agent must make: which scheduling parameter to provide, what happens with channels, and when an update may occur instead of a create. It is complete enough for correct selection and 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?

Although the schema already documents all 19 parameters (100% coverage), the description adds cross-parameter semantics not visible in the schema: timeout and schedule are mutually exclusive, channels defaults to '*', and unique changes the call from create to upsert. This is high-value clarification beyond the property-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?

The description states a clear verb and resource ('Creates a check') and immediately adds distinguishing behavioral detail: the upsert behavior via 'unique' can UPDATE an existing check, which sets it apart from the sibling update_check. It is not merely repeating the title.

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

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

The description gives explicit operational guidance: pass either timeout or schedule, never both; channels defaults to '*'; and unique triggers an upsert. It does not explicitly name sibling alternatives like update_check for plain modifications, so it stops just short of full alternative routing.

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

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

Beyond the annotations, the description discloses critical behavioral traits: permanence, non-recoverable UUID, downstream script breakage, and the two-step confirmation-token workflow. These are valuable details not derivable from readOnlyHint, destructiveHint, or idempotentHint alone. No contradiction with annotations exists.

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

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

Three sentences, front-loaded with the core action, followed by consequence and workflow. Every sentence earns its place; there is no filler or repetition 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 destructive two-step tool, the description covers the action, the irreversibility, the impact on scripts, and the required calling sequence. With annotations and an output schema present, nothing essential is missing for an agent to use it safely.

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

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

Schema coverage is 100% and both parameters are well-described, so the baseline is 3. The description adds meaningful workflow context by explaining how check and confirm_token relate across the two calls, elevating it slightly above the schema alone.

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

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

The description states a specific verb and resource: 'Deletes a check permanently.' It distinguishes this from sibling tools like pause_check or update_check by emphasizing permanence and the irreversible consequence of breaking deployed scripts. The purpose is immediately clear.

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

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

The description implies usage when permanent deletion is intended and explains the required two-step flow. However, it never explicitly contrasts with pause_check or resume_check, so an agent could overuse this destructive tool when a temporary pause would be more appropriate.

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 this tool as read-only and idempotent, and the description aligns with those hints. It adds valuable behavioral context beyond the annotations by explaining what the tool actually reports and how the result affects the usability and identifier conventions of sibling tools.

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

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

The description is a single, dense sentence that front-loads the core purpose and then adds the most useful implications of the result. Every clause earns its place; there is no repetition, filler, or irrelevant detail.

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 configuration query tool with an output schema available, the description is fully complete. It tells an agent what the tool reports, why that matters, and how the result should shape subsequent tool selection and parameter formatting.

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

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

The tool has zero parameters, and the schema covers all of them trivially at 100%. With no parameters to document, the description's explanation of the output semantics is sufficient and adds meaning beyond the empty input schema.

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

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

The description clearly states a specific verb ('Reports') and resource ('API key info'), and details exactly what is reported: configured instance, key validity, and key permissions. It also distinguishes this diagnostic tool from its data-manipulation siblings by explaining that its output governs how other tools can be used.

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

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

The description clearly implies when to use this tool: before calling list_pings, get_ping_body, or list_integrations, and to determine the correct identifier format for checks. It provides strong contextual guidance, though it does not explicitly state a when-not-to-use condition or name an alternative diagnostic 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 already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context by specifying the accepted identifier forms (UUID or unique_key from read-only API keys) and the scope of returned fields, which goes beyond the structured 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 sentences with no filler. The action and resource scope are front-loaded, and the identifier clarification is placed second without redundant phrasing. Every sentence earns its place.

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

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

For a simple read operation with one parameter, an output schema, and safety annotations, the description covers the essential decision points: what is fetched and which identifier forms are accepted. Nothing material is missing for an agent to invoke it correctly.

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

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

The schema description coverage is 100%, so the input schema already documents the single parameter. The description repeats the identifier guidance found in the schema, adding no new parameter-specific semantics beyond what the schema provides. The baseline of 3 applies.

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

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

The description states a specific verb ('Fetches') and a specific resource ('one check'), and clarifies scope by noting the response includes all fields, descriptions, and keyword filters. The singular 'one check' distinguishes it from list_checks and other siblings without needing to open schemas.

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

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

The description implies usage for retrieving a single check, but it does not explicitly name alternatives like list_checks for multiple checks or update_check for modifications. An agent can infer when to use this tool from the phrase 'one check,' but the guidance is implicit rather than explicit.

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?

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds substantial behavioral disclosure: 64 KB truncation, the unusual read-write key requirement for a read-only operation, the misleading 401 message, and why a read-only key can never produce a valid UUID argument. This goes well beyond what the annotations provide.

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

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

The first sentence is front-loaded and immediately useful. The description is longer than average, but the extra length is mostly high-signal: truncation, key requirements, error semantics, and troubleshooting guidance. The second paragraph is slightly repetitive in reinforcing the read-only limitation, but it does clarify a genuinely confusing failure mode.

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

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

Given that an output schema exists and annotations cover the safety profile, the description is complete for correct invocation. It explains truncation, the key prerequisite, how to check the key type, why the UUID argument may be unobtainable, and where related list_checks/get_api_key_info tools fit. There is no critical missing behavioral or contextual detail.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds meaningful extra semantics for the 'check' parameter by explaining that read-only keys never see UUIDs and that list_checks returns a different identifier, which directly affects correct invocation. The 'n' parameter is already well covered by the schema's reference to list_pings.

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

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

The description states a specific verb and resource: it 'returns the body that was POSTed with one ping' and explicitly frames it as the fastest way to see why a check failed. This clearly distinguishes it from siblings like list_pings, which return lists of pings, and get_check, which returns check configuration.

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

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

The description gives explicit when-to-use context ('fastest way to see why a check failed'), tells the user to call get_api_key_info when unsure about key type, and explains when the tool cannot be used at all ('with a read-only key this endpoint is out of reach'). This is actionable routing guidance rather than vague context.

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 indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it is an unauthenticated reachability/database check against the configured instance, which is helpful for selecting it as a first diagnostic step. No contradiction observed.

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

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

Two sentences, front-loaded with the tool's job and followed by the key usage/auth fact. Every sentence earns its place with no repetition of the schema or annotations.

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

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

For a 0-parameter status check with an output schema and robust readOnly/idempotent annotations, the description fully covers what an agent needs: what is checked, auth expectations, and when to use it. Nothing significant is missing.

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

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

There are zero parameters, so the baseline is 4. The description reinforces that no API key or arguments are required, which removes any temptation to supply credentials or filters. There is nothing else to document.

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

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

The description states a specific verb ('checks') and a clear resource: the configured Healthchecks instance's reachability and database responsiveness. It distinguishes itself from siblings by noting no API key is required, so an agent can recognize this as the connectivity/status probe rather than a data or mutation 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 explicitly gives the usage context: 'try first when something is not working' and notes no API key is needed. It does not name specific sibling alternatives or exclusion cases, but the guidance is clear enough for a 0-parameter status 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?

Beyond the annotations' readOnly and idempotent hints, the description explains meaningful output behavior: entries are per tag plus '*', and the plain versus '3'-suffixed variants differ in how grace periods and check states are reported. This is precise behavioral context that the annotations do not provide.

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 written sentences deliver the core purpose and the key variants without any filler. The main action and resource are front-loaded, and the additional details about variants are valuable.

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, read-only, idempotent tool with an output schema present, the description fully covers what an agent needs to know: what is listed, how entries are structured, and how different badge variants behave. 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?

The tool has zero parameters, so there are no parameter semantics to convey. Baseline 4 is appropriate for a parameterless tool, and the description correctly focuses on output semantics instead.

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

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

The description begins with a specific verb and resource: 'Lists the status badge URLs of the project.' It immediately clarifies the unique output scope (one entry per tag plus '*' for the whole project), which distinguishes it from sibling tools that manage checks or pings.

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

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

The description implies when to use the tool (when badge URLs are needed) by describing the exact nature of the badges, but it does not explicitly mention alternatives or state when not to use it. Sibling tools like list_checks are related but not addressed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context: newest-state-first ordering, project-scoped results due to API key scoping, and omission of descriptions. It does not describe pagination, but output schema and parameter docs cover most remaining details.

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, no filler, and the most important behavior is front-loaded. The final sentence earns its place by preventing a likely misuse (expecting descriptions) and pointing to the correct sibling.

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

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

For a simple list operation with all parameters optional and fully documented, plus a rich output schema, the description covers scope, ordering, and the key alternative. Nothing necessary for correct tool selection or 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?

Schema description coverage is 100%, so the parameter meaning is fully documented in the schema itself. The description adds little about the parameters, which is acceptable because the schema already carries that 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?

The description opens with a specific verb and resource: 'Lists the checks in the project the API key belongs to, newest state first.' It adds ordering and project-scope information, and distinguishes itself from get_check by noting that descriptions are omitted.

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

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

It clearly states what the tool returns and explicitly routes to get_check when descriptions are needed: 'Descriptions are omitted here — call get_check for one.' This gives the agent an explicit when-not-to-use signal and a named alternative.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond those: the instance retains only the current month and the two prior months, and either a UUID or unique_key may be used. This goes beyond what annotations provide.

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

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

Two sentences with no filler: the action is stated first, then scope/retention, then the accepted identifier format. Every sentence 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?

Given the annotations, output schema, and fully described input schema, the description provides enough orientation for a simple read-only history tool. The retention limit and identifier flexibility are useful additions. It could be stronger with explicit sibling guidance, but nothing critical is missing.

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

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

Schema coverage is 100%, so every parameter already has a description. The tool description restates the UUID/unique_key identifier behavior but adds little beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-documentation 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?

The description names a specific verb ('Lists') and a specific resource ('the up/down transitions of a check'), and clarifies that these are the history behind the current status. This clearly distinguishes it from siblings like list_pings or get_status even without naming them.

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

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

The intended use—viewing flip history for a check—is implied by the description, and the retention-window note ('current month and the two before it') gives practical context. However, it does not explicitly state when to choose this over list_pings or get_status, nor does it mention alternatives or 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?

Adding the auth-requirement quirk, the misleading 'wrong api key' message, and the recommendation to call get_api_key_info gives valuable behavior beyond the readOnlyHint/idempotentHint annotations. The transparency is weakened by the garbled statement about addressing a check by uuid and list_checks' unique_key behavior, which appears to misattribute sibling-tool behavior to this 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?

The first sentence is front-loaded and the auth warning is important, but the second paragraph is unnecessarily long and repetitive ('out of reach', 'nothing to pass', 'not a mistake to fix'). It could be cut to two or three tight sentences without losing value.

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 list operation with an output schema, the description covers purpose, creation path, auth prerequisite, failure mode, and remediation. It is nearly complete, but the confusing uuid/list_checks tangent reduces the agent's ability to trust and act on the guidance.

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

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

The tool has zero parameters and 100% schema coverage, so the 0-param baseline of 4 applies. The description adds useful context by explaining the UUIDs returned are what create_check and update_check accept in their channels argument, even though it does not discuss tool 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?

The first sentence clearly states the tool lists the project's notification integrations and ties the output to the channels argument of create_check and update_check. However, the later paragraph says 'this tool ... addresses a check by uuid' even though list_integrations has zero parameters, which muddles the otherwise clear purpose.

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 is explicit that a read-write API key is required, that read-only keys will fail with a misleading 401, and that get_api_key_info should be called to verify the key type. It also notes integrations cannot be created via the API. It does not clearly contrast with sibling list tools, and the uuid/list_checks aside introduces confusion about which tool the guidance applies to.

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

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

The description goes far beyond the annotations by revealing plan-based caps (100/1000), absence of pagination, the misleading HTTP 401 'wrong api key' error, and the UUID vs unique_key mismatch with read-only keys. These are behavioral traits not visible in annotations or schema, and they materially affect whether and how the tool can be called.

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

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

The description is front-loaded with the core behavior and caps, but the final paragraph repeats the read-only/UUID limitation already stated in the previous paragraph. The same point about 'read-only key cannot see a check UUID' appears twice, making it longer than necessary. Still, the structure flows from behavior to auth caveats to invocation details.

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 tool with this complexity, the description covers the essential invocation conditions, failure modes, plan limits, pagination absence, and recommended preflight via get_api_key_info. Since an output schema exists, return-value documentation is not needed. Nothing critical is missing for an agent to decide whether and how to call this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents the check UUID, the read-only key limitation, the type enum, and the limit default and bounds. The description adds operational context like plan caps and the unique_key issue, but these are more behavioral than parameter-specific, so the schema remains the primary source for parameter meaning.

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

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

The description opens with a specific verb and resource: 'Lists recent pings of a check, newest first.' This clearly identifies the tool's function and separates it from sibling tools like get_ping_body or list_flips. No ambiguity about what the tool does.

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

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

The description gives actionable guidance: it explains that a read-only key cannot be used, recommends calling get_api_key_info to verify key type, and clarifies that the endpoint is unreachable with a read-only key. It does not explicitly compare to sibling tools for listing pings, but the usage preconditions and fallback actions are clear.

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

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

The annotations already communicate mutability, idempotency, and non-destructiveness. The description adds meaningful behavioral context: pausing suppresses ping expectations and alerting, nothing is lost during the pause, and there is a risk that actual job failures go undetected. This goes beyond the structured annotations without contradicting them.

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

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

The description is two sentences long, front-loads the primary action and effects, and avoids redundancy. Every sentence contributes useful information: what pausing does, how to reverse it, and an important operational caveat.

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

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

For a single-parameter tool with an output schema and informative annotations, the description covers the action, effects, reversibility, and associated risk. The parameter schema handles input expectations, and the output schema handles return values. Nothing needed 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?

Schema description coverage is 100%, so the single parameter is already fully documented in the input schema. The description does not add additional parameter-level detail, which is acceptable given the schema already explains the check UUID and how to obtain 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?

The description opens with a specific verb and resource: 'Pauses a check,' then clarifies the exact effects: it stops expecting pings and stops alerting. It also distinguishes pause_check from resume_check and reassures that no state is lost, making the tool's purpose 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?

The description clearly connects pause_check to resume_check, establishing the core use case of temporarily pausing monitoring. It also warns that a stopped job will go unnoticed while paused, which guides appropriate usage. However, it does not explicitly state when not to use the tool versus other alternatives such as update_check or delete_check.

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?

It adds meaningful behavioral detail beyond the annotations: the state change to 'new', the waiting-for-next-ping effect, and the 409 failure condition. This complements the idempotentHint and destructiveHint annotations without contradicting them.

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

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

Two sentences with no filler. The core action is front-loaded, and the failure condition is stated immediately after, making efficient use of the description space.

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 state-transition tool with an output schema and annotations, the description covers the action, the resulting state, and the key error condition. Nothing essential 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% and the check parameter is already well documented, including the read-only key caveat. The description does not need to add parameter-level detail, so baseline 3 is appropriate.

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

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

The description uses a specific verb-resource pair ('resumes a paused check') and clearly defines the state transition to 'new'. It is immediately distinguishable from sibling tools like pause_check and update_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 description makes the precondition explicit by stating it fails with HTTP 409 if the check is not paused, which effectively tells the agent when not to use it. It does not name alternative tools explicitly, but the context strongly implies its role relative to pause_check.

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

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

Annotations already mark the tool as non-readOnly, idempotent, and destructive, so the bar is lower. The description adds valuable behavioral context beyond those annotations: partial-update semantics, channels replacing the integration list rather than merging, and schedule taking precedence over timeout. It also discloses the UUID/read-only key limitation. The 'destructiveHint: true' is consistent with the replace-not-merge and schedule-switch behavior described. Minor gap: it doesn't explicitly state whether the update is irreversible or what happens to downstream pings, but the description is honest and substantial.

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

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

Three sentences, each earning its place: the first states the core behavior and partial-update default, the second flags the two counterintuitive exceptions, the third warns about UUID visibility for read-only keys. Information-dense with zero filler and the most important caveats front-loaded.

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

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

Given 19 parameters, a 100%-covered schema, an output schema, and annotations covering read-only/destructive/idempotence, the description covers the gaps that structured data cannot: partial-update semantics, replace-vs-merge, schedule-vs-timeout precedence, and the UUID/read-only-key constraint. It does not spell out that an empty payload is pointless or that channels with an empty list is refused, but the schema's required 'check' field and the channels description already handle those. Very complete for the tool's complexity.

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 19 parameters thoroughly with ranges, patterns, and mutual exclusions. The description adds cross-cutting semantics that the schema can't: the partial-update default ('Fields that are not given stay unchanged') and the two exceptions (channels replaces, schedule overrides timeout). That is genuinely useful but the heavy lifting is done by the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Updates a check' with a specific verb and resource, and immediately clarifies partial-update semantics ('Fields that are not given stay unchanged'). It doesn't explicitly differentiate from sibling tools like create_check, pause_check, or resume_check, but the name and verb make the core purpose 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?

The description gives implicit but clear usage context: it is a partial update operation, and it flags the two non-obvious behavioral exceptions (channels replaces rather than merges; schedule overrides timeout) that an agent must know before calling. It does not explicitly say 'use create_check to create a new check' or 'use pause_check to pause', but the exceptions serve as important when-to-call guidance for this tool versus alternatives. A slightly explicit alternative comparison would push this to 5.

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