ScaledPapers

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

Annotations already flag destructive=true and idempotent=false, and the description adds real context beyond them: the publish emails subscribers and posts to Slack, i.e. irreversible external side effects, plus the user-consent gate. It stops short of saying what happens to the draft afterwards or that repeat calls create duplicate 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 short sentences, front-loaded with the action, then the side effects, then the precondition. No filler and nothing that duplicates structured fields verbatim.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers action, blast radius, and consent gating — enough to call it safely. Missing only post-call state (what the response returns, whether the draft is consumed) which an agent would want given 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 coverage is 0%, so the description must carry the load — and it does for the three optional params, explaining they 'replace the draft text' and giving the impact enum (minor, major, critical) that the schema lacks entirely. slug and proposal_id remain undescribed, which is the only real gap.

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

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

States a specific verb and resource ('Publish a pending review draft as a status incident') and makes the transformation explicit — a draft becomes a live incident. This clearly separates it from dismiss_incident_proposal and list_incident_proposals without needing 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?

Gives an explicit gating condition: 'Run only when the user asked to publish it in this conversation,' which is exactly the kind of confirmation constraint an agent needs before a destructive publish. It does not explicitly name dismiss_incident_proposal as the alternative path, keeping it just 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?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false. The description adds value beyond that: it discloses the 'can email subscribers' side effect and the notify_subscribers default, which the annotations cannot express. It still omits whether the cancellation is reversible.

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, front-loaded sentences with the action first and the guardrail last. 'This can email subscribers' partially restates the preceding default sentence, a minor 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 destructive, non-idempotent tool with no output schema, it covers the side effect, the parameter default, and the invocation guardrail. What remains missing, such as reversibility of a cancelled window, is secondary.

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 0%, so the description must compensate. It documents notify_subscribers' default (false) and its effect (emails subscribers), but window_id is left with no meaning beyond its name. Partial compensation merits a 3.

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

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

States a specific verb and resource ('Cancel a maintenance window'), which clearly separates it from create_maintenance_window and update_maintenance_window siblings. It does not explicitly name the alternatives, but the operation 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?

Adds an explicit precondition: 'Run only when the user asked to cancel this window in this conversation.' This is a real usage constraint that prevents speculative invocation. It stops short of naming alternatives, so it lands below 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?

Annotations already declare this is a non-read-only, non-idempotent creation tool with destructiveHint false. The description adds valuable behavioral context: defaults for method/status/timeout/alerts/interval/region, the max_regions constraint from usage, and the fact that headers, body, and HTTP auth stay in the console.

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

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

Front-loads the core action and packs useful constraints into a compact paragraph with no obvious filler. It is dense but appropriately sized for a 28-parameter creation 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?

Covers the essential create path and several important constraints, which is sufficient for a basic check. However, for a complex 28-parameter mutation with no output schema and 0% schema coverage, many optional parameters remain unexplained, leaving gaps for advanced configurations.

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 0% across 28 parameters, so the description must carry the burden. It explains key parameters and defaults (kind, port, regions, site linking) but leaves many optional parameters undocumented, including verify_ssl, follow_redirects, expected_status_codes, dns fields, tcp extras, and incident/alert toggles.

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

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

States a specific verb and resource: "Create a check," and names the supported kinds (http, api, dns, tcp). This clearly separates it from update_check/delete_check/get_check in practice, though it does not explicitly name 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?

Provides useful creation guidance: kind-specific defaults, "TCP requires port," "Pass regions only when you want more than the default," and the requirement to pass site_id, site_slug, and component_id together. It lacks explicit when-not-to-use guidance or sibling-tool 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=false, idempotentHint=false, and destructiveHint=false, so the write nature and safety profile are covered. The description adds useful context about returning an id for update_check linking, but it does not mention permissions, duplicate handling, or other mutation behavior.

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

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

Two sentences with no wasted words. The core action is front-loaded first, followed by a useful return-value 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?

With no output schema and no parameter descriptions in the schema, the description should explain the parameters and the return value more fully. It mentions the returned id but omits any explanation of slug, name, and url, and does not clarify how the target status page is identified.

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 0%, so the description must compensate for all three parameters. It does not explain what slug, name, or url mean or how they are used, leaving their semantics entirely undocumented.

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: 'Add a component to an existing status page.' It is clearly distinguishable from update_component and delete_component by the word 'Add', though it does not explicitly name those siblings.

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

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

The phrase 'to an existing status page' implies the prerequisite context, and the note about update_check suggests a downstream use case. However, there is no explicit when-to-use versus alternatives guidance or exclusion criteria.

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 real side effects beyond the annotations: subscriber emails and Slack posts are triggered, matching console behavior, which is critical given destructiveHint=true. It also explains the opened_at/resolved_at backfill semantics that the annotations cannot express. It does not state that each call creates a separate incident (no idempotency implication) or what the response contains.

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

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

Purpose, side effects, the gating constraint, then parameter semantics — well front-loaded and dense with no filler sentences. The transition into parameter notes is slightly abrupt but every sentence carries information.

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

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

For an 8-parameter destructive tool with no output schema and zero schema descriptions, the description covers purpose, side effects, invocation gating, and the critical enum/format semantics. The remaining gap is the unexplained required 'slug' and no indication of what is returned, but overall an agent can call this 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 0%, so the description carries the burden, and it does supply the missing enum values for status and impact plus the meaning of component_ids and the opened_at/resolved_at pairing. However, 'slug' — a required parameter — is never explained (which status page it refers to), and title/body are left entirely implicit.

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 'Open an incident' gives a specific verb and resource, and the side-effect sentence clarifies it is the real, publishing version rather than a draft. It does not explicitly name sibling tools like update_incident or post_incident_update, so differentiation is inferable rather than stated.

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?

'Run only when the user asked to publish this incident in this conversation' is an explicit gating condition that rules out proactive use, which is unusually strong guidance for a mutating tool. It stops short of naming alternatives for related workflows (e.g. use update_incident to amend an open one), so it is clear context without full 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 destructiveHint=true and non-idempotent, so the bar is lower, and the description still adds real context: the side effect of emailing subscribers, the fact that probes pause and the status page flips to "Under maintenance". It explains why the destructive flag matters, though it doesn't say what happens on failure or whether the window can be undone.

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

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

Front-loads the purpose, then layers constraint, required pairing, and the notify gate. Five sentences all carry information, with only mild redundancy between "set it true only when the user asked to email subscribers" and the closing "can email subscribers" 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 an 8-parameter mutation tool with no output schema and no annotations beyond hints, the description covers the operationally risky parts (side effects, duration bounds, required check/component pairing). What it lacks — weekdays semantics, time/zone formats, and any mention of what the call returns — is a modest 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 0%, so the description has to carry the load. It documents duration_seconds (60 through 7 days), endpoint_ids as "the check", status_components as its public component, and the notify_subscribers default — but name, timezone, starts_at, and especially the non-obvious weekdays recurrence field are left unexplained.

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?

Opens with a specific verb+resource ("Schedule a maintenance window"), which cleanly separates it from update_maintenance_window, cancel_maintenance_window, and list_maintenance_windows. It doesn't explicitly name a sibling, so it stops short of a 5.

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

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

Gives a concrete precondition ("run only when the user asked to schedule this window") and a conditional default rule for notify_subscribers ("set it true only when the user asked to email subscribers"). No named alternative tool or exclusion is given, but the gating conditions are explicit enough to route 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?

Annotations cover the mutation/safety profile (readOnly=false, destructive=false), and the description adds substantial context beyond them: the Pro gating, the password rule with an explicit 'never invent a password or repeat it' safety instruction, endpoint-to-component linking with incidents and latency enabled, and the rollback behavior ('if a later step fails, the new page is deleted'). That rollback note is exactly the kind of consequence disclosure the annotations do not carry.

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 dense and front-loaded, with the core action first and constraints after. Every sentence carries information, though the middle sentences are tightly packed with clauses and could be slightly more scannable.

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 helpfully enumerates the return values (slug, publicUrl, component ids, linked check ids) and discloses the rollback on failure, covering the main things an agent needs. It is nearly complete for this tool, with only the trivial parameters and any rate-limit or auth-token expectations left unstated.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the non-obvious parameters: password rules, visibility enum implication, custom_domain hostname format, and endpoint_ids side effects. It leaves url, name, and slug unexplained, but those are largely self-evident, so the gap is minor rather than disqualifying.

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+resource ('Create a public status page') and elaborates on the key fields, so the agent knows exactly what is being made. It does not explicitly name a sibling (e.g. update_status_page or create_component) to contrast with, which keeps it just below a 5.

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

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

Conditional prerequisites are stated clearly: internal visibility requires Pro plus a user-typed password, and custom_domain requires Pro. What is missing is an explicit 'use this instead of update_status_page when…' routing sentence, so usage is well-contextualized but not fully comparative.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds a useful consent guardrail, but it does not explain irreversibility or what associated check data may be removed.

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 waste. The purpose is front-loaded and the safety condition follows immediately.

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 destructive tool with annotations and no output schema, the description is minimally adequate. However, it leaves the sole parameter undocumented and does not describe deletion consequences.

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 0%, and the description never mentions endpoint_id or explains how it identifies the check to delete. 'This check' gives only an indirect hint, so the parameter remains largely undocumented.

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 check.' This clearly distinguishes it from sibling tools such as create_check, get_check, update_check, run_check, and list_checks.

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

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

It gives an explicit invocation condition: run only when the user asked to delete this check in this conversation. That is a strong when-to-use and when-not-to-use guardrail for a destructive action.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds a useful conversational-permission constraint, but says nothing about what is destroyed (component alone or its dependents) or whether deletion is recoverable—context that matters for a non-idempotent destructive 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?

Two short sentences, no waste, with the destructive guardrail front-loaded right after the action statement. 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?

Annotations carry the destructive safety profile and there is no output schema to explain, so the definition is minimally callable. However, for a destructive mutation with fully undocumented parameters and no disclosure of deletion scope, it is only adequately complete rather than thorough.

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 0% for both required parameters (slug, component_id), and the description gives no indication of what they identify or their expected format. The description does nothing to compensate for the undocumented parameters, leaving the agent to guess.

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

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

States a specific verb and resource ("Delete a component"), clearly distinguishing it from sibling deletes like delete_check and delete_status_page. It stops short of explicitly naming alternatives, but the target object 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?

"Run only when the user asked to delete this component in this conversation" gives a concrete when-to-use guardrail that constrains destructive invocation. It doesn't mention alternatives such as update_component or manage_component_group that might achieve a user's intent without deletion.

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 destructiveHint=true and non-idempotent, so the safety profile is covered. The description still adds real value by disclosing cascade behavior ("and its components"), which the annotations do not convey, plus an invocation guardrail.

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 zero filler; the destructive scope is front-loaded and the constraint follows immediately. Nothing could be removed without losing 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?

Cascade destruction and the user-intent guardrail are covered, and no output schema is needed for a delete. But with zero schema documentation for the required slug and no pointers to list_status_pages as the source of a valid slug, an agent can still call this with an unusable identifier.

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 0% for the single parameter, so the description carries the full burden for "slug" and gives nothing — no format, no indication of how a slug differs from a page ID, no example. An agent must guess whether the slug is the page identifier returned by get_status_page/list_status_pages.

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

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

States a specific verb+resource ("Delete a status page") and adds the important scope detail that its components go with it. It is clearly distinguishable from delete_component and delete_check by resource, though it never names a sibling explicitly.

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

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

"Run only when the user asked to delete this page in this conversation" is an explicit precondition that prevents an agent from proactively cleaning up pages. It gives a clear when-to-use rule but no alternatives or prerequisites (e.g. what happens if the page is linked elsewhere).

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful fact – 'Nothing is published' – but never says what actually happens to the proposal (deleted, archived, marked dismissed) or who may dismiss it. Useful but thin given the safety profile is already structured.

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

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

Two short sentences, front-loaded with the action and ending with the consequence. Nothing wasted.

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

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

For a state-changing tool with two undocumented required parameters and no output schema, the definition is under-specified: no parameter meaning, no effect description, no sibling routing. It only conveys the bare action.

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 0% for both required parameters, so the description must compensate and it says nothing about 'slug' or 'proposal_id'. The agent gets no hint about scope (org/status page slug) or where a proposal_id originates.

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

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

States a specific verb ('dismiss') and resource ('pending review draft'), making the action understandable. The framing as 'review draft' rather than 'incident proposal' creates mild friction with the tool name, but the intent is still 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?

No explicit when-to-use guidance and no mention of the obvious alternative, approve_incident_proposal, which sits right beside it in the sibling list. The word 'pending' implicitly signals a precondition, but the agent must infer 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it lists the included field groups and explicitly notes that secrets (headers, body, HTTP auth) are omitted, which is useful for an agent handling sensitive data.

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, front-loaded with the core action and return scope. Every sentence contributes, 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?

The description clarifies what fields are returned and what secrets are excluded, which is important for a read tool. However, with a required parameter and 0% schema description coverage, it should explain what endpoint_id represents; that gap leaves the definition only partially 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 0% and the only parameter (endpoint_id) is never mentioned in the description. The description provides no meaning, format, or example for the required parameter, so an agent must infer its purpose from the tool name alone.

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

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

The description clearly states it retrieves a single check ('One check') and names the categories of fields returned (assertion, DNS, TCP). It distinguishes itself from list_checks by implying a single-item fetch, but it does not explicitly contrast with get_check_results or other siblings.

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

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

Usage is implied: fetch one check when you need its details. There is no explicit when-to-use guidance, no mention of when to prefer list_checks or get_check_results, and no prerequisites or exclusions 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by naming the views, specifying the default history window, listing the history return fields, and noting that sample metadata is omitted.

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-loads the key view information. The long enumeration of history return fields is somewhat redundant given the presence of an output schema, but the text remains efficient overall.

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 annotations covering safety and an output schema covering return values, which reduces the description's burden. Still, it omits any explanation of endpoint_id and provides limited guidance on when to use this tool rather than its siblings, so it is only minimally 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 0%, so the description must carry parameter meaning. It explains view values and the hours parameter for history, but it does not explain the required endpoint_id parameter at all, leaving a significant semantic gap.

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 identifies the resource as check results and enumerates the three supported views (status, history, outages), which is enough to understand the tool's basic function. It does not explicitly distinguish this from sibling tools such as get_check, list_checks, or run_check, so it falls short of a 5.

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

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

The description implies usage through the view enumeration and notes that history uses hours with a default of 24. However, it does not say when to choose this tool over get_check, run_check, or list_checks, nor does it explain when each view is appropriate beyond the brief parameter semantics.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral information — that incident updates are embedded in the response and ordered newest first — but says nothing about pagination, update volume, or missing/not-found 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?

A single short sentence with no filler; the most decision-relevant fact (single incident, updates included) comes first. It is terse rather than padded, though the terseness edges toward under-specification.

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 two required, undocumented parameters, no output schema, and no explanation of identifier formats or error cases, the definition is not complete enough for reliable invocation. The one useful detail (updates ordered newest first) does not offset those gaps.

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

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

Schema description coverage is 0% and the description never mentions the two required parameters. It gives no hint whether "slug" is an org/status-page slug or what format "public_id" takes, so an agent has no way to fill these fields correctly from the definition alone.

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

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

"One incident" names the resource and its singularity, implicitly distinguishing it from the plural/list siblings, and "including updates newest first" adds scope detail. It lacks an explicit verb (fetch/retrieve), but the intent 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?

No guidance on when to call this rather than update_incident, post_incident_update, or the proposal tools, and no mention of prerequisites such as needing an existing slug/public_id. The agent must infer the whole usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds genuinely useful context about what is exposed (ids, Slack connection state) and the password-handling rule (has_password returned, password withheld), but says nothing about error behavior for unknown slugs.

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

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

Two short sentences, front-loaded with the resource and then the security caveat. Nothing is padded and no sentence repeats the schema.

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

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

With no output schema, the description is the only source of return-value information; it names several fields but is clearly a partial list (no page name, custom domain, or subscribers). It also omits how to identify the page via slug, leaving the definition adequate but incomplete.

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 0% and the single required parameter 'slug' is never explained in the description — no indication of whether it is the page's URL slug, id, or display name. With one undocumented parameter the description had a clear obligation it did not meet.

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 the resource (a single status page) and enumerates the notable contents it returns (components, groups, incidents, Slack state, alert-destination ids). The retrieval verb is only implicit ('One status page:'), but the singular framing distinguishes it adequately from list_status_pages.

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 statement of when to call this versus list_status_pages or update_status_page, and no prerequisites. The only cue is the singular resource noun, which leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: secrets are never returned (so agents shouldn't expect credentials) and destination creation is out of scope for the API. Return format/pagination behavior is still unstated.

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, zero filler, with the resource and returned fields front-loaded before the two caveats. Nothing could be removed without losing 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?

An output schema exists, so return values need not be re-explained, and the description covers the key surprises (no secrets, no creation). The remaining gap is whether the result set is complete or whether page_alert_destinations should be used for large collections, which matters given that sibling's presence.

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

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

The tool takes zero parameters and the schema coverage is 100%, so the baseline is 4. The description's field list ('id, kind, name, and hint') is arguably return-value information rather than parameter semantics, but it does no harm and adds context.

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 the resource (alert destinations) and enumerates the returned fields (id, kind, name, hint), so an agent knows exactly what it gets back. It also rules out creation ('Creating a destination stays in the console'), which separates it from a write path. It does not, however, distinguish itself from the sibling page_alert_destinations.

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

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

Usage is only implied: the note that creation happens in the console signals this is a read-only listing, which is a useful boundary. There is no explicit 'use this when' guidance and no routing to the closely named sibling page_alert_destinations, which an agent would need to choose between.

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, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds genuine value beyond that by disclosing the deduplication intent, which is not expressible in annotations. However, it says nothing about result volume, pagination, or what a 'check' contains – though the output schema mitigates the latter.

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, no filler, and the usage trigger is front-loaded immediately after the resource statement. The opening fragment is slightly under-specified rather than padded, so brevity is well judged for a no-argument listing 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?

With zero parameters, an output schema, and full annotation coverage, the description only needs to establish purpose and calling context, which it does. The one remaining gap is that it never confirms the listing is unfiltered/complete, which matters for the duplicate-detection workflow it prescribes.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description's only free-text claim – the 'this workspace' scoping – is the sole implicit input context, and it is consistent with the empty 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?

"Checks in this workspace" names the resource and its scope but omits the verb entirely – it reads as a noun phrase rather than stating that this lists checks. The agent can infer the enumeration behavior from the tool name `list_checks`, but the description alone does not carry it. Sibling differentiation is partial: it implicitly contrasts with `get_check` (single check) and `create_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?

Explicitly states when to call it: before `create_check`, to avoid adding a duplicate check for an already-watched URL. That is a concrete, actionable trigger naming a specific sibling. It lacks any when-not-to-use guidance (e.g. after the set is known, or for large workspaces), so it falls 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add context — it does by disclosing provenance (checks in incident_mode review), sort order (pending first), and the downstream consequence of approving. It omits what is returned per proposal, but the core behavior is well covered.

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 the key scoping information front-loaded and no filler. The phrasing is telegraphic ('from checks in incident_mode review'), which costs a little readability but saves 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 with one parameter and no output schema, the description covers purpose and ordering but leaves the required slug undefined and gives no hint of the fields a proposal contains. Adequate but with a clear gap an agent will hit on the first call.

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

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

The single required 'slug' parameter has 0% schema description coverage and the description never mentions it at all. An agent must guess whether slug identifies a status page, an incident, or a check, so the description fails to compensate for the schema gap.

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 ('Drafts waiting for review from checks in incident_mode review') and adds ordering (pending first). It implicitly separates this list tool from the approve/dismiss siblings by describing the drafting state, though it never names those siblings.

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

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

Usage is implied: this is where you see proposals awaiting review, and 'Approving one publishes it as a status incident' gestures at the follow-up action. There is no explicit when-to-use/when-not statement and no named alternative such as approve_incident_proposal or dismiss_incident_proposal.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond enumerating fields that the output schema likely already documents—nothing about pagination, scope, or what is returned.

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 short and front-loads the resource name, but it is a field list rather than a purpose statement. It wastes its only content duplicating output fields instead of stating what the tool does, leaving it concise but under-specified.

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 zero parameters and an output schema present, the description needed only to state that this lists maintenance windows and clarify scope. Instead it spends its entire text on output-field names, so an agent gets no explicit indication of the tool's listing behavior or any filtering constraints.

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 input parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and nothing in the description contradicts or undermines that.

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 resource (maintenance windows) and enumerates its fields, but never states a verb or action such as 'list' or 'retrieve'. It effectively restates the tool name and output fields rather than articulating a distinct purpose, and gives no basis for distinguishing it from sibling list 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?

There is no guidance on when to use this tool versus alternatives like get_incident or list_checks, nor any note about scope, filtering, or prerequisites. The description provides no usage context at all.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact beyond the annotations: only 'enabled' regions are returned, which explains why results may be a subset. It says nothing about ordering, freshness, or whether regions can be disabled elsewhere.

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 short fragment with zero filler, and the key qualifier ('Enabled') is front-loaded. It is terse to the point of being a label rather than a sentence, but nothing wastes space.

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

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

This is a trivial zero-parameter read tool with an output schema, so most of the burden is lifted. Still, the description never says how the returned regions should be used (e.g. as inputs to create_check) nor what 'enabled' implies operationally, leaving a small but real gap for an agent navigating 30+ 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The listed fields (id, name, region) are redundant with the output schema, but they do no harm.

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 fragment 'Enabled probe regions' identifies the resource and implies a listing, and it signals a filter (only enabled regions). However, there is no verb and it largely restates the name plus return fields rather than stating what the tool does, so the agent must infer that it enumerates rather than, say, counts or configures.

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

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

There is no guidance on when to call this versus anything else, and no mention of how the returned region ids relate to other tools (e.g. region selection when creating a check). The agent gets no usage context beyond the 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds field-level behavior, notably the 'worst open incident status' aggregation and workspace scope, but does not discuss ordering or pagination.

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 sentence that front-loads the resource and then enumerates the useful fields. There is 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?

An output schema exists, so return values need not be explained in detail, and annotations cover safety. The description adds the workspace scope and key returned fields, though it could more explicitly distinguish itself from get_status_page.

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

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

The tool has zero parameters, so there is no parameter semantics to document. The schema is empty and fully described by its absence, matching the baseline for parameter-free tools.

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

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

It specifies the resource (status pages) and enumerates the attributes returned, including computed incident status. It does not explicitly contrast with get_status_page or create_status_page, so sibling differentiation is only implicit.

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 a listing operation via 'Status pages in this workspace', but gives no explicit when-to-use guidance or alternatives. An agent must infer that this is for browsing all status pages rather than retrieving a single page.

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 destructiveHint=true and idempotentHint=false, so safety is covered. The description adds a delete-intent guard ('Delete only when the user asked'), which is useful, but says nothing about irreversibility or what happens to member components when a group is deleted.

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, front-loaded with the operation and then conditional rules. The action enumeration is necessary because the schema has no enum, so nothing is wasted.

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

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

For a destructive, multi-mode tool with no output schema, the description omits the meaning of 'slug' and the side effects of delete on grouped components. Adequate to invoke correctly in the common case, but not fully complete.

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

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

With 0% schema coverage, the description carries the burden and mostly delivers: it supplies the action value set and which params each action requires. 'slug' is required but never explained, which is the one real gap.

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

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

States a specific verb set (create/update/delete) and resource (component group), which is clearly distinct from the sibling create_component/update_component tools. It doesn't explicitly say 'for groups, not individual components', but the resource naming does the differentiation work.

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 real exclusion rule ('Delete only when the user asked') and conditional requirements per action, which is unusually actionable. It stops short of naming alternatives for component-level operations, so it's clear context without a full when/when-not map.

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 idempotent=true and destructiveHint=false. The description adds meaningful behavioral context by stating that this is a replacement operation and that an empty list detaches all destinations, which is important for an agent 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?

The description is three short sentences with no wasted language. The main replacement behavior is front-loaded, followed by the id source and the empty-list edge case.

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 with annotations and no output schema, the description covers the core replace semantics and empty-list behavior. However, it leaves the required slug parameter unexplained and does not describe the response or confirmation behavior.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains destination_ids well, including that ids should come from list_alert_destinations and that an empty array detaches all, but it says nothing about the required slug parameter or its expected format.

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, 'Replace', and a precise resource, 'alert destinations attached to a status page'. It also names the related list_alert_destinations tool, making the write-versus-read distinction 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?

It explicitly tells the agent to use list_alert_destinations to obtain destination ids and explains that an empty list detaches all destinations. It does not discuss prerequisites or alternatives such as update_status_page, but the intended usage 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?

Adds real context beyond annotations: the side effects (emails subscribers, posts to Slack) and the state transition ('status resolved closes the incident'). This explains *why* destructiveHint=true. Doesn't mention irreversibility or that posted updates may not be retractable, which is the key risk of an externally-broadcast write.

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

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

Three tight sentences, front-loaded with the action and side effects, then the usage gate, then the status semantics. 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 destructive, externally-broadcasting write with zero schema documentation and no output schema, the description covers side effects and the usage gate but leaves the parameter contract and any reversibility/rate-limit info unaddressed.

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

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

Schema description coverage is 0% – all four required parameters (slug, public_id, status, body) are undocumented in the schema. The description only hints at the 'status' parameter (resolved behavior) and never explains slug/public_id, nor gives the allowed status values despite status being the pivotal field.

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

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

States a specific verb+resource ('Post an incident update') and immediately distinguishes itself from the sibling update_incident by disclosing that this is the subscriber-facing publish action (emails + Slack). An agent can tell it apart from update_incident without opening either schema.

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

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

Explicit gating condition: 'Run only when the user asked to publish this update in this conversation.' This is a strong when-to-use guard. It doesn't name update_incident as the alternative for non-publishing edits, so it stops short of 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?

Goes beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing that the call is asynchronous, that it queues work, and that it returns a job_id rather than the outcome. That is exactly the extra context an agent needs and isn't captured by the structured fields. It stops short of stating what a probe actually does or any rate/limit 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?

Three short sentences, front-loaded with the action, then the return value, then the follow-up call. No filler and nothing restated from the schema.

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

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

With no output schema, the description correctly supplies the return value (job_id) and the retrieval path, which would otherwise be missing. The only real hole is the input parameter's meaning, which neither schema nor description resolves.

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 0% for the single required parameter, so the description must compensate and does not: endpoint_id is never mentioned, and 'one check' actually conflicts with the parameter name. The agent is left guessing whether to pass a check ID or an endpoint ID.

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

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

States a specific verb and resource ('Queue a probe for one check'), and explicitly separates it from get_check_results, the tool that returns results. Slight friction: the description says 'one check' while the sole parameter is endpoint_id, leaving a small ambiguity about the resource identifier.

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

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

Tells the agent exactly what to do next when a result is needed: 'Call get_check_results with view status for the result; it is not included here.' That is explicit routing and an exclusion. It does not, however, say when to prefer this over get_check or other read tools beyond the result-is-separate point.

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 flag this as non-read-only and destructive, and the description adds important context beyond them: start produces a URL and OAuth should not be completed by the agent, while disconnect removes the connection and should be used only on user request. It does not describe permissions, reversibility, or error behavior, but the key action semantics are well disclosed.

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 short, front-loaded, and each sentence carries useful operational meaning. It moves directly from resource identification to action behavior, cautions, and the state-check alternative without 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 two-parameter tool with no output schema and existing destructive annotations, the description covers the critical action behavior, OAuth caveat, disconnect caution, and state alternative. The main missing piece is an explanation of the required slug parameter.

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 0%, so the description must carry parameter meaning. It explains the action parameter by describing start and disconnect behavior, including the critical OAuth caveat, but it never explains what slug refers to.

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 identifies the resource as a Slack connection for a status page and explains the two action behaviors: start returns a URL and disconnect removes the connection. It also distinguishes state lookup by pointing to get_status_page, though the opening phrase is noun-like rather than a direct verb statement.

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 explicit usage conditions: action start returns a URL and the agent should not complete OAuth; action disconnect should only be used when the user asked. It also names get_status_page as the place to check connection state, which is a clear alternative for a related need.

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 say non-read-only, non-idempotent, non-destructive. The description adds the key behavioral fact beyond them: the alert is 'real', i.e. it actually delivers a notification to a live destination, which is why the guard clause exists. It stops short of saying whether prior alerts are affected or what the response looks like.

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, action first then the safety constraint. Nothing wasted and no ambiguity.

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

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

For a single-parameter action tool with annotations covering the safety profile, this covers the essentials. The only real gap is sourcing destination_id, which is implied by 'existing' but not directed to a sibling listing tool.

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

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

Schema coverage is 0%, so the description must compensate. 'Existing destination' clarifies that the ID must reference a pre-created destination, but it doesn't say where to obtain that ID (e.g. list_alert_destinations) or the expected format.

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

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

States a specific verb and resource: 'Send a real test alert to an existing destination.' That is clearly distinct from list/page destination siblings, though the description never names those siblings 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?

'Run only when the user asked to send the test' is an explicit when-to-use gate that prevents unsolicited test alerts. It does not mention alternatives such as list_alert_destinations for finding a destination, but the core exclusion is 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful operational detail beyond that: enabled false pauses and true resumes; linking requires site_id, site_slug, and component_id together; incident_mode 'review' stores a draft for human approval; and request headers, body, and HTTP auth stay in the console. It does not cover permission requirements or rate limits, but it is a solid supplement.

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

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

The description is front-loaded with the core action, followed by compact guidance on partial updates, enabled semantics, linking, and console-only fields. Every sentence adds useful information without repetition, though it could be slightly tighter given the remaining parameter gaps.

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

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

For a 29-parameter mutation with no output schema and 0% schema description coverage, the description is incomplete: it misses semantics for the majority of parameters, provides no error or return behavior, and does not clarify many operational constraints. It covers key flows (pausing, linking, incident_mode) but leaves too much undocumented for an agent to call the tool confidently across all 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?

With 29 parameters and 0% schema description coverage, the description carries the full burden but only explains roughly seven parameters (enabled, site_id, site_slug, component_id, incident_mode, incident_auto_resolve, display_metrics). It also adds enum-like meaning for incident_mode, which the schema lacks, but many fields such as name, target, port, regions, dns_*, http_*, and endpoint_id are left undocumented.

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 'Update a check,' which states a clear verb and resource, distinguishing it naturally from siblings like create_check, delete_check, and get_check. It does not explicitly name or contrast those siblings, but the purpose 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?

'Pass only the fields to change' gives useful partial-update guidance, and the description explains the effect of enabled and the linking requirements. However, it never states when to use update_check versus alternatives such as create_check or get_check, nor does it list any exclusions or preconditions.

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

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

Annotations already state readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description usefully narrows the mutation to name and URL changes only, implying a partial, non-destructive update, but says nothing about permissions, what happens to unmentioned fields, or how null values behave.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity contributes to the missing parameter and usage detail.

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

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

For a mutation tool with zero schema description coverage, a required slug and component_id, and no output schema, the description is too thin. An agent still lacks the identifiers' meaning and the conditions for a successful update.

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 0%, so the description must carry parameter meaning. It maps 'rename' to name and 'URL' to url, but leaves the required slug and component_id entirely unexplained, including what they identify and how they interact.

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

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

States a specific verb and resource ('Rename a component or change its URL'), clearly distinguishing an update from create_component and delete_component siblings. It is clear but does not explicitly name those siblings or describe the full update scope.

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 on when to choose this over create_component, delete_component, or manage_component_group, and no mention of prerequisites such as required permissions or valid component identifiers.

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

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

Goes well beyond the annotations by disclosing real side effects: editing can email subscribers and post to Slack. Combined with annotations (destructiveHint=true, idempotentHint=true) and the guard against inventing statuses, an agent understands both the blast radius and the safety constraint before calling.

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, zero filler, and the most important constraint (side effects / only when asked) is front-loaded ahead of the update_id nuance and the status 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?

It covers the destructive/notification profile and one parameter, which matters for a 9-param mutation with no output schema. But it never explains how omitted/null fields behave, what body versus update_body targets, or how component_ids are applied, leaving real ambiguity before a destructive call.

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

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

Schema coverage is 0% across 9 parameters, so the description carries the full burden, yet it only explains update_id (edit a posted update instead of the incident) and gestures at status. body vs update_body, title, impact, component_ids, and slug vs public_id are all left undocumented.

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

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

Specific verb+resource ("Edit an incident") plus a useful disambiguation: with update_id it edits a posted update rather than the incident. That distinguishes the two behaviors without naming the sibling post_incident_update directly, so an agent still has to infer which tool posts versus edits.

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?

"Run only when the user asked" is an explicit precondition, and "Never invent a status the user did not ask for" constrains behavior. There is no explicit routing vs. post_incident_update for creating a new update, which is the main nearby alternative, so it falls short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds non-obvious side-effect context the annotations cannot express: notify_subscribers defaults to false and enabling it emails subscribers. It does not explain what happens to fields omitted from the request (left unchanged vs. cleared), which matters given the destructive hint.

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, zero filler, with the action front-loaded followed by the side effect and the usage gate. 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 9-parameter destructive mutation with no output schema, the description covers the riskiest default and the invocation gate but leaves partial-update semantics and most field formats undocumented. Adequate to call safely in the common case, incomplete for anything beyond setting notify_subscribers.

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 0% across 9 parameters, so the description carries the full burden, yet it only explains notify_subscribers' default and effect. Nothing is said about weekdays (integer array encoding), starts_at format/timezone interaction, duration_seconds, or the nested status_components shape.

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

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

The first sentence names a specific verb (update) and resource (maintenance window), which is unambiguous against siblings like create_maintenance_window and cancel_maintenance_window. It does not explicitly name those alternatives, but the verb+resource pairing is sufficient to distinguish.

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?

"Run only when the user asked to change this window" is an explicit precondition/exclusion that keeps the agent from proactively editing windows. It stops short of naming the sibling alternatives (create/cancel) for adjacent intents, so it is clear context rather than full when/when-not routing.

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

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

Annotations already disclose that this is a non-read-only, idempotent, non-destructive mutation. The description adds useful behavioral details beyond the annotations: custom_domain null removes the setting, internal visibility requires a password typed by the user, and passwords must never be invented or repeated. It does not detail broader authorization requirements or consequences for unspecified fields.

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 action is stated first, then fields and key constraints. Every sentence carries a constraint or semantic detail, with no filler.

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

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

For a 7-parameter mutation tool with no output schema and 0% schema description coverage, the description is fairly complete: it covers the main field semantics, the custom_domain removal behavior, and password safety rules. The main remaining gaps are the missing explanation of the required slug argument and the absence of allowed visibility values.

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 0%, so the description must carry parameter meaning. It helps for several fields, especially show_auto_detected, custom_domain null, and the password requirement for internal visibility, but it omits the required slug parameter and does not enumerate allowed visibility values or clarify null behavior for other fields.

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: 'Update a status page,' then enumerates the updatable fields. It is clear what the tool does, though it does not explicitly contrast itself with sibling tools such as create_status_page, get_status_page, or 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?

Usage is implied by the verb 'Update' and by conditional rules such as visibility internal requiring a user-entered password and custom_domain null removing the domain. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternative such as get_status_page or create_status_page.

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/idempotentHint/destructiveHint=false, and the description adds meaningful policy beyond that: this is a pre-creation gate and calls should halt once a cap is hit. It doesn't clarify what 'stop' concretely means (abort vs. report) or how cap breaches surface, keeping it just short of a 5.

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

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

The behavioral rule is front-loaded ('Call this before creating anything'), followed by a compact field enumeration and a stop condition. The inline comma list of ten fields is dense but each entry carries information given there is no output schema.

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

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

With no output schema, the enumeration of returned fields is exactly the return contract an agent needs, and workspace scoping plus the pre-creation gate are stated. What's missing is only edge behavior (what a cap breach looks like, units for min_interval_seconds) — minor for a zero-parameter read 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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to compensate for. The field list is about return values rather than inputs, which does not detract from this dimension.

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 resource (plan caps for this workspace) and enumerates exactly which caps are reported (probe_count, monthly_probe_quota, max_endpoints, etc.), so an agent knows this is a read-only quota/usage lookup. The tool name 'usage' alone is vague, but the description disambiguates it and clearly distinguishes it from the create_*/list_* siblings.

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

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

'Call this before creating anything' gives an explicit pre-flight trigger, and 'Stop when a cap is reached' defines a stopping condition. It doesn't name a specific alternative tool, but the sibling set of create_* tools makes the intended sequencing obvious.

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=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-destructive but not read-only operation. The description adds useful context by naming the record types inspected, but the "Check" phrasing reads as a passive read and the description never explains side effects (e.g., whether a successful check marks the domain verified) or what happens on failure.

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

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

A single, front-loaded sentence with zero filler; the verb and scope arrive immediately. It is efficient but so terse that brevity shades into under-specification rather than tight 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?

For a verification tool with no output schema, the description should convey what a pass/fail result looks like, whether checks are idempotent-safe to retry, and any propagation caveats. None of that is present, leaving the agent guessing about return semantics and failure handling.

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 single `slug` parameter has 0% schema description coverage, so the schema contributes nothing. The description partially compensates by tying the check to "a status page custom domain," implying the slug identifies the status page, but it never states this explicitly or explains format expectations.

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

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

States a concrete verb ("Check") and a specific resource ("CNAME and TXT records for a status page custom domain"), so an agent knows exactly what DNS verification work happens. No sibling tool overlaps this domain-verification role, so no differentiation is needed.

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 no when-to-use context: no prerequisite that the custom domain must already be configured on a status page, no note that DNS propagation may require retries, and no indication of when to call this versus inspecting the status page via get_status_page.

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