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

Goes well beyond the annotations: explains that an enabled check starts on its next tick and opens an incident after the confirmation period, that enabled:false creates it paused, that duplicate slugs are rejected with a conflict rather than merged, and that the call counts against a quota and needs a specific scope/role. Annotations only declare the generic non-read-only, non-idempotent profile.

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?

Leads with the core action and return shape, then layers prerequisites, alternatives, and side effects. Given 16 parameters and several side effects, the density is justified and no sentence 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?

With an output schema present the description needn't explain return values, and it still names the salient ones. For a complex multi-param mutation it covers prerequisites, alternatives, quota, and reversibility, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: enabled:false semantics (create paused), config-shape discovery via list_check_types, and the create-vs-update conflict behavior. It does not restate the many placement/period parameters, leaving those to 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 ("Create a new monitoring check") and even names the key return fields (uid, slug, placement, resolved periods). It clearly distinguishes itself from update_check, delete_check, validate_check and list_check_types by naming them with their roles.

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 routing: call list_check_types to discover config shapes, validate_check to dry-run before creating, update_check for existing checks rather than re-creating, delete_check to reverse. Exclusions and prerequisites (mcp scope, user role, MaxChecks quota) are spelled out.

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 it is a non-destructive, non-idempotent write. The description adds substantial behavior beyond that: duplicate slugs are rejected with a conflict and never merged, the first page becomes default and isDefault:true demotes the prior default, new pages are seeded with a 'Services' section and start enabled/public, and it is not quota-limited. This is strong, though it does not describe the returned page shape (an output schema exists, so that is acceptable).

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

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

Front-loaded with the core action and then pairs each behavior with the sibling tool that handles the alternative. It is a bit dense across several sentences but every sentence conveys actionable information rather than repeating the name.

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

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

With 100% schema coverage, an output schema, and annotations present, the description fills the remaining gaps: uniqueness enforcement, default-page demotion, seeding behavior, reversibility, quota, and auth requirements. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds real meaning: it clarifies slug uniqueness semantics (conflict, never merged) and isDefault demotion behavior, which the schema only partially conveys. It does not elaborate on the many optional fields, but the schema handles 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?

States a specific verb and resource ('Create a new status page for the organization') and explicitly differentiates from siblings by naming manage_status_page_section and update_status_page as the tools for later section/page changes. An agent can distinguish this from update_status_page and delete_status_page 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?

Gives explicit routing: use manage_status_page_section to add sections, update_status_page to edit later, and delete_status_page to reverse. It also states prerequisites (mcp scope, at least user role), so when-not conditions 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?

Adds substantial context beyond the destructiveHint/idempotentHint annotations: immediate halt, active incidents resolved, scheduling jobs removed, historical results retained, permanence with no undelete, and freed MaxChecks quota. It also discloses auth requirements (mcp scope, mcp:read refused, user role required), which no annotation covers.

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 effect of the call is front-loaded, followed by side effects, the refusal case, permanence, and the alternative. Every sentence carries operational information; nothing is padding.

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 the safety profile and an output schema covering the response, the description fills the remaining gaps: side effects, irreversibility, quota impact, permissions, and failure modes. Nothing an agent needs to decide or call 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% and the single parameter already documents UID-or-slug format with examples. The description's "by UID or slug" merely restates the schema, adding no new syntax or validation 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 ("Soft-delete a monitoring check") plus the accepted identifier forms (UID or slug). It is clearly distinguishable from siblings such as get_check, update_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?

Explicitly names the alternative and the condition that selects it: "To stop a check without losing it, use update_check with enabled:false instead." It also documents a refusal case (checks that other checks tunnel through), so an agent knows when this call will fail.

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 annotations by disclosing that destruction is permanent with no undelete, that sections/resources are removed, and that uploaded brand assets are deleted. It also states the required mcp scope and minimum user role, which are critical operational constraints.

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

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

The destructive consequence and identifier are front-loaded, followed immediately by the safer alternative and partial-deletion alternatives. Despite its length, every sentence carries decision-relevant information for a destructive operation.

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 destructive annotations, a fully described single parameter, an output schema, and the tool's cascading deletion behavior, the description covers the important operational and safety context. Auth requirements and irreversibility are included, leaving no material gap for correct invocation.

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

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

The schema already documents the single identifier parameter at 100% coverage, including UID-or-slug semantics and an example. The description restates that identifier may be a UID or slug but adds no further syntax, validation, or edge-case guidance 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 the specific action (soft-delete a status page) and identifier types (UID or slug), plus the cascade scope. It clearly differentiates this destructive full-page deletion from sibling tools that delete only sections or resources.

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 to use update_status_page with enabled:false instead when the goal is merely taking a page down without destroying it. It also directs partial removal to delete_status_page_section or delete_status_page_resource, so the agent has clear 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds auth scope ('works with mcp:read tokens') and, more valuably, discloses output-absence semantics (freshness/regionalIssue omitted when empty, incidents null when none). It does not mention cost, latency, or result-volume limits for the multi-region aggregation, which is the one remaining behavioral gap.

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

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

Three sentences, each doing distinct work: what is returned, the sibling alternative, and null/omission semantics plus auth. The payload contents are front-loaded before the usage rule.

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; the description still pre-empts the confusing part of the response (omitted vs null fields) and states the auth tier. For a 2-parameter read aggregation tool, 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%, with identifier's UID-or-slug format and recentResultsLimit's range/default fully documented in the schema, so baseline 3 applies. The description adds nothing about either parameter beyond the implicit notion of targeting one check.

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') and resource ('a single check's current state') and enumerates exactly what is aggregated: status, raw results across regions, active incident, most recent resolved incident. It is also distinguishable from siblings list_results and list_incidents, which it explicitly folds together.

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 routing rule: 'Use this instead of chaining list_results + list_incidents when a human asks "what's wrong with check X?"'. Both the alternative and the selecting condition are named, leaving nothing 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/non-destructive, and the description reinforces this with auth-level detail the annotations cannot express: it works with mcp:read tokens. It also discloses the opt-in 'extras' expansion behavior, though it does not describe payload shape or size limits.

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

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

One dense, front-loaded sentence chain with zero filler: core purpose first, then extras, then alternative routing, then the auth note. Every clause carries information 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?

An output schema exists so return values need no explanation, annotations cover the safety profile, and both parameters are fully documented. Combined with explicit sibling routing, 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% and both parameters carry detailed descriptions, including the enum-like list of allowed 'with' values. The description's 'identifier takes either' and its 'with=lastResult,lastStatusChange' example largely restate the schema, so it adds little semantic value beyond it.

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

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

Specific verb and resource ('Get a single check's metadata') plus an explicit identifier scope ('by UID or slug'). It names the two siblings it is not (diagnose_check, list_checks), so an agent can select it without opening another 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 routing: use diagnose_check for a full triage briefing and list_checks to search by name or label. Both alternatives come with the condition that selects them, leaving nothing 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 readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: the unknown-UID error, the 50-event cap, notification rows being newest-first and capped by limit, and the mcp:read token requirement. That is substantive disclosure an agent cannot infer from 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?

The identifying constraint (UID not slug) and the error behavior are front-loaded, and every sentence carries routing or option information. The middle sentence is long and stacks several modifiers (include, status, limit, newest-first, per-target rows), which slightly slows parsing but is not padding.

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 fetch with an output schema, annotations, and full parameter documentation, nothing an agent needs to call it correctly is missing: key format, optional expansions, notification filtering, caps, and failure mode are all covered.

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 a baseline of 3 applies; the description earns the extra point by explaining what the parameters mean semantically — include=["notifications"] yields one row per dispatch target with delivery status, channel and recipient — which enriches the schema's terser wording rather than repeating it.

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

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

States a specific verb and resource (get a single incident), and immediately disambiguates the key lookup key: 'by UID (not by slug)'. It also distinguishes itself from list_incidents and diagnose_check by name, so an agent can route 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 names the alternatives and the condition selecting them: list_incidents for searching/filtering across incidents, diagnose_check for a check's full triage briefing. The error path (unknown UID fails with 'incident not found') tells the agent what a wrong selection looks like.

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, closed-world, so the bar is lower; the description still adds real context: mcp:read token scope, that with=sections embeds nested sections and their resources, that include returns filtered incident publications, and that an unknown include value is an error. It doesn't discuss pagination or failure modes beyond the include error, keeping it 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?

Front-loaded with purpose and efficient overall, but the middle sentence enumerating include values in prose is verbose and duplicates the schema enumeration. Slight redundancy, no wasted framing.

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, return shape needn't be described; annotations cover safety and the description covers auth scope, embedding behavior, and sibling routing. 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 description coverage is 100%, so baseline is 3. The description's prose about with/include/state/active largely restates what the schema already documents (including the sectionIdentifier requirement for include=resources), adding little semantic depth beyond 'identifier takes either'.

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 one status page') plus identifier flexibility (UID or slug), and explicitly distinguishes itself from list_status_pages for browsing. An agent can tell instantly this is the single-record read.

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?

Names the alternatives and the conditions selecting them: list_status_pages for browsing, manage_status_page_section/_resource/_incident for changes. It also gives intra-tool guidance (when to use with=sections vs include, and the rule not to combine them), leaving nothing 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 read-only, idempotent, non-destructive behavior, but the description adds useful context beyond them: it returns every group in one unpaginated response and works with mcp:read tokens. It also notes the fields each entry carries, though it does not cover rate limits or failure modes.

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 primary action and scope, then adds only useful details about group semantics, return shape, pagination, and auth. Every sentence contributes without 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?

With zero parameters, rich annotations, and an output schema, the description supplies everything an agent needs to call this tool correctly: scope, return behavior, auth requirements, and the fact that no input is required. No important context 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. The description correctly states that it takes no parameters, which matches the empty input schema.

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

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

The description gives a specific verb and resource ('List all check groups for the organization') and clarifies what a check group is, including that it bundles related checks. This distinguishes it implicitly from check-level siblings like list_checks, but it does not explicitly name when another list tool would be preferred.

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 concept: an agent can infer this is the tool for enumerating check groups. However, there is no explicit comparison to alternatives such as list_checks or list_check_types, and no guidance on when not to use it.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, but the description adds useful context beyond them: filters combine with AND, the response shape is {data, pagination}, and pagination.cursor should be passed back as cursor. It also discloses the auth requirement ('works with mcp:read tokens'), which is exactly the kind of operational detail annotations do not cover.

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: purpose and filter behavior first, then return/pagination mechanics, then sibling routing, then auth context. Every sentence adds useful information for selecting or invoking the 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?

Given six optional parameters, full schema coverage, an output schema, and rich annotations, the description covers everything an agent needs: filtering semantics, pagination, when to choose this tool versus alternatives, and the auth scope. No material gap remains.

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 adds meaningful cross-parameter semantics: filters for name/slug substring, labels, and check group combine with AND. It also explains the pagination cursor flow, though it does not describe the 'with' parameter or limit defaults beyond what the schema already says.

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') and scopes it to the organization, with optional filters clearly named. It distinguishes itself from sibling tools like get_check and diagnose_check by explaining the browsing/filtering use case.

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 to use this for browsing or filtering a fleet of checks, and names alternatives: diagnose_check for investigating one check's health, and get_check when the UID or slug is already known. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the returned envelope {data: [...]} in both modes, the fields per entry (description, enabled state, period bounds, secretFields), and the fact that samples are complete valid configs. However, it restates the read-only guarantee in the closing sentence ('works with mcp:read tokens'), which is partly redundant with the annotations, and adds no pagination or ordering limits.

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

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

Front-loaded with the tool's purpose, then the two modes in call order, so an agent can stop reading after the first clause. It is dense but nearly every sentence adds routing or return-shape information; the closing auth sentence is the one part that earns little given readOnlyHint is already set.

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, yet the description still usefully pre-summarizes both return shapes and the secretFields/key fields per entry, and it covers the auth requirement. For a single optional-parameter read tool with full annotations, nothing an agent needs in order to call it or interpret results is missing.

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

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

Schema coverage is 100% and the schema already documents the optional `type` string with examples, so the baseline is 3. The description earns above that by explaining what the parameter semantically switches on — it returns the sample configs of that type rather than the type metadata, and it names the fields returned in the unfiltered case, which the schema does not.

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 monitoring check types supported by this server') and explicitly covers both call modes: bare enumeration vs. type-filtered sample configs. The named examples (http, tcp, dns, icmp, ssl) and the mention of 'ready-made sample configs' let an agent distinguish it from siblings like list_checks or 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?

Gives an explicit two-step workflow with the condition that selects each step: 'Call it without arguments first when you don't know what type to use' then 'call it with type=<chosen type>'. It also justifies the choice ('much more reliable than guessing field names'), which steers the agent away from an inferior alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavior: pagination cursor semantics, that order=asc always returns a cursor, that rows younger than 5s are held back, and the mcp:read token requirement. It stops short of describing rate limits or error behavior, but carries substantial beyond-annotation 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?

Front-loaded with purpose, then pagination, then alternatives. It is a dense single paragraph but every sentence contributes; slightly heavier than ideal but 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 and the description nonetheless previews the return shape ({data, pagination}, cursor meaning), covers pagination and ordering semantics, and names alternatives. Nothing a caller needs to invoke 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; the description adds value by stating filters combine with AND, explaining cursor round-tripping, and clarifying that order=asc upgrades cursor meaning to 'strictly after.' These go beyond the schema text and help correct invocation.

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 internal incidents'), scopes it to active or resolved, and enumerates filter dimensions. It explicitly distinguishes itself from events ('It lists new incidents only; changes to existing incidents are events'), so an agent can tell it apart from siblings like get_incident and diagnose_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 routes to alternatives: 'Use diagnose_check for one check's incidents plus current health in one call, and get_status_page include=incidents for the customer-facing entries.' It also names the exclusion (events endpoint for changes), giving clear 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 readOnly, idempotent, non-destructive and closed-world, so the safety bar is pre-met; the description adds the auth detail that it "works with mcp:read tokens," which is real operational context not in the annotations. It also discloses the result envelope (data plus defaultRegions), though that partly duplicates the output schema.

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

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

Three sentences, front-loaded with what the tool is, then return shape, then how to use the output, then auth scope. No filler, and the downstream-use instruction comes before the least-important token 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?

Since an output schema exists, the return-value sentence is technically redundant, but everything an agent needs — purpose, token requirement, and how to apply the slugs — is present. Nothing material is missing 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 there is nothing to disambiguate and the baseline is 4. However, the description spends a sentence describing the return payload rather than parameter behavior, so it adds no semantic value on this axis.

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

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

Specific verb+resource ("List monitoring regions available to the organization") with concrete slug examples (eu-west-1, us-east-1). It also distinguishes scope: org-visible regions plus the org's defaultRegions set, which no sibling tool returns.

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 downstream use: "Use these slugs in the regions array of create_check or update_check," which tells the agent exactly why it would call this before those mutation tools. It doesn't name an alternative listing tool, but none exists among the siblings, so the guidance is effectively 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 still adds value by disclosing the required token scope (mcp:read) and the default-resolution behavior when periodType/periodStartAfter are omitted. It does not go further on result volume or pagination behavior beyond what the schema's cursor/size fields imply.

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 filtering capability, followed by the alternative and defaults, then the token requirement. Efficient, though the default-fallback sentence largely repeats the schema text for periodType and periodStartAfter, costing a little redundancy.

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

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

With an output schema present, return values need not be explained, and the description covers purpose, alternative, defaults, and auth scope for a 10-parameter optional-filter tool. Minor gap: it doesn't characterize aggregation semantics (e.g. what raw vs hour rollups mean for interpretation) beyond naming them.

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

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

Schema description coverage is 100% and it already documents every parameter including enums, ranges, and the default fallback rules. The description's restatement of the periodType and periodStartAfter defaults is duplication rather than added meaning, 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 (query/list) and resource (monitoring results), plus the dimensions it can be sliced by (check, type, status, region, period type, time range) and the raw-vs-aggregated distinction. It explicitly names the sibling it is not (diagnose_check), so an agent can route between them 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?

Gives positive use cases (trend analysis, inspecting a specific window) and an explicit alternative with the condition that selects it: 'For investigating a single check's current state, use diagnose_check instead.' That is a concrete when/when-not routing rule, not implied guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is largely covered. The description still adds real context beyond them: the newest-first ordering and the fact that an mcp:read token suffices, which tells the agent about auth requirements. Minor redundancy in restating read-only 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?

Two sentences, both front-loaded: the core behavior first, then the routing/alternative and auth note. No filler, no restating the title.

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

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

With no parameters, a present output schema, and rich annotations, the description supplies everything needed to invoke the tool, including where to go if a filtered fetch is required. It stops short of mentioning result size or pagination behavior for large organizations, a small remaining gap.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a 0-param tool is 4. The description correctly doesn't invent parameters and instead points to the sibling that accepts filtering/closing arguments.

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 every status page in the organization") plus ordering ("newest first"), immediately separating it from get_status_page. An agent can tell from the first clause what it returns and how it differs from the sibling that fetches a single 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?

Explicitly names the alternative (get_status_page), the selector for it ("by UID or slug"), and even the argument form needed to pull contents (with=sections or include=sections). This is when-to-use and when-not-to-use guidance in a single sentence.

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: discloses subscriber notifications with an hourly cap and webhook fanout for create/add_update/publish, append-only narrative entries, audit retention after unpublish, PATCH semantics on update, and the required mcp scope plus org role. The only imprecision is the claim that 'delete is one of its actions' when the enum exposes unpublish rather than delete, but the destructive/non-idempotent annotations themselves are not contradicted.

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 resource identity and the safety warning before enumerating actions, then closes with side effects and auth. Dense but every sentence carries operational information an agent would otherwise have to guess.

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?

Return values are covered by the output schema, so the description correctly spends its budget on side effects, permission requirements, append-only semantics and per-action argument requirements. Nothing needed to invoke a destructive multi-action tool 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 would be 3, but the description adds a per-action parameter map (pageIdentifier+title for create, publicationUid for update, kind+bodyMarkdown for add_update, incidentUid+publicationUid for unpublish) that the schema—whose only required field is action—does not encode. It also clarifies that publish templates the title from the page.

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 specific resource (customer-facing status page incidents/publications) and the exact verb per action (create, update, add_update, publish, unpublish), including the parameters each requires. It explicitly distinguishes itself from list_incidents, which returns internal incidents, so the agent can tell the two apart 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?

Every action carries its use case and required arguments, and the description names the alternative path for reading publications (get_status_page with include=incidents). It also states when-not conditions via the warning that titles/bodies are customer-visible and must never contain probe output, error strings, hostnames or IPs.

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: it explains why destructive/non-idempotent applies (delete is one of its actions), guarantees the underlying check/group is untouched, states the return shape for delete, and documents the mcp scope plus user-role requirement. The remaining gap is minor since annotations already carry the safety profile.

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 verb set and the three action branches in tight sentences; the trailing auth/scope sentence is useful but slightly dense, and the return-shape detail partially duplicates the 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?

For a nine-parameter, three-mode mutation tool this covers the decisions an agent must make: which branch to invoke, which identifiers each branch needs, side effects, permissions, and where to read the current state.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by stating action-conditional requirements (resourceUid only for update, checkUid/checkGroupUid mutual exclusivity for create) and partial-update semantics that the schema itself does not encode.

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

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

Names a concrete resource (a check or check group pinned in a status page section) and enumerates the three operations with their distinct semantics, so it is clearly separable from sibling tools like manage_status_page_section and get_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?

Gives explicit per-action conditions (create pins exactly one of checkUid/checkGroupUid; update requires resourceUid and keeps omitted fields; delete unpins) and routes the agent to get_status_page include=resources for reading instead.

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: discloses that delete cascades to 'every resource pinned in it', that update preserves omitted fields, the return shapes per action, and the exact auth requirements (mcp scope; mcp:read tokens refused; minimum user role). This is exactly the kind of consequence and permission detail an agent cannot infer from destructiveHint alone.

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

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

Front-loaded with the action enumeration, then requirements, then return values, then auth. A few phrases are redundant ('and returns it' twice) and the sentence explaining why it is annotated destructive/non-idempotent partly restates structured data, but nothing 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?

For a mutating multi-action tool with six parameters, the description covers mode selection, conditional requirements, destructive cascade, return shape, an alternative for reads, and auth/role gating. Nothing an agent needs in order to call it safely is missing; an output schema exists so return values need no elaboration.

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 baseline is 3, but the description adds conditional requirements the schema cannot express: name and slug are required only for create, sectionIdentifier only for update, and omitted fields are retained on update. That materially improves correct invocation.

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 and resource ('Create, update or delete a section of a status page') and then disambiguates the three modes by action value. It also names the sibling read path (get_status_page include=sections), so the tool is distinguishable 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?

Gives an explicit alternative for the read case ('Read a page's sections with get_status_page include=sections') and per-action prerequisites. It does not route the related-but-different 'pinned resources' concern to manage_status_page_resource, which a sibling tool covers, so the guidance is clear but not exhaustive.

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 behavioral detail beyond the annotations: nothing is persisted, secrets resolve to empty values (a non-obvious and important caveat), env is plaintext, and the timeout default/max is 30s. It also names the auth scope (mcp:read tokens). The return-value recount partially duplicates the existing output schema.

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

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

Front-loaded with purpose and the create_check relationship, then organized mode-by-mode. Sentences are dense but each clause carries information; only the 'Reaches the URL or script target you name' line is close to 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 six-parameter, three-mode tool with an output schema, this covers everything an agent needs: mode semantics, per-mode parameter applicability, secret handling, timeout bounds, and auth scope. Errors and non-http URL handling are the only untraced corners.

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 bar is the baseline of 3, and the description exceeds it by explaining the cross-parameter rule: the other params apply only to their kind (script/env/secrets/timeout for script; url for fetch and browser). That conditional mapping is not expressible in the flat 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 (probe/explore) and resource (target), then enumerates the three distinct modes (script/fetch/browser) with what each returns. It explicitly positions itself against create_check, so an agent can distinguish it from the sibling 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 a clear when-to-use: testing a js check before create_check, with an explicit 'without saving anything' exclusion. It does not, however, contrast with the closely related run_check or validate_check siblings, which an agent must resolve on its own.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, but the description adds context the annotations cannot: rate limits per check and per organization, that the run goes through the normal result path and can open or resolve an incident, the queued region-status semantics, and the exact auth requirements (mcp scope; mcp:read tokens refused; user role required). This is rich behavioral disclosure consistent with the annotations.

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

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

It is front-loaded with the core action and flows logically into side effects, rate limits, outcome reading, and auth. It is dense with several parentheticals, but each sentence carries distinct, non-redundant information; slightly more compression would earn 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 mutation-like trigger tool with an output schema, the description supplies everything an agent needs beyond the structured fields: when to call it, side effects on incidents, rate-limit behavior, region status semantics, where to read the result, and permission prerequisites.

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 (UID or slug, examples, length bounds). The description adds no parameter-level syntax or constraints beyond what is already structured, 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?

A specific verb and resource with exact scope: run a check once, now, in every region, contrasted with waiting for its next period. An agent can distinguish this from sibling tools like get_check or list_results 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 when to use it (right after a fix, or on a freshly created check) and names the alternatives for reading the outcome (diagnose_check or list_results, with the periodStart >= requestedAt discriminator). Nothing is left to inference about choosing this tool over a scheduled run or a read tool.

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

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

The description adds substantial behavior beyond the annotations: PATCH semantics, in-place modification, no quota consumption, reversibility, and required mcp scope plus user role. These details are directly useful for safe invocation and are consistent with the readOnly=false and destructive=false annotations.

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

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

The description is front-loaded with the core action and scope, then covers alternatives, side effects, and auth requirements in a compact form. Every sentence contributes useful operational context for a 17-parameter mutation 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?

Given the rich input schema, output schema, and annotations, the description supplies the remaining high-value context: PATCH behavior, safety, quota impact, reversibility, and authorization. Nothing essential for correct tool selection or invocation is missing.

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

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

Schema coverage is 100%, so the individual parameter descriptions already carry most semantics. The description still adds meaningful cross-parameter behavior by stating PATCH semantics: only passed fields are modified and all others remain unchanged.

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 an existing check by UID or slug and return the updated check. It also explicitly distinguishes this tool from create_check and delete_check, so an agent can identify its role among siblings without inspecting 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?

It gives explicit alternatives: create_check for new checks, delete_check for removal, and enabled:false for pausing without deleting. That covers the main decision points an agent needs before choosing this tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is partly pre-covered; the description still adds substantial context: PATCH semantics for omitted fields, reversibility by re-updating with previous values, the required mcp scope (mcp:read refused) and minimum user role. The only gap is that it doesn't note side effects of toggling isDefault/visibility on other pages.

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 mutation and its identifier, then partial-update semantics, error cases, alternatives and auth in a tight progression with no filler. It is dense with clauses, but each sentence carries distinct operational information.

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

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

With 15 parameters, an existing output schema, and rich annotations, the description covers everything an agent needs before calling: identity resolution, partial-update contract, failure modes, sibling routing, reversibility and authorization. Return-value details are correctly 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 coverage is 100%, so baseline is 3; the description earns an extra point by explaining that only supplied fields change and omitted ones retain current values — a semantic not derivable from the schema of 15 optional properties plus one required identifier. It doesn't add per-field details beyond the schema, which already documents enums, defaults and limits.

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 ("Update an existing status page by UID or slug and return the updated page") with the identifier form stated up front. It explicitly names the sibling tools it is not (create_status_page, delete_status_page), so an agent can route without opening another 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 both when to use (page must already exist, PATCH-style partial update) and when not to (use create_status_page for new pages, delete_status_page to remove). It also names a concrete failure condition — a colliding slug is rejected — which an agent needs to avoid a wasted call.

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, yet the description still adds value: it discloses the auth scope ('works with mcp:read tokens') and explains that valid=false corresponds exactly to a non-empty, complete fields list while warnings never block. That is behavioral context an agent would otherwise have to infer.

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 read-only guarantee is front-loaded and every sentence carries information about behavior or routing. There is mild redundancy between 'pure read, no side effects' and the closing 'Read-only: works with mcp:read tokens', but the second sentence adds the token scope.

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 operation's semantics, safety profile, auth requirement, and the create_check workflow. With an output schema present it didn't need to explain returns, and what it does say about valid/fields/warnings is a useful supplement rather than a gap-filler.

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 schema already documents 'type' with examples and describes 'config' as check-specific. The description adds no meaning about either parameter, so the baseline 3 applies; the nested config object remains generic in both places.

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 ('Dry-run validate a check config') and immediately scopes it as a non-mutating operation. The contrast with create_check makes it clearly distinguishable from the mutating sibling.

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

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

Gives an explicit condition ('Use this before create_check when you've assembled a config from scratch or modified a sample'), naming both the alternative and the trigger. It does not address why one would choose this over run_check or diagnose_check, but the dry-run framing implies that division.

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