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

Annotations only cover readOnly/openWorld/idempotent/destructive hints, and the description adds substantial context beyond them: an enabled check starts on its next tick and opens an incident after its confirmation period, duplicate slugs are rejected with a conflict and never merged, and creation requires the mcp scope with at least the user role (mcp:read tokens refused). This is rich behavioral disclosure; it stops short of 5 only because rate limits or exact failure payloads are not described.

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

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

Front-loads the core action and return values in the first sentence, then layers prerequisites, lifecycle behavior, error semantics and required scopes in descending priority. Five sentences, no filler; each carries a distinct fact an agent needs.

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 16-parameter mutation with nested config, the description covers the gaps structured data cannot: scope/role prerequisites, duplicate-slug conflict behavior, the paused-creation path, and the recommended discovery/validation workflow. An output schema exists and describes return values, so the brief return summary is sufficient.

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

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

Schema description coverage is 100% and the schema already documents every parameter in depth, including placement/regions interaction, quorum rules and period ranges. The description reinforces 'enabled:false creates it paused' and the type/config dependency, but adds no syntax or format detail the schema does not already carry, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new monitoring check'), plus the scope of what is returned (uid, slug, placement, resolved periods). It explicitly names update_check as the tool for modifying existing checks, so an agent can separate it from its siblings without reading 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?

Gives explicit sequencing guidance: call list_check_types with the type first to get a working config shape, then validate_check to dry-run before creating. It also states the alternative (update_check) and the condition that selects it (changing an existing check), and explains the enabled:false escape hatch for creating paused.

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 concrete side effects and constraints: duplicate slugs are rejected with a conflict rather than merged, the first page auto-becomes default and isDefault:true demotes the previous default, every page is seeded with a Services section and starts enabled/public, and it requires the mcp scope (mcp:read refused) plus user role.

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

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

Four dense sentences, front-loaded with the core action and conflict behavior before the follow-up routing and auth requirements. No filler, though the auth sentence is somewhat appended rather than integrated.

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 already exists so return-value description is not needed, and the description covers the remaining gaps an agent would care about: conflict handling, default-page side effects, seeding, initial state, and authorization requirements.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters in detail, establishing a baseline of 3. The description adds only marginal parameter meaning (isDefault demotion semantics, default-enabled/public state) beyond what the schema and annotations already carry.

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 ('Create a new status page for the organization') with the return value named, and it distinguishes itself from siblings by pointing to manage_status_page_section and update_status_page for the follow-up operations it does not cover.

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 routes the agent to update_status_page and manage_status_page_section for later edits and section management, and the duplicate-slug rule implies this tool is only for first-time creation. There is no explicit 'do not use if the page already exists' exclusion, keeping it 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?

Goes well beyond the annotations (destructiveHint/idempotentHint) by enumerating exactly what happens: check stops, active incidents resolved, scheduling jobs removed, historical results kept. It also discloses the auth requirements (mcp scope, mcp:read refused, user role minimum) and the refusal case, which annotations cannot express.

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 outcome, then layers in the caveat and alternative. Every clause carries distinct information (side effects, refusal rule, alternative tool, auth) with no padding 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 detailed, yet the description still names them. Combined with side-effect disclosure, refusal semantics, alternative routing and auth preconditions, an agent has everything needed to 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 coverage is 100% and the single identifier parameter is fully documented with examples in the schema, so the description only restates 'by UID or slug'. It adds no syntax or format detail beyond the structured field, which is the expected baseline here.

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

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

States a specific verb and resource ('Soft-delete a monitoring check') plus the accepted identifier forms (UID or slug). It is clearly distinguishable from siblings like update_check and get_check, and 'soft-delete' signals the mutation semantics up front.

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 names the alternative ('To stop a check without losing it, use update_check with enabled:false instead') and states the exclusion condition (checks other checks tunnel through are refused). Both when-to-use and when-not-to-use are covered.

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 declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them: it discloses the soft-delete semantics, the cascade (sections and resources go with it), that uploaded brand assets are physically deleted, that there is no undelete, and the auth requirement (mcp scope, mcp:read refused, user role). This is exactly the additional context annotations cannot 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?

Front-loads the action and its cascade, then the alternative, then the return shape, then auth — every clause carries distinct information with no filler despite the length.

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 destructive scope, irreversibility, cascading effects, auth prerequisites, alternatives, and even the return value (redundant given the output schema, but harmless). Nothing an agent needs before invoking this irreversible operation is missing.

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

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

Schema description coverage is 100% and the single identifier parameter is fully documented in the schema, including the slug example. The description's 'by UID or slug' restates what the schema already says, adding no new syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Soft-delete a status page by UID or slug') and immediately distinguishes itself from siblings by naming update_status_page with enabled:false as the non-destructive alternative. An agent can identify this tool's role without opening any schema.

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

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

Explicitly states when-not to use it ('There is no undelete — use update_status_page with enabled:false') and routes partial deletions to section/resource tools. The only nit is that it names delete_status_page_section/delete_status_page_resource while the actual siblings are manage_status_page_section/manage_status_page_resource, but the intent is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds genuinely new context: the return envelope keys, that freshness and regionalIssue are omitted when empty and incidents are null when none exist, and the auth requirement ('works with mcp:read tokens'). That is exactly the kind of behavioral detail annotations cannot express.

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

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

Front-loaded with purpose, then the usage rule, then the return shape and auth note in a logical order. The return-shape sentence is dense with parenthetical qualifiers, slightly overlong, but every sentence carries distinct information with no filler.

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

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

An output schema exists, so the description is not obligated to explain return values, yet it briefly summarizes the envelope and its omission semantics. Combined with the usage rule and auth note, an agent has everything needed to invoke this correctly on the first try.

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

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

Schema description coverage is 100%, so identifier (UID or slug) and recentResultsLimit (1-20, default 5) are already fully documented in the schema. The description references 'check X' generically and adds no format, default, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (diagnose) plus resource (a single check) and enumerates exactly what it aggregates: current status, recent raw results across regions, active incident, and last resolved incident. It explicitly distinguishes itself from the aggregation siblings list_results + list_incidents, so an agent can separate it from the many list_*/get_* tools without opening a schema.

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

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

Gives an explicit when-to-use rule ('when a human asks "what's wrong with check X?"') and names the alternative it replaces (chaining list_results + list_incidents). The selection condition is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description reinforces rather than contradicts them. It adds value annotations don't carry: the tool 'works with mcp:read tokens', which tells the agent about auth scope — useful for a read-only agent. It does not, however, describe pagination, error cases, or what 'metadata' excludes.

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, zero waste: the core operation and lookup key come first, then the extras hint, then the alternatives routing. Each clause earns its place.

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

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

For a 2-parameter read tool with full schema coverage and an output schema (so return shape need not be explained), the description covers purpose, routing, and auth scope completely. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented with format examples in the schema. The description's mention of `with=lastResult,lastStatusChange` restates what the schema property description already spells out, adding no new syntax or defaulting semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get a single check's metadata') plus the lookup key ('by UID or slug'), which immediately separates it from list_checks and diagnose_check. An agent can identify this as the single-object retrieval tool without opening any schema.

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

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

Explicitly names two alternatives and the conditions that select them: diagnose_check for a full triage briefing, list_checks for search by name or label. No inference is required to route between the three.

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, yet the description still adds real behavioral context: unknown UIDs produce an 'incident not found' error, notifications are returned newest-first one row per dispatch target, and read access requires mcp:read tokens. It stops short of describing pagination or truncation behavior for timeline events beyond the 50 cap.

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

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

Front-loaded with the core operation, then qualification, then alternatives. The middle sentence is long and packs several clauses, but nearly every clause carries information an agent needs; little is 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?

Given an output schema already exists, the description need not explain return shapes, yet it still summarizes returns (number, state, timestamps, failure counts) and covers error behavior, auth scope, and the interaction among with/include/status/limit. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relational meaning the schema states only per-field: it explains that with=check/with=events are opt-in extras, that include=["notifications"] is filtered by status and capped by limit, and that events are capped at 50 most-recent. This ties the parameters together rather than restating them.

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 and scope: 'Get a single incident by UID'. It immediately distinguishes itself from the sibling list_incidents ('Use list_incidents to search and filter across incidents') and names the exact identifier type the tool consumes.

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 routes the agent to alternatives with conditions: list_incidents for search/filter over many incidents, diagnose_check for a check's triage briefing. It also states the failure mode for an unknown UID, so the agent knows what to expect when guessing a UID.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new context: the mcp:read token requirement and the behavioral effect of each include value (sections embed their resources; incidents are filtered by state and active). It stops short of describing pagination or error behavior for a missing identifier.

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

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

Front-loaded with the core action, then the modifier semantics, then sibling routing – a sensible order with no filler. The include parentheticals are dense, but each clause carries real information.

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

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

For a 6-parameter read tool with an output schema present, the description covers the modifier interactions, filtering semantics, and auth scope, so nothing essential is missing. Return-value documentation is correctly delegated to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns more by explaining what each include list actually returns (section metadata/display order, resources of sectionIdentifier, customer-facing incidents filtered by state and active) and by flagging the with=sections vs include=sections overlap.

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 (get one status page by UID or slug) and immediately distinguishes itself from siblings by naming list_status_pages for browsing and the manage_status_page_* tools for mutation. An agent can route correctly without opening any schema.

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

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

Explicitly names the alternatives and the condition that selects them: browse with list_status_pages, change sections/resources/incidents with the manage_* tools. It also states the read-token scope, so the when-to-use picture is complete.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the auth scope ("works with mcp:read tokens") and enumerating the per-entry fields (slug, rolled-up status, check count), giving useful behavioral context.

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

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

Three tight sentences, front-loaded with the action and scope, followed by definitional and auth context. No redundant or wasted text.

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 annotations covering safety, an output schema present, and zero params, the description leaves nothing an agent needs missing. It even names the return shape, which is a bonus rather than a necessity.

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 document; baseline 4 applies. The description correctly implies a no-input, organization-scoped call.

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

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

States a specific verb+resource ("List all check groups") and further defines what a check group is, distinguishing it from the sibling list_checks/list_check_types. An agent can tell exactly what this returns without opening the schema.

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

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

Usage is implied by the scope phrase "for the organization," but there is no explicit when-to-use/when-not guidance and the strong sibling alternatives (list_checks, list_check_types) are never mentioned. Adequate but with clear gaps.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context by stating it works with mcp:read tokens and explaining pagination via pagination.cursor. It does not cover rate limits or edge cases, but with annotations and an output schema, the added detail is solid.

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 purpose, then return/pagination, then usage guidance and alternatives. Four sentences with no wasted words, each earning its place.

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

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

Given six optional parameters, an existing output schema, and rich annotations, the description is complete enough. It covers filtering, pagination, sibling alternatives, and token scope; return structure is left to the output schema.

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

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

Schema description coverage is 100%, so all six parameters are already well documented. The description only summarizes filter categories ('name/slug substring, labels, or check group') and pagination, adding little syntax or meaning beyond the schema.

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

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

States a specific verb and resource ('List monitoring checks'), scope ('for the organization'), and optional filters. Distinguishes from siblings by naming diagnose_check and get_check, so an agent can tell it apart without opening schemas.

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

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

Explicitly says 'Use this for browsing or filtering a fleet of checks' and routes to diagnose_check for a single check's health or get_check when the UID/slug is known. This gives clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, but the description adds the auth requirement (works with mcp:read tokens) and the shape/contents of each return entry (description, enabled state, period bounds, secretFields). The return-shape detail partly duplicates the output schema, so this is strong but not purely additive.

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 key guidance (no-args-first, then type-scoped) is front-loaded and each clause carries information. It is somewhat dense and repeats the {data: [...]} return shape twice, but there is no filler.

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

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

With an output schema present, annotations covering the safety profile, and a single fully-documented optional parameter, the description provides everything an agent needs: both invocation modes, the recommended order, and the auth scope.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it explains that 'type' selects which type's ready-made sample configs are returned and that each sample is a complete, valid config to clone. That is more than the schema's bare example list conveys.

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

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

The description names a specific resource (monitoring check types) and clearly distinguishes its two behaviors: a no-argument listing of supported types versus a type-scoped return of sample configs. An agent can tell exactly what this tool does and how it differs from siblings like 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 sequencing rule: call it without arguments first when the type is unknown, then call it with type=<chosen type>. It also motivates the pattern (samples are reliable configs to clone rather than guessing field names), which is actionable when-to-use guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-obvious behavior: the cursor returned in the response is not read back on the next call yet, so advancing requires narrowing since/until, plus it discloses that mcp:read tokens suffice. Both are genuinely beyond what the structured fields convey.

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

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

Four sentences, purpose-front-loaded, and each block earns its place (filters, pagination caveat, alternatives, auth). The 'Returns {data, pagination}' clause mildly duplicates the existing output schema, which keeps it from a 5.

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

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

For a read-only, 7-param, zero-required list tool with an output schema, the description covers purpose, filters, pagination behavior, sibling routing, and auth scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents size, with, since, until, state, cursor, and checkUid in detail. The description only summarizes the filter axes (check, state, time range), which maps onto the schema without adding format or edge-case detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (internal incidents), plus scope: organization-wide, active or resolved, filterable by check/state/time. An agent can distinguish it from get_incident (single) and from the status-page tools without opening a schema.

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

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

Explicitly routes to alternatives with conditions: diagnose_check when you want one check's incidents plus current health in a single call, and get_status_page include=incidents for the customer-facing entries. This is when-to-use guidance naming the sibling that wins in each case.

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, non-destructive and closed-world, so safety is covered structurally. The description adds auth-specific detail the annotations do not carry ('works with mcp:read tokens') plus the defaultRegions payload, which is genuinely new behavioral context. Minor overlap with readOnlyHint keeps it from a 5.

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

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

Three tight sentences, front-loaded with what is listed, then the return shape, then the downstream consumer. Every sentence earns its place; the 'Read-only' clause is mildly redundant given readOnlyHint but is justified by the token-scope information it adds.

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

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

For a zero-parameter, read-only listing tool with annotations and an output schema, the agent has everything needed: what comes back, the meaning of the slugs, and where those slugs are consumed. Nothing required for correct invocation is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no syntax the description could add. It correctly spends its words on output semantics (slug/label/metadata, defaultRegions) instead of inventing parameter detail.

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

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

States a specific verb and resource ('List monitoring regions available to the organization') and grounds it with concrete slug examples (eu-west-1, us-east-1), so it is immediately distinguishable from sibling lists like list_checks or list_check_types. The return shape (slug, label, metadata, defaultRegions) further pins down exactly what is being listed.

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 routes the agent: 'Use these slugs in the regions array of create_check or update_check' names the consuming sibling calls and the exact argument they feed. There is no explicit when-not or exclusion, but the usage context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes further by disclosing defaulting behavior (periodType falls back to 'hour', periodStartAfter falls back to a window matched to periodType) and the auth scope (mcp:read tokens). It stops short of describing rate limits or exact aggregation semantics, which keeps it below a 5.

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

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

Front-loaded with purpose and routing before the return-shape and defaults detail. Minor redundancy: the periodType/periodStartAfter default rules are repeated from the schema descriptions, costing a little efficiency but not readability.

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

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

For a 10-parameter read tool with an output schema and full annotation coverage, the description supplies everything needed: filtering scope, sibling routing, fallback defaults, and the auth profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters. The description largely restates the periodType/periodStartAfter defaults that are already in the schema rather than adding new syntax or format meaning, so baseline 3 applies.

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

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

Specific verb (Query) plus resource (monitoring results) with scope detail (raw or aggregated) and filtering dimensions named. It explicitly distinguishes itself from the diagnose_check sibling, so an agent can select correctly without opening the schema.

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

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

States the intended use cases ('trend analysis or to inspect a specific window') and names the alternative with the condition that selects it ('For investigating a single check's current state, use diagnose_check instead'). When-to-use and when-not are both explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds crucial auth context: 'works with mcp:read tokens'. Also specifies ordering (newest first) and response shape {data: [...]}, going beyond what annotations provide.

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

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

Two tight sentences, front-loaded with purpose and return shape, second sentence routes to alternative. 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 parameterless list tool with an output schema, the description provides ordering, return structure, auth scope, and sibling routing. Nothing essential is missing.

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

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

Zero parameters, so baseline is 4. The description mentions that get_status_page accepts include/sections parameters, which implies this tool does not; this is useful but not a parameter explanation for this tool itself.

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

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

States a specific verb (List) and resource (status pages) with scope (in the organization) and ordering (newest first). Distinguishes from sibling get_status_page by contrast. An agent can identify the correct tool immediately.

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 names get_status_page as the alternative for a single page and hints that include/sections parameters are for that tool. No exclusions or edge cases like empty results, but the routing is clear and actionable.

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

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

Goes well beyond the annotations: it discloses the customer-visible blast radius of titles/bodies, that create/add_update/publish notify subscribers under an hourly cap, that every action hits webhook connections, that unpublish preserves rows for audit, and the exact auth requirements (mcp scope, mcp:read refused, user role minimum). This is unusually rich operational context for a 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?

The safety warning about customer-visible content is front-loaded, and every subsequent sentence is an action-to-parameter mapping rather than filler. It is dense and long, but nearly all of it earns its place; only mild compaction is possible.

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 5-action, 9-parameter mutation tool with an output schema and existing annotations, the description supplies everything else an agent needs: action routing, parameter binding per action, side effects, permissions, and audit behavior. Nothing material is left unspecified.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds real value by mapping parameters to actions (pageIdentifier+title for create, publicationUid for update, kind+bodyMarkdown for add_update, incidentUid for publish/unpublish) and by stating PATCH semantics and append-only behavior for add_update. It does not restate enum values, which the schema already documents.

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

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

States a specific verb (manage) and a precisely scoped resource: 'the customer-facing incidents a status page shows (publications)'. It explicitly distinguishes that resource from the internal incidents returned by list_incidents, so an agent can route correctly without opening schemas.

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

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

Enumerates each action with its required parameters (create, update with PATCH semantics, add_update append-only, publish relays an existing incident, unpublish removes while keeping the row for audit) and names the exact read companion: get_status_page include=incidents. It also names the alternative source for internal incidents (list_incidents), covering when-not-to-use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description goes further by explaining *why* (delete is one of its actions) and clarifying the blast radius — unpinning leaves the underlying check or group untouched — plus the return shape {deleted, identifier} and the auth refusal mode for mcp:read tokens. That is substantive context beyond structured 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?

Four dense sentences, front-loaded with the action semantics before the caveats, and no filler. It is on the longer side but each clause carries operational information (return values, scope requirement, role requirement).

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, three-mode mutation tool with an output schema available, the description covers action semantics, exclusivity rules, side effects, return shapes, and auth requirements. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema only hints at: exactly one of checkUid/checkGroupUid must be supplied for create, and resourceUid is required for update with omitted fields preserved. That ties parameters to action semantics usefully.

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

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

The description names a specific verb set (pin/edit/unpin) and the exact resource (a check or check group inside a status page section), then enumerates what each of the three action values does. An agent can distinguish this from manage_status_page_section and get_status_page without opening any schema.

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

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

It states the selecting condition for each mode of the single tool (create/update/delete), and explicitly routes the read case to a sibling: 'Read a section's resources with get_status_page include=resources.' Prerequisites are also given (mcp scope, user role).

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 and idempotentHint=false, but the description explains why (delete is one of the actions) and adds context annotations cannot: delete also removes every resource pinned in the section, update preserves omitted fields, and the exact return shapes. Auth requirements (scope and role) are disclosed as well.

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

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

Front-loaded purpose followed by one sentence per action, then sibling routing, annotation rationale, and prerequisites. Dense but every sentence carries distinct, load-bearing information with no filler.

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

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

For a multi-action mutation tool with an output schema, it covers the action semantics, conditional inputs, destructive side effects, sibling routing, and auth prerequisites. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so field meanings are already documented, but the description adds conditional requirements the schema cannot express — name/slug required only for create, sectionIdentifier only for update. It does not add format or example detail beyond what the schema provides, so it stops short of a 5.

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

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

Names the resource (status page section) and breaks the verb into its three concrete actions, specifying exactly what each produces. It also distinguishes itself from get_status_page, telling the agent this is the mutation counterpart to that read tool.

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

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

Spells out the trigger condition for each action (create requires name/slug, update requires sectionIdentifier and keeps omitted fields, delete removes pinned resources) and names the alternative for reading. It further states the access conditions — mcp scope required, mcp:read refused, at least user role — so the agent can pre-check eligibility.

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

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

Annotations already cover readOnly/idempotent/openWorld/destructive, yet the description adds real behavioral context: kind=script runs exactly as a worker would, secrets are supplied by NAME only and run empty, and kind=fetch executes server-side. These caveats materially affect how an agent constructs the call.

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

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

Dense but front-loaded: the purpose and no-save guarantee come first, then the kind-by-kind breakdown. Every sentence carries information relevant to invocation, though the kind explanations are somewhat tightly packed.

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 6-parameter, enum-bearing, nested-object tool with annotations and an output schema, the description covers the modes, the auth requirement, and the secrets caveat. Return shape is delegated correctly to the output schema, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the semantics of `env` (plaintext parameters) and the security-relevant nuance that `secrets` are given by name and run empty, which is the kind of detail an agent must reason about.

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 ('explore a target and test a js check') with the crucial scope qualifier 'without saving anything', and positions itself relative to create_check. An agent can distinguish it from create_check/run_check/validate_check without opening a schema.

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

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

Explicitly frames the tool as a pre-flight for create_check and states it is read-only with mcp:read tokens, which tells the agent when it is safe/appropriate. It does not explicitly contrast with sibling alternatives like validate_check or run_check, so it stops 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 only say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial extras: the run "can open or resolve an incident like any scheduled run" (a real side effect), rate limiting per check and per organization, the required mcp scope with mcp:read refused, and the minimum organization role.

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

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

Dense but front-loaded: purpose first, then usage, side effects, limits, return shape, and auth. Nearly every sentence earns its place, though the inline return-shape literal is partly redundant given a dedicated output schema exists, and the single unbroken block is less scannable than it could be.

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 non-idempotent action with incident side effects, the description covers the critical unknowns: side effects, rate limits, auth/scope requirements, and how to retrieve the eventual outcome. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the schema already explains the UID-or-slug identifier format with examples. The description adds no further parameter-level detail, so the baseline 3 applies.

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

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

Starts with a specific verb, resource, and scope: "Run a check once, now, in every region, instead of waiting for its next period." This clearly separates it from sibling scheduling/CRUD tools (create_check, update_check, list_checks) and from read-only outcome 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?

Explicitly names the trigger conditions ("right after a fix, or on a freshly created check") and routes the agent to alternatives for reading the outcome: "read the outcome with diagnose_check or list_results (a result with periodStart >= requestedAt)." Both when-to-use and where-to-go-next are given.

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

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

Annotations already cover readOnly/idempotent/destructive flags, but the description adds value beyond them: PATCH semantics (unspecified fields are untouched) and an explicit authorization gate (mcp scope required, mcp:read tokens refused, at least user role). These are operational facts 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?

Four tight sentences, front-loaded with the action and PATCH semantics, then alternatives, then the auth requirement. No filler or restated title.

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

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

For a 16-parameter mutation tool with full schema coverage, an output schema, and annotations, the description supplies exactly the missing pieces: mutation semantics, sibling routing, and permission requirements. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100% and each of the 16 parameters is documented in the schema itself, so the baseline is 3. The description only echoes one parameter (enabled:false to pause) and adds no syntax or interaction detail beyond the schema.

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

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

States a specific verb (update) and resource (check), names the two supported identifiers (UID or slug), and describes the PATCH-style mutation semantics. It is immediately distinguishable from create_check, delete_check and get_check by name in the same sentence.

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 routes the agent: use create_check to make one, delete_check to remove one, and set enabled:false to pause without deleting. That is a concrete when-to-use / when-not-to-use rule plus a named alternative for a common intent.

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: it discloses PATCH semantics (omitted fields retain values), the slug-collision rejection behavior, and required auth ('mcp scope', 'mcp:read tokens are refused', 'at least the user role'). The annotations only assert idempotent/non-destructive/closed-world; the description supplies the operational constraints an agent must satisfy 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?

Front-loaded with purpose and update semantics before alternatives and auth, so the highest-value information comes first. Dense but no sentence is filler; the auth/precondition clause is compressed into the final sentence rather than padded out.

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 15-parameter mutation tool, the description covers purpose, patch semantics, preconditions, failure modes (slug collision), alternatives, and authorization, while the output schema and per-parameter schema descriptions handle the rest. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully adds the update semantics for all 15 fields ('only fields you pass change, omitted fields keep their current values'), which is the single most important fact about how these parameters behave. It also clarifies that identifier accepts either a UID or a slug.

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 combination ('Update an existing status page') and immediately scopes the target as 'by UID or slug'. It also names the sibling tools for the adjacent operations (create_status_page, delete_status_page), so the agent can distinguish it from them without opening any schema.

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

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

Explicitly routes the agent: 'Use create_status_page to make a new page and delete_status_page to remove one instead.' It also states the precondition that the page must already exist and that a slug collision is rejected, which is exactly the when-not-to-use guidance an agent needs.

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

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

Beyond the readOnly/idempotent/destructive annotations, it adds that validation is a pure read with no side effects, that valid is false exactly when fields lists all blocking findings, that warnings never block, and that it works with mcp:read tokens. These details clarify behavior and auth requirements usefully.

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 purpose and usage, and each sentence carries useful information. However, the explicit return-value explanation is somewhat redundant because an output schema exists, so it is efficient rather than maximally lean.

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 validation tool with rich annotations, complete schema coverage, and an output schema, the description supplies purpose, usage context, safety behavior, and auth scope. Nothing essential for correct invocation appears missing.

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

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

Schema description coverage is 100%, so the schema already documents the required type and config parameters. The description adds only the framing of validating an assembled or modified config, without new parameter-level syntax or format detail, matching the baseline for high-coverage schemas.

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

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

The description gives a precise verb and resource: 'Dry-run validate a check config without creating or changing anything — a pure read, no side effects.' It clearly distinguishes validate_check from sibling mutation tools like create_check and update_check by emphasizing dry-run validation with no changes.

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 states when to use the tool: 'before create_check when you've assembled a config from scratch or modified a sample, to catch problems early.' This gives the agent a concrete pre-create validation workflow and names the sibling it should precede.

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