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

The description explicitly discloses that the operation publishes to subscribers and notifies people, which is a side effect that annotations do not capture. It also flags the need for prior approval ('get the wording approved first'). This goes well beyond the basic readOnly/destructive hints.

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 deliver the core action, the scope requirement, and the critical side-effect warning. It is front-loaded with the most important information and contains 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?

The tool has no output schema and moderate complexity, but the description covers the action, the publish side effect, the state transition, and the approval caveat. It could mention whether the incident must already be declared or what the response contains, but the most critical calling context is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context about the 'state' parameter by explaining it moves lifecycle state (e.g., to 'resolved') and that the message is 'shown to visitors.' It also hints that idempotencyKey prevents duplicate publishing, which adds value beyond the schema text.

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

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

States an explicit verb (append), the resource (an incident's timeline), and the side effect (moving the incident state). It is also distinct from sibling 'comment_incident' because it names the timeline and state transition, making the tool's role 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?

Gives a direct scope requirement ('statuspage:write') and warns that this publishes and notifies subscribers, which guides when to use it and when to pause. It does not name alternative tools or explicit when-not-to-use conditions, but the context is strong enough to infer appropriate use.

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?

Despite annotations indicating destructiveHint=true, the description goes far beyond by specifying authorization source, scope enforcement, absolute refusal for /account writes, and the precise confirmed=true retry workflow for DELETE and non-validate bulk writes. This gives the agent concrete behavioral expectations and safety constraints.

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 dense sentences cover purpose, prerequisite, authorization, safety policy, and the confirmation retry workflow. Every clause carries operational weight; there is no filler, and the most important scoping constraint is 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?

For a generic REST fallback with no output schema, the description is remarkably complete. It covers discovery (describe_api), auth, scope limits, hard refusals, destructive-operation confirmation, and the validation dry-run exception. Response format is unspecified, but that is acceptable for arbitrary operations and would be impossible to summarize usefully.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description adds extra meaning by explaining the confirmed parameter's safety role, the requirement that method/path match a real operation from describe_api, and the idempotency key context implied by the bulk/incident doors. This is above the baseline three.

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: 'Call any HostTracker v2 REST operation that no curated tool covers.' This clearly distinguishes it from the many curated siblings and defines its catch-all role. It leaves 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 explicitly states when to use the tool ('no curated tool covers' the operation) and prescribes a mandatory prerequisite: 'Look the operation up with describe_api first.' It also gives exclusion rules ('Writes under /account are refused outright') and a confirmation workflow for destructive operations, leaving no guesswork.

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 say this is not read-only or destructive, so the description carries the burden of explaining behavior. It fully discloses the validation-first flow, the conditional submit behavior, and that the submitted job is polled via get_job, which is beyond the annotation information.

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 with no filler; the purpose is front-loaded and the workflow is stated compactly. Every sentence adds necessary operational information.

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

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

For a tool with no output schema and async behavior, the description covers the main prerequisites: scope, validation-first call, submit flag, and polling with get_job. It could specify the shape of the validation report or job ID, but the essential calling sequence is complete.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the role of submit in the two-phase workflow and that itemsJson is a batch of monitor definitions. It does not discuss defaultsJson or idempotencyKey, but those are already well-covered by schema 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 specific action and resource ('Create many monitors in one asynchronous job') and distinguishes this from single-create and other bulk operations by emphasizing 'many' and 'asynchronous'. It is immediately clear what the tool does and how it differs from siblings like create_monitor.

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 a clear context for use: many monitors, asynchronous job, and a two-step workflow (validate with submit=false, then submit=true). It does not explicitly name alternatives or say 'use create_monitor for single monitors', but 'many' and the polling instruction make the intended usage unambiguous.

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

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

Beyond the destructiveHint and idempotentHint annotations, the description adds materially valuable behavior: the tool runs as an asynchronous job, validation-only mode when expectedCount is absent, rejection if the selection drifted, and the required 'monitor:write' scope. These details meaningfully shape how the agent should invoke and explain the 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?

Three dense sentences cover purpose, safety workflow, submission requirements, and scope without redundancy. The most important information is front-loaded: destructive action first, then the exact validation/submission protocol. No sentence is wasted.

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

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

The description handles the complex two-phase destructive workflow well and covers auth scope. Since there is no output schema, it could have briefly described what the tool returns (e.g., the validation count or job identifier), but the phrase 'the validation reported' implies the response includes the matched count, and the async-job framing is enough for safe 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?

The input schema already covers all four parameters at 100%, so the baseline is 3. The description adds real semantic value by explaining the relationship between confirmed and expectedCount, the validation-only behavior when expectedCount is null, and the API's drift-refusal rule. This goes beyond simple field 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 opens with a specific verb and resource: 'Delete every monitor a filter selects, as an asynchronous job.' This clearly distinguishes it from singular delete_monitor and from bulk_create_monitors/bulk_update_monitors. The filter-based bulk scope is explicit and immediately understandable.

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 a precise two-phase workflow: call without expectedCount to validate, then submit with both confirmed=true and the reported expectedCount. It also warns to show the validation count and get explicit approval. It does not explicitly compare to delete_monitor or state when not to use the bulk variant, but the filter/async framing makes the intended use 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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds meaningful behavior beyond them: the operation is asynchronous, submit defaults to false producing a dry-run count/sample, and it requires 'monitor:write' scope. No contradiction with annotations; the description actually clarifies the non-read-only nature of the 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?

Three short sentences, each earning its place: core purpose, auth scope, and the dry-run workflow. The purpose is front-loaded and there is 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?

For an asynchronous bulk mutation with no output schema, the description covers the critical workflow (dry-run first, then submit). It does not state what the async invocation returns (e.g., a job ID to track with wait_for_job), which is a notable gap given the async design and the existence of job-management siblings.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks — it explains the consequence of submit=false (count and sample returned) and the recommended dry-run-then-submit flow. It does not clarify the relationship between operation and patchJson, but the schema already documents each parameter well.

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

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

The description states a specific verb and resource — 'Apply one patch to every monitor a filter selects' — and clarifies the asynchronous job mechanism. It clearly differentiates from sibling bulk tools (bulk_delete_monitors, bulk_create_monitors) by describing the patch semantics and filter-based selection, so an agent can pick it correctly 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?

It gives clear workflow context: without submit=true the call returns only a count and sample, and it directly instructs the agent to show that to the user before actually submitting. However, it does not explicitly contrast with alternatives like update_monitor for single-monitor edits, so when-not 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?

The description explicitly warns that 'items already processed are NOT rolled back', which is a critical behavioral caveat beyond what the annotations convey. It further advises confirming with the user and reading the receipt to assess partial effects. This is valuable transparency for a mutation-like tool with potential 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?

The description is two efficient sentences with no filler. The first sentence states the action and scope; the second delivers the essential warning and recommended follow-up. Important caveats are front-loaded and easy for an agent to parse.

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?

This is a low-complexity tool with one simple required parameter and no output schema, so the description does not need to explain return values. It covers the action, applicable states, non-rollback behavior, and even suggests reading the receipt to verify what happened. 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?

The input schema fully documents the only parameter, id, with 'The job id', and schema description coverage is 100%. The tool description adds no extra parameter-specific meaning such as id format, source, or validation rules. Since the schema already covers the parameter, a baseline score 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?

The description uses a specific verb ('Cancel') and a clear resource ('a queued or running asynchronous operation'), making the tool's function immediately understandable. It also implicitly distinguishes itself from related sibling tools like wait_for_job and resume_job by focusing on the queued/running state and the cancellation action.

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

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

The phrase 'queued or running' sets a clear precondition for when to use the tool, implying it is not for completed operations. It also gives procedural advice: confirm with the user and read the receipt afterward. However, it does not explicitly name alternatives like wait_for_job or resume_job, leaving the contrast implicit.

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 discloses important behavior beyond the annotations: 'The comment replaces any previous one' signals overwrite semantics, and 'get the incident back' describes the return behavior. It also states the required scope. The annotations already indicate mutation, so the description adds useful context without contradiction.

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

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

Two sentences carry purpose, scope, an example, replacement semantics, and return behavior. Every clause earns its place, and the key purpose is 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?

For a simple two-parameter mutation tool with no output schema, the description is complete: it states what to do, the required scope, that it replaces existing comments, and that the incident is returned. Nothing essential 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?

Schema description coverage is 100%, so the schema already documents both 'id' and 'comment'. The description adds color with 'for example the root cause' and the replacement behavior, but it does not substantially enhance parameter meaning beyond what the schema provides.

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: 'Annotate an incident with a note' and notes the return value. It clearly identifies what the tool does, though it does not explicitly contrast it with sibling tools such as get_incident or create_status_page_incident.

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

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

The description provides clear context for when to use the tool: when you need to store a note on an incident, and it even gives an example ('root cause'). The scope requirement 'monitor:write' adds a practical prerequisite, but it does not explicitly name alternatives or exclusion cases.

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 adds meaningful context: it requires the 'contact:write' scope and involves an interactive user step to retrieve the code. Since annotations do not contradict this, the extra behavioral context earns credit, though it does not describe the resulting resource state.

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

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

The description is two sentences, front-loads the primary operation, and adds only necessary context about scope and user interaction. Every sentence contributes without redundancy.

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

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

For a simple two-parameter action with no output schema, the description gives the purpose, required scope, and a direct instruction for obtaining the code. It could be more complete by explicitly mentioning the preceding send_contact_confirmation step, but it is otherwise sufficient 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that the code arrives via inbox or phone, clarifying the source of the code parameter beyond the schema's 'received' wording. It does not repeat the schema descriptions verbatim.

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 identifies the operation as confirming a contact using the code the contact received, which is a specific verb+resource pairing. It distinguishes from siblings like send_contact_confirmation by focusing on the confirmation step, though it does not explicitly name the alternative.

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 provides partial usage guidance by instructing the agent to ask the user for the code from their inbox or phone, implying the tool is used after a code has been sent. However, it does not explicitly state when to use this tool instead of send_contact_confirmation or update_contact, leaving the choice partly inferred.

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 discloses the required OAuth scope ('monitor:write') and an important async behavior: copying to many addresses returns a job id that must be polled with get_job. This adds meaningful behavioral context beyond the annotations, though it does not fully describe single-address return behavior or edge cases.

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, the scope requirement is included, and the important async polling behavior is stated in one compact sentence. 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?

The description covers the essential behavior, scope, and the async job flow for bulk copies, and points to get_job for follow-up. Since there is no output schema, the description cannot rely on structured return defaults; it does not explain the response for single copies or possible failure states, but it is otherwise sufficient for a tool with fully documented parameters.

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 parameters already carry meaningful descriptions. The tool description adds only high-level context ('new addresses', 'keeping its configuration') and does not introduce detail beyond what the schema provides, which matches the baseline of 3.

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

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

The description states a specific action ('Copy'), a clear resource ('a monitor'), and the target ('one or more new addresses'), and clarifies that configuration is preserved. This clearly distinguishes copying from create, update, or delete operations among the sibling tools.

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 basic use case clear and notes the 'monitor:write' scope requirement. However, it does not explicitly compare against alternatives like create_monitor or bulk_create_monitors, nor does it state when not to use this tool. The usage context is implied rather than explicitly differentiated.

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 only mark readOnly=false, openWorld=false, destructive=false and carry no side-effect detail, so the description bears the full disclosure burden. It reveals that sending to the address is a real-world action requiring user confirmation, that contacts are created UNCONFIRMED with a confirmation code sent out-of-band, and that confirm_contact must be called before alerts are delivered. It also states the required 'contact:write' scope. All disclosures are consistent with 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?

Five sentences, each with a distinct load-bearing job: purpose, auth scope, real-world caution, unconfirmed-state workflow, and sibling routing. The purpose is front-loaded in the first sentence and there is no redundant or filler 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?

The tool's unusual workflow — creation yields an UNCONFIRMED contact requiring a confirm_contact step — is fully disclosed, as is the auth scope and the alternative for signed HTTP delivery. All parameters are schema-documented. The only gaps are that, with no output schema, the return value is never hinted and the mechanism for obtaining the confirmation code is left implicit (it is sent to the address, implying out-of-band retrieval from the user).

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 documents all 5 parameters at 100% coverage, so the baseline is 3. The description adds genuine value by attaching behavioral semantics to address — it will receive a confirmation code and sending to it is a real-world action warranting user confirmation — and by reinforcing the four valid type values. The remaining parameters (name, language, alertDelay) are already fully explained in 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?

The opening sentence states a specific verb and resource — 'Create a contact' — and enumerates all four accepted types (email, sms, voiceCall, webPush). It also distinguishes itself from the create_webhook sibling by routing signed HTTP delivery elsewhere, so an agent can select this tool confidently without opening other 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 clearly states the main use case (person-facing alert contacts by email, SMS, voice call, or web push) and explicitly routes signed HTTP delivery to create_webhook instead. It also positions confirm_contact as the mandatory follow-up step. It does not enumerate every contact-related sibling (e.g., test_contact, subscribe_contact), but the most confusable alternative is handled explicitly.

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

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

The annotations already indicate this is a write operation (readOnlyHint=false), and the description adds a useful behavioral detail by naming the required 'contact:write' scope. It also clarifies the internal structure of what is being created. Minor gaps like return shape or idempotency are acceptable for a straightforward create operation.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, defines the core concept, and includes the required auth scope. Every part is necessary and there is no redundancy or 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 simple two-parameter creation tool with full schema coverage, the description is sufficient for correct invocation: it names the resource, the required permission, and the structure of the group. There is no output schema, so omitting the exact return value is 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?

The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description reinforces the conceptual model of a named group with contacts and events, but it does not add parameter-specific details beyond what the schema already provides.

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 action ('Create') and resource ('a contact group'), then defines the resource as a named set of contacts with the events each contact should receive. This clearly distinguishes it from sibling tools like create_contact, update_contact_group, and delete_contact_group.

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

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

The description implies the use case through its definition of a contact group and adds a prerequisite via the 'contact:write' scope. However, it does not explicitly explain when to prefer this tool over create_contact or how it relates to update_contact_group, so the usage guidance is only implied.

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

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

It discloses the key behavioral side effect: while the maintenance window runs, covered monitors suppress alerts and optionally suppress statistics. It also states that times are Unix seconds. This goes beyond the sparse annotations and gives the agent meaningful expectations about what the tool does at runtime.

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 three short sentences with no wasted words. The main action is front-loaded, followed by scope, side effects, and time format—all high-value information in an efficient structure.

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?

The core behavior and time convention are well covered, and the schema handles parameter details. However, for a 9-parameter mutation tool with no output schema, the description could add more context about return values and recurring-window semantics, even though the schema already documents weekDays and timezone.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little beyond what the schema already says: 'Times are Unix seconds' repeats parameter descriptions, and 'if asked' only lightly echoes suppressStats/suppressAlerts defaults. It does not clarify the to/durationSec exclusivity or recurrence semantics beyond schema text.

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

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

The description uses a specific verb ('Schedule') and a specific resource ('maintenance window over an explicit set of monitors'), making the tool's function immediately clear. It also distinguishes this tool from siblings like update_maintenance, list_maintenance, and delete_maintenance by focusing on the creation act.

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 conveys the primary use case—scheduling a maintenance window—and adds the required auth scope ('monitor:write'). It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent can determine when to invoke this 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 say destructiveHint=false, but creating a monitor consumes an account slot and begins alerting—the description surfaces that side effect, which is exactly the kind of behavioral disclosure that matters beyond the annotations. It also notes that contacts are attached separately, preventing a false expectation that the create call wires up notifications.

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, all information-bearing, no filler. The core verb phrase is front-loaded and the behavioral warnings follow immediately. 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?

With no output schema, the description doesn't say what the response contains, which is a minor gap. However, the behavioral context (slot consumption, alerting starts, contacts later) is well covered, and the schema fully documents parameters and required fields. Also lacks an explicit why-use-this-vs-bulk_create_monitors, so not a 5.

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

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

Schema coverage is 100%, so the schema itself documents all nine parameters with descriptions. The description adds the account-slot consequence and the confirm-first rule, but it doesn't add extra meaning to specific parameters beyond what the schema already states. That lands exactly at the baseline 3 for full schema coverage.

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

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

The description opens with 'Create a monitor', a clear verb+resource statement. It doesn't explicitly distinguish itself from sibling tools like bulk_create_monitors or copy_monitor, but the singular 'Create' plus the immediate behavioral notes make the primary 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?

It explicitly tells the agent to confirm the target and interval with the user first, and why (a monitor consumes an account slot and starts alerting). It also points to subscribe_contact as the follow-up step, which is strong when-to-use guidance. It names no alternative for the create action itself, but the human-confirmation requirement is the critical usage rule here.

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 indicate this is a write operation that is not read-only and not destructive, but the description adds essential behavioral context beyond those flags: the page becomes publicly accessible at its slug and requires prior user agreement on slug, title, and monitors. This is valuable context an agent would not otherwise know.

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 with no filler. The core action is front-loaded, and the second sentence delivers the critical constraints—scope, public visibility, and user agreement—each earning 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 tool's complexity—four parameters, two required, no output schema—the description covers the essential operational context: what the tool does, the required permission, the public nature of the result, and the prerequisite of user agreement. Combined with the fully documented schema, nothing critical is missing for correct invocation.

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

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

The input schema already documents all four parameters with descriptions, and coverage is 100%, so the baseline is 3. The description adds a general hint that monitors should be agreed upon before creation, which loosely relates to componentsJson, but it does not provide extra parameter-level detail beyond what the schema already offers.

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 the specific verb and resource: 'Create a status page.' It also adds distinctive behavioral scope by noting the page becomes public at its slug, which clearly separates creation from reading, updating, or deleting status pages among the siblings. This 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?

The description provides clear context for when to use this tool: it is for creating a status page, requires the 'statuspage:write' scope, and mandates user agreement before creation. It does not explicitly enumerate when not to use it or name alternatives like update_status_page, but the creation-specific guidance is actionable and 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 description clearly discloses the most important behavioral trait: 'This PUBLISHES the message to the page and notifies its subscribers'. This goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by explaining real-world side effects and adding an approval safety guideline. It also notes the scope requirement.

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 three sentences with no filler. It front-loads the primary purpose, then adds the critical scope/behavioral warning, and ends with actionable usage guidance. 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 10-parameter tool with no output schema, the description covers the core purpose, scope, side effects, and usage warning. It doesn't explain return values (mitigated by no output schema) or when to use scheduledStart/scheduledEnd vs. the kind parameter, but the schema covers parameter-level details. The description adequately compensates 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 fully documents each parameter. The description adds useful context about publishing/notifying subscribers, which relates to the message parameter's impact, but doesn't add significant semantics beyond what the schema provides. 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 explicitly names the verb (declare), the resource (an incident or scheduled maintenance on a status page), and the scope ('statuspage:write'). It clearly distinguishes from siblings like create_maintenance and add_status_page_incident_update by covering both incident and maintenance declaration.

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 states the scope requirement and provides a strong usage warning: get user approval on exact wording before publishing. It also implies when to use this tool (when declaring incidents/maintenance) but doesn't explicitly contrast with create_maintenance or add_status_page_incident_update as alternatives.

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

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

The annotations are sparse, so the description carries the responsibility of behavioral disclosure. It adds critical runtime details: the URL must be https and publicly reachable, the exact allowed event set, and that the signing secret is returned only once. This is significant, non-obvious behavior that an agent needs to know.

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 short sentences with no filler. The core action is front-loaded, followed by scope, constraints, event vocabulary, and the one-time-secret warning, with every sentence earning 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 note that 'the response carries the signing secret once' sufficiently sets return expectations. Combined with URL requirements, the full event vocabulary, and scope prerequisites, the description contains everything an agent needs to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by enumerating the valid event names for the events parameter and adding the publicly-reachable constraint for url, going beyond the schema's wording. It does not enrich every parameter, but it meaningfully supplements the most decision-critical ones.

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 'Register a webhook,' which is a specific verb and resource, and clearly identifies this as a creation operation distinct from sibling tools like list_webhooks, update_webhook, and delete_webhook. It further clarifies the required scope, making the tool's purpose unmistakable.

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 clear context for when to use the tool: to create a webhook, and it states the prerequisite scope 'webhook:write' plus the required URL and reachability constraints. It does not explicitly contrast against alternatives like update_webhook or test_webhook, 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 destructiveHint annotation, the description discloses the cascading effect on subscriptions, the concrete consequence ('their monitors stop notifying that address'), the required confirmation step, and the receipt return value. This is substantial behavioral context that annotations alone do not provide, and it does not contradict 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 sentences, no wasted words. The core action is front-loaded, and each subsequent clause adds essential information: scope, destructive warning, user confirmation, consequence, and follow-up action. The structure is ideal for quick agent scanning.

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?

Despite having no output schema, the description tells the agent what to do with the return value ('report the receipt'). Combined with 100% schema parameter coverage and annotations for idempotency/destructiveness, all necessary invocation context is present. Auth scope, side effects, and user-confirmation requirements are all addressed.

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

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

Schema description coverage is 100%, so both id and confirmed are already fully documented in the schema. The description largely repeats the confirmation workflow already in the schema ('confirm with the user first') without adding new parameter-level meaning, earning the baseline score of 3.

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

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

The description states a specific verb and resource ('Delete a contact') and adds a key scoping detail ('and every subscription it had'), which clearly distinguishes it from siblings like delete_contact_group or unsubscribe_contact. The action and object are 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 provides clear context for safe usage: it requires scope 'contact:write', warns that the action is destructive, instructs to confirm with the user first, and tells the agent to report the returned receipt. It does not explicitly contrast with alternatives (e.g., unsubscribe_contact for non-destructive removal), but the destructive-warning and confirmation flow effectively guide when to use this 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 destructiveHint annotation, the description discloses the required OAuth scope, instructs the agent to confirm with the user first, and clarifies the non-destructive effect on contacts. These behavioral details are not present in annotations and add real operational context.

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 short sentences, each earning its place: purpose, scope, destructive confirmation, and a key distinction from sibling tools. The most important information is 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?

The definition covers purpose, scope, destructiveness, and confirmation requirement. The two-step confirm flow lives in the schema, which is acceptable, and the no-output-schema means return values are not otherwise expected. It could be more complete by explicitly referencing the confirmation flow in the description, but the schema fills that gap.

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

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

Schema description coverage is 100%, so the baseline applies. The description does not discuss parameters, but the schema already documents id and the two-step confirmed flag thoroughly. No additional parameter meaning is needed.

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 'Delete a contact group', a specific verb and resource, and immediately distinguishes itself by clarifying that contacts themselves are not deleted, which differentiates it from sibling tools like delete_contact. The destructive warning reinforces the core 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 states the operation and clarifies that contacts are not deleted, which implies it is the tool for group deletion and not individual contact deletion. However, it does not explicitly name alternatives like delete_contact or update_contact_group, so usage guidance remains implied 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds concrete behavioral context: the required scope 'monitor:write', the need for user confirmation, and the immediate consequence that active monitors resume alerting. This is exactly the kind of extra safety-relevant behavior an agent needs.

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 tight sentences with no filler. The action is front-loaded, followed by scope, a clear DESTRUCTIVE warning, and the user-confirmation requirement. Every clause earns its place.

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

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

For a simple two-parameter tool, the description plus schema and annotations fully cover the call flow: what it does, what scope is required, that confirmation is mandatory, the two-step confirmed-parameter pattern, and the operational impact. No critical information 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 schema already fully documents both parameters, including the confirmation flow for 'confirmed'. The tool description itself adds no parameter-level detail, so the baseline score 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 opens with a specific verb and resource: 'Cancel a maintenance window.' It is unambiguous and clearly distinguishes this tool from siblings like create_maintenance, update_maintenance, and list_maintenance by naming the cancel action 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?

The description clearly states the destructive nature and instructs the agent to confirm with the user first. It also explains the consequence of cancelling an active window, which guides appropriate use. It does not explicitly compare against update_maintenance, but the context is clear enough for 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 important behavioral details: it deletes subscriptions as well, is irreversible, requires confirmation, and returns a deletion receipt. This meaningfully extends the destructiveHint and idempotentHint annotations rather than merely repeating 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 dense sentences convey action, scope, permissions, destructiveness, irreversibility, user confirmation, and the expected output. There is no filler, and the most important warning is 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?

For a simple two-parameter destructive tool with 100% schema coverage and no output schema, the description provides everything needed: what is deleted, the permission scope, the confirmation protocol, and the receipt to report. Missing return-format details are not necessary given the tool's simplicity.

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

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

Schema coverage is 100%, so the baseline is 3; the description does not need to re-explain id or confirmed. It does implicitly reinforce the confirmation workflow, but it adds no parameter-specific meaning beyond what the schema already documents.

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 action ('Delete one monitor') with an explicit resource and scope, plus the cascading effect on subscriptions. It is easily distinguished from sibling tools like bulk_delete_monitors or delete_status_page by the resource and 'one monitor' qualifier.

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 strong contextual guidance: this tool is destructive, not undoable, and requires user confirmation before use. It does not explicitly name alternatives such as pause_monitor or bulk_delete_monitors, so it stops short of a full when/when-not comparison, but the intended usage context is 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?

Beyond the destructiveHint annotation, the description discloses the cascading deletion scope (components, incidents, subscribers), the public-facing nature, the need for user confirmation, and the immediate effect of the slug stopping resolving. This gives the agent critical behavioral context that annotations alone 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?

The description is compact and every sentence earns its place: the core action is stated first, followed by the safety warning and the immediate consequence. There is no redundant wording 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?

Even without an output schema, the description and the input schema together cover the essential context: what gets deleted, the required scope, the destructive public impact, the confirmation workflow, and the result of deletion. Nothing critical is missing for an agent to invoke the tool 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 description coverage is 100%, and the schema already explains the 'confirmed' flag and the two-step call pattern. The description adds emphasis on confirming with the user but does not add new technical meaning to the parameters, 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?

The description uses a specific verb ('Delete') and a clear resource ('a status page'), and it explicitly states the scope of deletion ('with its components, incidents and subscribers'). This distinguishes it from sibling deletion tools like delete_maintenance or delete_contact_group without needing to inspect 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 gives clear contextual guidance: this is DESTRUCTIVE and public-facing, so an agent should confirm with the user first, and the schema reinforces a two-step call pattern. However, it does not explicitly name alternative tools or state when NOT to use this tool, leaving some inference to the agent.

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 destructiveHint=true annotation, the description adds concrete irreversible consequences: "pending deliveries are dropped and the signing secret cannot be recovered," plus the auth scope requirement. This is exactly the context the rubric asks for (what gets destroyed, auth needs). No contradiction with annotations — destructiveHint=true aligns with the explicit DESTRUCTIVE warning.

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 zero filler: the first states action and effect, the second front-loads the DESTRUCTIVE warning before the scope and consequences. Every clause earns its place.

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

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

For a simple 2-parameter tool with no output schema, the description plus the fully documented schema covers the complete invocation flow: call without confirmed, show the resource to the user, then call with confirmed=true. The only minor gap is error/idempotent behavior on deleting a nonexistent webhook, which the idempotentHint=true annotation only partially addresses.

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 of 3 applies. The description does not add parameter-level detail, but the schema fully documents id, confirmed, the default false, and even the two-phase workflow ("Call WITHOUT it first: the tool answers with the resource so you can confirm with the user"). The description's confirm-first line reinforces, rather than extends, 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?

"Unregister a webhook and stop its deliveries" names a specific verb, resource, and observable effect, so an agent immediately knows what happens. It is clearly distinguishable from sibling tools like test_webhook, redeliver_webhook, or update_webhook 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?

The description explicitly instructs "confirm with the user first," establishing the correct human-in-the-loop sequence for a destructive call, and states the required scope 'webhook:write' as a precondition. It does not name explicit alternatives or when-not conditions, but for a delete operation the usage context is essentially complete.

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 it read-only and non-destructive. The description adds useful behavioral context by stating that all timestamps are Unix seconds and all ids are opaque strings, and by clarifying that the tool exposes the API contract rather than performing operations. No contradiction with 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?

Three sentences cover purpose, usage guidance, and a key API-wide convention. The description is front-loaded with the main action and contains 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 one-parameter, read-only reference tool, the description provides enough to invoke it correctly: what it returns, how to search, when to use it relative to api_request, and important data-format conventions. The schema handles the omit-to-list-all behavior, so 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 for the single 'search' parameter is 100%, including a description and default, so the baseline is 3. The description adds example search terms, but the schema already provides similar examples, so it does not contribute significant semantic meaning beyond the structured definition.

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 the exact action: 'Describe the HostTracker v2 REST operations available through api_request' and enumerates what is covered: paths, what each operation does, query parameters, and request-body members. This clearly distinguishes it from the concrete operation siblings and from api_request itself.

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 explicitly says to call it with a search term before using api_request, and explains why: 'so the call is built from the real contract rather than guessed.' This is clear when-to-use guidance, though it does not explicitly discuss when not to use the tool or name alternative discovery pathways.

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 discloses important behavioral details beyond annotations: the call is asynchronous, returns a job id rather than a report, and requires polling before the report can be fetched. It also states the required 'monitor:read' scope and Unix-seconds convention. 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?

The description is compact and every sentence adds value: the first states the action, the second explains the async job workflow and scope, and the third clarifies time units. The most important information is 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?

For an async tool with 8 parameters and no output schema, the description sufficiently covers the job lifecycle, how to obtain the final report, required scope, and time conventions. It could mention cancel/resume behavior or alternative report tools, but those are not essential 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?

The schema already describes all 8 parameters with 100% coverage, so the baseline is 3. The description adds modest value by clarifying the time-range concept and Unix-seconds units, but these are also present in the schema. It does not need to compensate for missing schema information.

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: 'Request an uptime report over a set of monitors and a time range.' It also names the async job-id workflow, which clearly distinguishes this tool from sibling report-related tools such as get_uptime_summary or list_report_types.

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

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

The description gives clear context for when to use the tool and explicitly tells the agent to poll with get_job or wait_for_job, defining the expected follow-up workflow. It does not explicitly name alternatives or exclusions, but the usage context is clear and actionable.

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 provide readOnlyHint and destructiveHint, and the description reinforces this by stating it is read-only and cannot change account settings. It also adds the auth scope 'account:read' and the list of account attributes read, which is useful context beyond the annotations.

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

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

Two tightly written sentences with no filler. The main action and resource are front-loaded, followed by a compact scope list and a clear read-only warning.

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, parameterless, read-only tool, the description covers what data will be returned and the permission scope. It does not detail exact return formatting, but with no output schema and such a general read operation that 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?

The tool has zero parameters, so the baseline is 4; the description does not need to add parameter-level detail. The input schema is empty, and the description's mention of what is read is enough for a parameterless call.

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 the specific verb 'Read' and identifies the resource as 'the account', then enumerates the data categories (identity, package, resource usage, limits, status flags). It is clear and not tautological, though it does not explicitly contrast with sibling tools get_account_quota or get_account_usage.

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 provides clear context: it is a read-only operation scoped to 'account:read' and explicitly states the server cannot change account settings, which tells an agent not to use it for modifications. It does not name alternative tools for quota- or usage-specific reads, but the exclusion is explicit and sufficient given the simple scope.

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 read-only and non-destructive. The description adds meaningful context beyond annotations: it inspects the current token's actual scopes, mentions the 'account:read' scope, and explains how the result helps diagnose 403 errors. This is useful behavioral information not available from structured fields alone.

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, each earning its place: what the tool reads, the relevant scope, and when to call it. The key information is front-loaded with no filler or redundancy.

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

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

For a zero-parameter, read-only diagnostic tool, the description fully equips an agent. It states the resource, the scope requirement, and the exact situation in which to invoke the tool. Even without an output schema, the agent understands what the tool exposes and how to use the result.

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 is empty, so there are no parameter semantics to clarify. The description appropriately focuses on behavior and return-purpose instead. This matches the baseline for a parameterless tool.

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: 'Read the API quota headroom and the scopes the current token actually carries.' It clearly states what the tool does and differentiates it from siblings like get_account_usage by focusing on headroom and token scopes rather than raw usage.

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 explicitly gives a when-to-use trigger: 'Call this first when another tool returns a 403.' This is clear and actionable. It does not name alternatives or say when not to use the tool, but the diagnostic context is strong enough to guide an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by specifying what resource usage is counted and that it relates to package allowances, plus the required scope, but it does not disclose response shape, error behavior, or rate-limit implications.

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 entire description is one efficient sentence with the action and resources front-loaded. The scope note is placed at the end and adds necessary authorization context without unnecessary 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 simple, zero-parameter read operation with annotations covering safety, the description conveys the essential behavior: it returns usage counts of four resource types relative to package allowances. It does not fully disambiguate from get_account_quota, and there is no output schema, but the core calling context is present.

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 input schema has zero properties, so parameter documentation is unnecessary. With no parameters, the baseline is 4; the description does not need to add parameter-level semantics.

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 ('Read') and names the exact resources being measured: monitors, contacts, reports, and maintenance windows. It also clarifies that these are compared against what the account's package allows, which distinguishes it from sibling tools like get_account_quota that likely return raw quota limits.

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 provides no guidance on when to use this tool versus alternatives such as get_account_quota or get_account. The only extra line, 'Scope account:read', is an authorization note, not usage direction.

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 readOnlyHint and destructiveHint, so the safety profile is known. The description adds the requirement of a token with 'check' scope, which is useful auth context, and notes it fetches 'current' results, implying the data can be updated. It does not describe return format or errors, so it only moderately extends beyond 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 short sentences; the first sentence states the primary function, the second gives the auth requirement. No filler or repetition of schema trivia.

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?

The tool is simple: 2 fully-documented parameters, no output schema, read-only. The description tells the agent what to pass and from where, and the auth scope needed. It does not describe the result payload or polling semantics, but that is not necessary for correct invocation; how to consume the response is likely covered by API conventions.

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

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

Schema description coverage is 100%; both id and dbId are documented with descriptions referencing run_instant_check. The description merely echoes 'by its dbId and id' without adding new parameter-level detail, so it meets the baseline but does not exceed 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 ('Fetch'), names the resource ('current results of a previously started instant check'), and specifies the identifiers ('by its dbId and id'). It clearly distinguishes from sibling tools like get_job or list_monitor_results by tying the operation to run_instant_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 states the tool is for a 'previously started instant check' and that the ids come from run_instant_check, making the intended workflow clear. It does not explicitly name alternatives or exclusions, but the context is sufficient to know when this tool applies versus other fetch/list 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 convey readOnlyHint=true and destructiveHint=false, and the description adds the scope requirement and expand behavior. It does not describe return shape or error behavior, but for a simple getter this is acceptable.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the expand guidance is direct and actionable.

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?

The description is sufficient for a low-complexity read tool with robust schema documentation and read-only annotations. It could mention the return type or missing-contact behavior, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that expand='subscription' reveals subscription details, giving practical meaning beyond the raw schema token list.

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 action, 'Read one contact', with a clear resource. It distinguishes itself from list_contacts by emphasizing singular scope, though it does not explicitly name sibling alternatives.

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 clear contextual guidance: the required scope 'contact:read' and how to use the expand parameter to retrieve subscriptions. It does not exclude alternatives, but for a single-contact read operation the use case is straightforward.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description consistently describes a read operation. It adds behavioral context beyond the annotations by stating that the returned incident includes the transitions that opened and closed it and by noting the required auth scope 'monitor:read'. This is useful for agents planning calls, though it doesn't cover rate limits or error behavior.

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

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

Two short sentences deliver the core operation and a scoping note with zero filler. The key behavioral detail (transitions) is front-loaded. 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 a simple read tool with full schema coverage and annotations, the description provides the essential call context: one incident, transitions included, required scope. The absence of an output schema is partially mitigated by the mention of transitions, but the response structure is left unspecified, so it is not maximally 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 the id and expand parameters. The description does not add parameter-specific details, but that's acceptable because no information is missing that would affect invocation. It earns the baseline 3.

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

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

The description uses a specific verb ('Read') with a specific resource ('one incident') and adds a distinguishing detail ('with the transitions that opened and closed it'). This clearly separates it from siblings like list_incidents, which fetch multiple incidents, and comment_incident, which mutates.

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

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

The description establishes clear context: this is for reading a single incident's details, including its opening/closing transitions. It does not explicitly name alternatives or exclusions, but the 'one' vs. list siblings makes the intended use apparent. No prerequisites or when-not conditions are stated, so it stops short of full routing guidance.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavior beyond that: a failed job still returns 200 with state='failed', and each failed item carries its own error. This is exactly the kind of API quirk that helps an agent handle results correctly.

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 with no filler. It front-loads the core purpose, then states the most important behavioral nuance. 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?

Given the simple read-only nature, full schema coverage, and annotations, the description covers the essential contract: state, progress, per-item results, and failure semantics. Since there is no output schema, a bit more explicit detail about the response shape would push it to a 5, but it is sufficient for effective use.

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 all three parameters (id, limit, cursor) at 100% coverage, including defaults and ranges. The description does not add much beyond that, except to clarify that limits and cursors relate to per-item results. It meets the baseline without significantly enhancing parameter understanding.

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 says 'Poll one asynchronous operation: its state, progress and per-item results,' which is a specific verb and resource. It clearly scopes the tool's function, though it does not explicitly distinguish it from siblings like wait_for_job, cancel_job, or resume_job.

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: use this tool to poll an asynchronous operation and inspect its state, progress, and per-item results. However, it provides no explicit guidance about when to prefer this over wait_for_job or how it relates to cancelling/resuming jobs. The usage context is present but not fully developed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'monitor:read' scope and the behavior of expand tokens, but it does not describe return shape or pagination-style behavior; the annotation coverage lowers the bar enough for a 3.

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

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

Two compact sentences with no filler. The core behavior is front-loaded, followed by scope and actionable expand-token guidance. Every sentence contributes to correct invocation.

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 full schema coverage, read-only annotations, and the description's scope/expand guidance, an agent has enough to call the tool correctly. The only notable gap is the lack of explicit routing guidance versus related sibling tools, but the description's specificity compensates.

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 all parameters at 100% coverage, so the baseline is 3. The description adds value by enumerating the valid expand tokens (settings, uptime, lastResult, lastIncident, subscription, maintenance, attached, spans) and clarifying their role, which goes beyond the schema's generic 'comma-separated expand tokens'.

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 ('Read'), a single resource ('one monitor'), and highlights 'full configuration'. This clearly distinguishes it from list_monitors (which returns many monitors) and get_uptime_summary (which is summary-focused).

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

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

The description implies the use case: retrieve a single monitor's configuration, optionally expanded with more detail. However, it does not explicitly name alternatives like list_monitors or get_uptime_summary, nor does it say when not to use this 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 destructiveHint=false, so the description adds only the scoping detail that settings and components are returned and that the statuspage:read scope applies. No additional context about response structure or edge cases is provided.

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 one tight sentence with the core behavior stated first and a brief scope note appended. There is no redundant or filler 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?

For a simple one-parameter read operation with annotations covering the safety profile, the description is nearly complete. It could mention response format or invalid-id behavior, but those are minor gaps given the tool's simplicity.

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 lone id parameter is already documented in the schema. The description does not add meaningful information beyond what the schema provides.

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 that the tool reads one status page and its settings and components. This distinguishes it from list_status_pages, create_status_page, update_status_page, and delete_status_page.

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

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

The singular wording implies use when a specific status page is needed, but the description does not explicitly mention alternatives or when not to use this tool. It relies on the reader to infer the contrast with list_status_pages.

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 readOnlyHint=true and destructiveHint=false. The description adds a concrete permission scope ('monitor:read') and the non-obvious default-window behavior. However, it does not disclose pagination, grouping details, or response shape beyond what the schema itself implies, so the added behavioral context is moderate.

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 three short sentences with no filler. Purpose, permission scope, and time-window semantics are each stated once, front-loaded, and 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?

With 9 parameters and 100% schema coverage, the schema carries most of the parameter documentation. The description adds permission scope and the default-window fallback. The main gap is the absence of any output-shape description, but given the lack of an output schema and the clarity of the summary purpose, the definition is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter-related context by stating that times are Unix seconds and that omitting the window uses the API's default range—an important behavior not captured by the schema's 'default: null' fields. This extra guidance raises the score slightly above baseline.

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

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

The description opens with a clear statement of what the tool provides: 'Uptime, SLA and response-time figures over a time window for one or more monitors.' This identifies the resource (monitors) and the nature of the data. It does not explicitly name sibling tools for differentiation, but the purpose is specific enough to distinguish it from raw check result or monitor configuration tools.

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 by describing the returned figures, allowing an agent to infer when to call it, but it does not explicitly state when to use it versus alternatives, nor does it give any exclusion criteria. Sibling tools such as get_check_result or list_monitor_results are not referenced, leaving the routing decision partially to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavior beyond that: it reads live from the API catalogue, is cached only briefly, and requires no authentication. It does not describe output shape or pagination, but for a no-parameter catalogue list that is a minor omission.

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

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

Two tight sentences earn their place: the first names the exact resources returned, and the second covers the live source, caching, and authentication. There is no filler or repetition of the tool name.

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

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

For a no-parameter, no-output-schema, read-only catalogue tool, the description is complete: it identifies the resource contents, the sourcing behavior, caching, and auth requirements. An agent has everything needed to safely invoke and interpret the tool's purpose.

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 input schema has zero parameters, so the baseline is 4. There are no parameter semantics to document, and the description correctly avoids inventing any.

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 ('List') and an exact resource: the instant-check types HostTracker supports, plus the waterfall check device profiles. This clearly distinguishes it from sibling catalogues like list_monitor_types and list_report_types without needing to inspect 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?

The description makes the tool's context clear: it is an API-catalogue-backed listing for instant-check types and waterfall profiles, with no authentication needed. It does not explicitly name alternatives or exclusion conditions, but the resource scope is specific enough for an agent to infer when this tool, rather than a monitor-type or report-type catalogue, is relevant.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the required 'contact:read' scope, which is useful authorization context, but it does not disclose pagination behavior, ordering, or return format.

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 short sentences, front-loading the purpose and then adding the required scope. Every word contributes useful information and there is no redundancy.

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

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

For a simple read-only list operation with fully documented optional parameters and clear safety annotations, the description is largely complete. The only minor gap is the absence of any mention of return value shape, but with no output schema and an obvious list result, this is not a blocking omission.

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 limit and cursor parameters. The description adds no additional parameter-level meaning beyond the fact that it lists contact groups, which is the baseline expectation.

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 the action and resource: 'List the account's contact groups.' It is distinct enough from list_contacts by naming 'contact groups' and 'account's', but it does not explicitly differentiate itself from sibling tools such as list_contacts.

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 guidance is provided about when to use this tool versus alternatives like create_contact_group, update_contact_group, or delete_contact_group. The context is implicit from the name and description, but there are no explicit exclusions or sibling comparisons.

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 establish readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the account scope and a domain behavior about unconfirmed contacts, but the statement 'An unconfirmed contact receives nothing until it is confirmed' is vague and doesn't clearly disclose how listing behaves for unconfirmed contacts or what the output 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?

The description is two short sentences with no redundant wording. The primary action is front-loaded, and the additional scope/behavior note is concise and adds context.

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 operation with fully documented optional filters, the description is mostly sufficient. The main gap is the lack of any explanation of return shape or pagination behavior, especially since no output schema is provided, though the schema's limit/cursor parameters partially cover this.

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 six parameters. The description itself adds no parameter-level meaning beyond confirming the overall listing purpose, so the baseline score 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?

The description uses a specific verb and resource: 'List the account's contacts.' It clearly scopes the operation to the account's contacts, distinguishing it from singular operations like get_contact and from contact-group operations like list_contact_groups.

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 mentions the required auth scope 'contact:read' but gives no explicit guidance on when to prefer this tool over alternatives such as get_contact or list_contact_groups. There are no usage conditions, exclusions, or 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds non-obvious behavioral context: the required auth scope ('monitor:read') and the newest-first ordering. There is no contradiction with annotations, though pagination behavior is not described.

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 no filler. Every clause contributes either purpose, scope, ordering, or auth requirements.

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?

The tool is callable from the schema and annotations alone, and the description adds helpful scope and ordering context. However, there is no output schema and the description does not characterize the returned incident items or how filters interact, leaving a moderate gap for an agent.

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 seven parameters. The description only reinforces the 'monitor selection' concept via 'account or a monitor selection' and adds no new format, default, or combination semantics for the 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 description uses a specific verb ('List') and resource ('down-episodes'), defines the scope ('across the account or a monitor selection'), and states ordering ('newest first'). This clearly distinguishes it from sibling tools like get_incident or comment_incident.

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

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

The description gives useful context about account vs. monitor scope and ordering, and mentions the required 'monitor:read' scope. However, it does not explicitly say when to prefer this tool over alternatives such as get_incident or when not to use it.

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 as a safe read-only operation. The description adds useful behavioral context beyond that: listing pools versus individual agents, the fact that pool ids are consumed by create_monitor and run_instant_check, and that 'allworld' is a special value. This materially helps an agent understand what the response will represent.

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 primary purpose is front-loaded, and the secondary mode plus the cross-tool relationship are packed into one compact follow-up sentence. Every clause earns its place.

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

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

For a low-complexity read-only list tool with all parameters documented in the schema, the description covers the essential semantics: what is listed, how to get agents instead of pools, how the output is used, and a special sentinel value. It does not describe output format or pagination behavior, but the absence of an output schema and the simplicity of the tool make this 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%, so the baseline is 3. The description adds extra meaning by tying pool ids to the 'pools' argument of other tools and documenting the special 'allworld' value, which is not covered by the pool parameter's schema description. It also reinforces what agents=true changes semantically.

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 ('List') and resource ('location pools checks can run from'), and immediately distinguishes the two modes: pools by default and individual monitoring locations with agents=true. It is clear how this tool differs from other list tools in the family, even without naming a sibling.

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 clear context on when to use the tool and how to switch between pools and agents, and it explains the relationship to create_monitor and run_instant_check via pool ids. It does not explicitly state exclusions or conditions when not to use it, but there are no obviously overlapping siblings to route around.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is covered. The description adds the required 'monitor:read' scope, which is useful context, but it does not disclose any other behavioral traits such as response shape or pagination 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?

The description is two short sentences with no filler. The main purpose is front-loaded, and the scope requirement earns its place. It is appropriately sized for a simple list tool.

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

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

Combined with the fully documented schema and safety annotations, the description gives an agent everything needed to invoke the tool correctly. The purpose, scope, and read-only nature are clear, and no critical external details are missing for this filtered-list operation.

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?

Input schema coverage is 100%, so all six parameters are documented structurally. The description mentions the state values, but this duplicates the schema's state parameter description and adds no additional parameter-level 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 uses a specific verb ('List') and resource ('maintenance windows') and enumerates the covered states (scheduled, active, finished). It clearly distinguishes this from maintenance mutation siblings like create_maintenance, update_maintenance, and delete_maintenance.

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

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

The description implies use for read-only retrieval of maintenance windows, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. There is no exclusion or referral to sibling mutation tools, leaving the routing partly to inference from the tool name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by disclosing the ordering behavior, the required 'monitor:read' scope, and an important security trait: the error text is untrusted data from the monitored target. No contradiction with 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?

Three short sentences, each earning its place: the first states the action and ordering, the second adds scope and use case, the third warns about untrusted data. No filler or repetition.

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

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

For an 8-parameter tool with full schema coverage and no output schema, the description provides purpose, ordering, permission scope, and a trust warning. It does not explicitly describe pagination returns or response shape, but the schema's cursor/limit parameters and the 'newest first' ordering cover the essentials. Slightly more detail on output format would push it to 5.

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 all 8 parameters documented in the input schema. The description does not add parameter-level explanations, though the 'newest first' phrasing subtly clarifies the default ordering that the from/to parameters control. Baseline of 3 is appropriate given full schema coverage.

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

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

The description uses a specific verb and resource ('List one monitor's raw check results') plus an ordering guarantee ('newest first'), clearly distinguishing it from siblings like list_monitors (which lists monitors) and get_check_result (which likely fetches a single result). It also states the required scope, making the 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 clear context for when to use it: 'Use it to see what actually happened at a given time.' However, it does not explicitly name alternatives or state when not to use this tool, such as for aggregate uptime (get_uptime_summary) or a single check (get_check_result).

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 readOnlyHint annotation, the description discloses the required scope (monitor:read), default ordering, the AND-combination behavior for filters, the 50-row maximum, and cursor-based pagination. This meaningfully expands on what the annotations already convey.

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

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

Three sentences with no filler. The main purpose is front-loaded, and each sentence adds distinct value: scope/ordering, filter semantics, and pagination boundaries.

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 8 optional parameters, the description covers the essential runtime facts: required scope, filter combination rules, default behavior when no filters are given, and pagination limits. The schema already covers individual parameter meaning, so nothing critical is missing for correct invocation.

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

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

The schema already documents all 8 parameters with 100% coverage, so the baseline is 3. The description adds valuable cross-parameter semantics: filters combine with AND, omitting all filters returns the entire account, and the cursor enables pagination. These insights are not present in the schema itself.

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 the action (list), the resource (the account's monitors), and a distinguishing ordering detail (newest page first). It is easy to tell apart from sibling tools like list_monitor_types and list_monitor_results because the target resource is 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?

The description gives practical usage rules: filters combine with AND, omitting all filters lists the whole account, and results are paginated with a cursor. It does not explicitly name alternative tools or when-not-to-use conditions, but the guidance is concrete enough for an agent to call it correctly.

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 it as read-only and non-destructive; the description adds the valuable behavioral detail that a token changes the returned limits. This is context beyond the annotations and no contradiction 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?

Two short sentences: the first fronts the primary purpose and output fields, the second adds the auth conditional. No filler, densely informative.

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 enumeration tool with no output schema, the description fully captures what the tool returns (every monitor type with label, minimum interval, package-create flag) and the auth conditional. 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?

With zero parameters and an empty input schema, the description needn't document parameters. The baseline of 4 applies; the token note is about behavior, not parameter semantics.

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?

Uses a specific verb ('List') with a precise resource ('every monitor type') and names the exact attributes returned (label, minimum interval, package-created eligibility). This clearly distinguishes it from close siblings like list_check_types and list_monitors.

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 states the tool can be called anonymously and that including a token adds per-account limits, giving useful context about auth-dependent behavior. It does not explicitly name alternatives, but the usage context is unambiguous.

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

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

Annotations already indicate read-only and non-destructive behavior, so the description's main added value is the 'Anonymous' access requirement, which is useful operational context. It does not detail return format or pagination, but given the simplicity and zero parameters, this is acceptable.

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, front-loaded sentence with no wasted words. It efficiently lists the four categories of information the tool returns and appends a useful authentication note.

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

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

For a zero-parameter, read-only listing tool, this description is complete: it names the exact content returned, states that access is anonymous, and the annotations cover safety. No additional context is necessary for an agent to correctly invoke it.

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 no parameters, and schema description coverage is 100%. With zero parameters, the description carries no parameter burden and the baseline of 4 applies. It also clarifies the scope of what will be listed.

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 ('List') with a concrete set of resources: report types, output formats, sections, and schedules. This distinguishes it from siblings like generate_report and list_monitor_types, 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 includes the explicit usage context 'Anonymous', meaning no authentication is required. It does not explicitly name alternative tools or state when not to use this tool, but for a zero-parameter listing tool this context is sufficient for basic usage decisions.

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 readOnlyHint=true and destructiveHint=false. The description adds the auth scope requirement ('Scope 'statuspage:read'') and clarifies that the list is scoped to the account, which are useful behavioral disclosures beyond the annotations.

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

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

The description is two short sentences with no filler. The primary purpose is front-loaded, and the scope requirement is stated as a necessary extra detail. Every word 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 list operation, the description combined with the schema and annotations covers the essential information: what it lists, the account scope, the required scope, and pagination parameters. No output schema exists, but the expected result (status pages) is unambiguous enough for 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?

The input schema fully documents both parameters (limit and cursor) with clear descriptions, so the description does not need to repeat them. It adds no additional parameter semantics, which is acceptable given 100% schema coverage.

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

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

The description clearly identifies the action ('List') and the resource ('the account's status pages'), making the purpose unambiguous. It distinguishes itself from get_status_page via the plural/list framing, though it does not explicitly name an alternative.

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

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

The usage context is implied: use this when you need the account's status pages as a list. However, there is no explicit guidance about when to prefer this over get_status_page or create_status_page, and no exclusions are stated.

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

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

The annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds useful non-annotation context: the required scope 'subs:read' and the semantic difference between alert and report subscriptions. It does not contradict 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?

The description is one concise sentence that front-loads the purpose, states the scope, explains the kind variants, and summarizes available filters. Every part earns its place with no irrelevant 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 read-only list tool with complete parameter schema coverage and basic annotations, the description provides enough detail to select and invoke the tool correctly: purpose, scope, variants, and filters. It does not describe the response shape, but with no output schema and a self-evident 'list' purpose, this is a minor omission.

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 each parameter, including limit, cursor, contactId, and monitorId, is already documented. The description adds only a small amount of grouping information by saying 'filter by monitor and/or contact,' but the schema carries the bulk of parameter semantics.

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 and resource: 'List who is notified about what' and then disambiguates with kind='alert' for alert subscriptions and kind='report' for scheduled-report subscriptions. This clearly distinguishes list_subscriptions from sibling tools like list_contacts and list_webhooks.

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 clear usage context: kind='alert' is the default and kind='report' selects scheduled-report subscriptions, and listing can be filtered by monitor and/or contact. It does not explicitly name excluded alternatives, but the tool's purpose is specific enough that this is not a major gap.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds useful context beyond those annotations, including the required auth scope and the diagnostic intent. It also hints at what the listing contains ('outcome and attempts'), which helps set expectations.

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, each carrying distinct value: what the tool does, the required scope, and the intended use case. It is front-loaded and avoids any 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?

The description gives enough context for a read-only list tool: the resource, output summary, scope, and a concrete diagnostic use case. It does not detail pagination or exact return shape, but those are largely covered by the schema and the read-only annotations.

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

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

Schema description coverage is 100%, so the schema already explains all parameters including id, time window, limit, outcome, and eventName. The description does not add parameter-level meaning beyond 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 uses a specific verb ('List') and resource ('recent deliveries for one webhook'), and specifies the returned content ('outcome and attempts'). It clearly distinguishes itself from siblings like list_webhooks by narrowing scope to deliveries of a single webhook.

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 explicitly states when to use the tool: to diagnose why an endpoint stopped receiving events. It also mentions the required scope 'webhook:read'. However, it does not explicitly mention alternatives or when not to use it.

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 read-only and non-destructive behavior. The description adds value by specifying the auth scope ('webhook:read') and the response contents (enabled flag, recent failure count), providing behavioral context beyond the structured hints.

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, information-dense sentence that leads with the action and resource, then adds key details and scope. No wasted words.

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

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

For a simple read-only list tool, the description plus schema covers the essentials: what is listed, key fields, pagination params, and auth scope. It does not describe ordering or output format, but these are not critical for a list operation with no output schema.

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 limit and cursor fully documented. The description adds no parameter-specific meaning, 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 'List' and resource 'webhooks', and adds distinguishing detail about enabled status and failure count. This clearly separates it from sibling tools like list_webhook_deliveries or create_webhook.

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 states it lists the account's webhooks and mentions the required scope, giving context for when to call it. It does not explicitly exclude alternatives or state when not to use it, but the resource is unambiguous.

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

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

Annotations already indicate this is not read-only and not destructive, but the description adds valuable behavioral detail: the monitor stops both checking and alerting, and this state lasts until resumed. It also discloses the required scope 'monitor:write', which helps agents anticipate authorization requirements. The behavior is consistent with 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?

The description is a single, well-structured sentence that front-loads the action and immediately states the consequential behavior. It includes the scope permission without unnecessary filler, so every word contributes 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 one-parameter tool with no output schema, the description covers the action, its observable effects, reversibility, and required scope. The agent has enough context to call the tool correctly and understand what happens afterward, so 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?

The input schema covers 100% of parameter documentation with 'The monitor id.' description, so the schema already explains the lone required parameter. The tool description adds no additional semantic detail about the id parameter beyond what the schema provides, which meets the baseline expectation for high schema coverage.

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

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

The description uses a specific verb ('Pause') and resource ('a monitor'), and clearly states the operational effect: stops checking and stops alerting until resumed. This distinguishes it from sibling tools like resume_monitor, update_monitor, and delete_monitor 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?

The description makes it clear this tool is for pausing monitors and that the pause persists until resumed, implying the complementary use of resume_monitor. It does not explicitly list when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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 a non-read-only, non-destructive operation, and the description adds valuable behavioral context: the required 'webhook:write' scope, the side effect of the receiver seeing the same delivery id, and the deduplication implication for correctly-written consumers. This goes well beyond the 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 compact and front-loaded: the primary action and target appear in the first sentence, with the essential behavioral note in a second short sentence. Every sentence earns its place with no filler or repetition.

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

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

For a simple two-parameter tool with annotations and a clear purpose, the description covers the action, auth scope, and key behavioral consequence. It lacks explicit mention of the response shape or error behavior, but given the tool's low complexity and existing schema coverage, this is a minor gap rather than a critical omission.

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 input schema already documents both parameters fully (100% coverage), including the format hint 'd_...' for deliveryId. The description does not add new parameter-level meaning, so the baseline score 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 uses a specific verb ('Resend') with a clear resource ('previously recorded delivery') and target ('same endpoint'), and distinguishes itself from siblings like test_webhook and list_webhook_deliveries by emphasizing it replays an existing recorded delivery rather than creating a new one.

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 conveys when to use this tool: to resend a previously recorded delivery to the same endpoint. It does not explicitly name alternatives or state when not to use it, but the context anchors the tool to retry scenarios, which is sufficient for a tool with few sibling overlaps.

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 adds behavioral context beyond the annotations: already-concluded items are skipped, and non-interrupted or non-resumable jobs are refused. It also explains what 'interrupted' means. It does not disclose what happens to partially-processed items or what the return value looks like, but it covers the key runtime behaviors.

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 compact and front-loaded: the main action and precondition appear first, followed by important behavioral details and refusal conditions. Every sentence contributes meaningful information with no filler or repetition.

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

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

For a simple one-parameter job-control tool, the description covers the main behavior, preconditions, and refusal cases. It does not describe the return format, but no output schema exists and the tool's primary purpose is clear. Minor gap: what happens to active or partially completed items is not specified.

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 has 100% parameter description coverage for the single 'id' parameter, so the description does not need to duplicate parameter details. The description adds context about which jobs are eligible but does not enrich the meaning of the id parameter itself. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool resumes a job that is in the 'interrupted' state, with a specific verb, resource, and precondition. It differentiates from sibling tools like cancel_job, get_job, and wait_for_job by focusing on resuming an interrupted job.

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 explicitly says when to use the tool: when a job's state is 'interrupted' because its server died. It also states when not to use it: the call is refused if the job is not interrupted or if its kind cannot be resumed. It does not name sibling alternatives, but the conditions are clear enough for an agent to route correctly.

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 this is a mutating operation (readOnlyHint=false) and not destructive. The description adds the required scope 'monitor:write', which is useful behavioral context for an agent deciding whether it can invoke the tool. It does not elaborate on edge cases like resuming an already-running monitor, but for a simple state-change tool the disclosure is adequate.

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 short sentences with zero filler. The core action is front-loaded, and the scope requirement is stated efficiently. Every word 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 one-parameter tool with annotations and a fully documented schema, the description is largely complete. It communicates the action, the target state, and the required permission scope. Slightly more detail about behavior when the monitor is not paused could improve it, 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?

The schema already fully documents the single 'id' parameter with 100% coverage, so the description does not need to add parameter-level detail. The description adds no extra semantics beyond what the schema provides, meriting the baseline score.

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 ('Resume') and a clear resource ('a paused monitor'), making the tool's purpose immediately identifiable. It also naturally distinguishes itself from the sibling pause_monitor, which performs the inverse operation.

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 explicitly targets paused monitors, which signals the intended use case. However, it does not explicitly mention when NOT to use it or compare it to alternatives like pause_monitor or update_monitor, though the context is fairly 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 description goes well beyond the annotations by disclosing that the tool starts the check, polls up to ~30s, returns per-location status plus a public result-page URL, and returns partial results with IDs for continued polling. It also surfaces the authorization requirement. There is no contradiction with 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?

The description is compact and front-loaded: the main action appears first, followed by auth requirements, behavior, timeout, and return shape. Every clause earns its place, with no filler or repeated schema information.

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

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

Despite having no output schema, the description covers the key return elements: per-location status, public result URL, and partial results with polling IDs. The only minor gap is that it does not name the follow-up tool to use with those IDs, which would make the polling workflow fully self-contained.

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 all five parameters documented including defaults, constraints, and aliases such as 'pageSpeed' for 'waterfall'. The tool description itself adds little parameter-specific meaning, but the schema already carries the full load, 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 opens with a specific verb and resource: 'Run a free instant website/host check from HostTracker's global monitoring locations and return per-location results.' This clearly states what the tool does and distinguishes it from monitor-management and result-history tools in the sibling list.

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 the tool is for one-off, instant checks rather than ongoing monitoring, and it notes the required 'check' scope token. However, it does not explicitly state when to prefer this tool over alternatives like create_monitor or get_check_result, so the usage guidance is mostly implied.

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

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

The description discloses a significant behavioral trait beyond what annotations provide: it delivers a real message and never returns the code, instructing the agent to ask the user instead. This is critical information for invoking the tool correctly and is not present in the annotations or schema.

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

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

The description is two efficient sentences that front-load the action, then add scope and a crucial behavioral warning. Every clause earns its place with no repetition or 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 one-parameter tool with annotations, this description covers the purpose, the real-world side effect, and the agent's expected next step. No output schema exists, but the description clarifies what will not be returned, making the tool's behavior predictable enough for reliable invocation.

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

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

Schema description coverage is 100%, so the single parameter 'id' is already documented as 'The contact id.' The description adds no further detail about the parameter, which is acceptable given the simple and self-explanatory 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 states a specific verb and resource ('Send or resend the confirmation code to an unconfirmed contact'), and clearly differentiates this tool from verification tools by emphasizing the code is never returned to the agent. This is more than a tautology and makes the tool's purpose immediately actionable.

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 clear context for when to use this tool: it targets unconfirmed contacts, and the scope 'contact:write' signals permission requirements. It also warns the agent not to expect the code in the response, steering behavior away from a likely misstep. It does not explicitly name alternatives like confirm_contact, but the context is clear enough for correct use.

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