SolidPing

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

The description discloses behavior beyond the annotations: 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 the call requires the mcp scope and at least the user role. It does not cover rate limits, whether side effects are reversible, or how the returned config is normalized, which is what would earn a 4-5 here.

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 dense and well front-loaded: the core action and return value come first, then the workflow guidance, then the side effects and auth constraints. Four sentences of tightly packed secondary detail (placement inference, quorum semantics) make it longer than strictly necessary, but 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?

For a 16-parameter mutation tool with nested config, an output schema, the description still covers workflow (fetch schema, validate, create), side effects, failure modes, and permission requirements. It goes beyond the annotations rather than restating 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?

With 100% schema coverage the baseline is 3, but the description adds real semantic value. It spells out the paused-versus-running distinction, the conflict-on-duplicate-slug vs. update_check split, and the return shape (uid, slug, placement, resolved periods), which lets an agent reason about the effect of each parameter instead of having to infer it from the schema alone.

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

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

States a specific verb and resource — 'Create a new monitoring check' — plus what is returned (uid, slug, placement, resolved periods). This cleanly separates it from update_check, delete_check, and list_check_types in the sibling set.

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 with type when the config shape is unknown, then validate_check to dry-run before creating. It also names the alternative for the mutation path — a duplicate slug must go through update_check — and explains enabled:false 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?

With annotations already declaring a non-readonly, non-idempotent, non-destructive write, the description adds substantive behavior: slugs are never merged on conflict, only one page can be default and isDefault:true demotes the previous one, new pages are seeded with a 'Services' section and start enabled and public. It also discloses the auth requirements (mcp scope, mcp:read refused, user role), which is exactly the kind of context annotations cannot 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, no filler, with the core action and conflict rule front-loaded before configuration semantics and auth constraints. It is dense to the point of being a single wall of text, but nearly 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?

For a 13-parameter creation tool, the description covers the side effects, defaults, follow-up tools, and permission requirements an agent needs to commit the call. An output schema exists, so the return value needs no further explanation beyond the mention that the created page is returned.

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 still adds meaning beyond the schema for isDefault (the first page always becomes default, and setting it demotes the existing default) and for page initialization state, which the schema does not express.

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') plus what it returns. It is clearly distinguished from update_status_page and manage_status_page_section, which are named as the follow-up tools for later edits.

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

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

Explicitly routes the agent to manage_status_page_section for additional sections and update_status_page for later edits, and warns that duplicate slugs are rejected rather than merged. It stops short of telling the agent to call list_status_pages first to avoid a slug conflict, but the context is otherwise clear.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description goes beyond them with real consequences: check stops immediately, incidents resolved, scheduling jobs removed, historical results kept, tunneling checks refused. Auth requirements (mcp scope, user role, read tokens refused) are also disclosed. It stops short of describing irreversibility or error shapes, so a 4 rather than 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: effect first, then side effects and exclusion, then the alternative and the auth/return contract. No filler and no repetition of the title or annotations.

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

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

A destructive single-parameter tool with annotations and an output schema, and the description still covers side effects, refusal conditions, the preferred non-destructive alternative, authorization scopes, and the return shape. Nothing an agent needs before calling 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 identifier as UID or slug. The description repeats 'by UID or slug' without adding format or resolution rules, 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?

Opens with a specific verb and resource ('Soft-delete a monitoring check') and immediately scopes the identifier to UID or slug. It is clearly distinguishable from siblings like delete_status_page, update_check, and get_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 names the alternative ('use update_check with enabled:false instead') with the condition that selects it (stop without losing it). It also states an exclusion: a check other checks tunnel through is refused.

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 annotations: the soft-delete cascades to sections and resources, uploaded brand assets are permanently deleted, no undelete exists, and the required mcp scope and user role are stated. This gives an agent the destructive consequences and authorization prerequisites that the annotations alone do not 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?

The description is front-loaded with the destructive action and its consequences, then alternatives, return shape, and auth requirements. It is dense and largely waste-free, though the reference to non-existent sibling tools makes one sentence less useful than it appears.

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, cascade effects, irreversibility, alternatives, return value, and authorization requirements. For a destructive single-parameter tool with annotations and an output schema, this is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the identifier parameter is already fully documented as a UID or URL-friendly slug. The description restates that identifier accepts UID or slug but adds no new syntax, format, or validation 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 and resource (soft-delete a status page) and immediately clarifies scope: removal from API and public site, cascade to sections/resources, and brand asset deletion. It distinguishes the operation from update_status_page's enabled:false and from partial removal tools, so an agent can identify the action 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?

Provides explicit when/when-not guidance: no undelete, use update_status_page with enabled:false instead, and use section/resource tools for partial removal. However, the named partial-removal tools (delete_status_page_section, delete_status_page_resource) do not appear in the sibling set, which weakens the routing guidance slightly.

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 real value beyond them: the auth scope ('works with mcp:read tokens') and the conditional omission semantics (freshness and regionalIssue omitted when empty, incidents null when none). It stops short of covering cost/latency or how freshness is computed, so not 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 the purpose, then the routing rule, then output shape — no filler sentences. Slightly docked because the field-by-field return enumeration partially duplicates an output schema that already exists, even if the omission/null semantics within it are useful.

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

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

For a two-parameter read-only diagnostic aggregator with an output schema, this covers purpose, alternative, auth requirements, and edge-case shape of the response. An agent has everything needed to select and call it correctly and to interpret sparse results.

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 their own descriptions (identifier as UID/slug, recentResultsLimit as 1-20 default 5), so the schema does the work. The description only echoes 'recent raw results across regions' and adds no syntax or edge-case detail beyond it — baseline 3.

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

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

States a specific verb (diagnose/return) and resource (a single check's current state) and enumerates exactly what is bundled: status, recent regional results, active incident, last resolved incident. This makes it trivially distinguishable from list_results, list_incidents, and get_check 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 says to use it 'instead of chaining list_results + list_incidents' and names the triggering situation ('a human asks what's wrong with check X?'). The alternative and the condition that selects this tool are both stated outright.

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, but the description adds non-annotation context: the required token scope ('works with mcp:read tokens') and the opt-in extras model via with=. It does not cover pagination or response shape, though an output schema exists to do that.

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

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

Two sentences, front-loaded with the core action and lookup keys, then routing guidance and the read-only scope. No filler and every clause carries distinct 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 2-parameter read tool with full schema coverage, complete annotations and an output schema, the description supplies everything missing: sibling disambiguation, the escalation path to diagnose_check, and auth requirements. Nothing needed to invoke 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 both parameters carry examples and the full with= field list in the schema itself. The description's 'ask for extras with with=lastResult,lastStatusChange' restates the schema's enum-of-fields rather than adding new syntax or semantics, 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?

States a specific verb and resource ('Get a single check's metadata') plus the accepted lookup keys (UID or slug), and explicitly contrasts itself with diagnose_check and list_checks. An agent can distinguish it from all 22 siblings 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 explicit routing: use diagnose_check when you need a full triage briefing, use list_checks when searching by name or label. Both the alternative and the condition that selects it 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 cover read-only/idempotent, yet the description adds auth detail ('works with mcp:read tokens'), failure behavior ('unknown UID fails with an "incident not found" error'), event cap (50 most-recent), and notification ordering ('newest first') plus that an unknown include value is an error.

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 error case, then option behavior, then routing. It is dense — clauses like 'plus the check with with=check and up to 50 timeline events with with=events' stack qualifiers — but almost nothing is redundant.

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

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

Even though an output schema exists, the description tells the agent which optional data appears in the response and what can fail, which is everything needed to call it 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 coverage is 100%, so baseline is 3; the description goes beyond it by explaining the shape of the notifications list (one row per dispatch target with delivery status, channel and recipient, newest first) and how status/limit interact with include=notifications.

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 precise verb+resource and scope: 'Get a single incident by UID'. It immediately separates itself from list_incidents (search/filter) and diagnose_check (check triage), so an agent can choose 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?

Explicit routing: 'Use list_incidents to search and filter across incidents, and diagnose_check for a check's full triage briefing.' It also states the condition that selects this tool (known single UID) versus those 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, but the description adds useful auth context by noting it works with mcp:read tokens. It also discloses that include adds lists alongside page fields and that incidents can be filtered by state and active, though it does not mention rate limits or error behavior beyond the schema.

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

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

The description is front-loaded with the primary action and then explains the optional embedding and include behavior. It is appropriately sized for a six-parameter tool, though the phrase 'and return it' is slightly redundant and the include enumeration is dense.

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 annotations, full schema description coverage, and presence of an output schema, the description supplies enough context about retrieval scope, optional includes, and sibling alternatives. An agent has what it needs to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including with, include, state, active, identifier, and sectionIdentifier. The description restates the main parameter interactions but adds little beyond the structured field descriptions, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: fetch one status page by UID or slug. It also distinguishes this retrieval tool from list_status_pages and the manage_* mutation tools, so an agent can identify its role without opening the schema.

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

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

It explicitly routes browsing to list_status_pages and changes to manage_status_page_section, _resource, and _incident. It also explains when to use with=sections versus include lists, leaving little ambiguity about 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/idempotent/non-destructive, and the description adds real value beyond them: the auth requirement (works with mcp:read tokens) and the bucket-level fields each entry carries. The 'Returns {data: [...]}' note is partly redundant with the output schema, keeping 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 short sentences, front-loaded with the action and scope, then the domain concept, then return shape and auth. Every sentence carries information.

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

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

For a no-param, read-only list tool with an output schema and full annotation coverage, this is sufficient: scope, entry contents, auth precondition, and response envelope are all conveyed.

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 the baseline is 4; the description correctly says nothing about params and instead describes the entry fields, which is the relevant semantic information 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 (List) and resource (check groups) with scope (for the organization), and defines what a check group is, which distinguishes it conceptually from sibling list_checks. It stops short of naming the sibling it differs from explicitly.

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

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

The org-level scope and the definition imply when the tool is useful (browsing grouped checks for incident handling/dashboards), but there is no explicit when-to-use or when-not-to-use guidance relative to list_checks or get_check.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the description is not burdened with the safety profile. It still adds real context beyond structured fields: the pagination round-trip ("pass pagination.cursor back as cursor") and the auth scope ("works with mcp:read tokens"). The "Returns {data, pagination}" sentence is mildly redundant given an output schema exists.

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

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

Four tight sentences ordered by importance: what it is, filter scope, pagination mechanics, then sibling routing. No filler and nothing repeated from annotations.

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

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

For a read-only list tool with full schema coverage, an output schema, and rich annotations, nothing an agent needs is missing: purpose, filtering, pagination loop, auth scope, and alternatives are all present.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description's "filtered by name/slug substring, labels, or check group" merely paraphrases q, labels, and checkGroupUid and says nothing about `with` or `limit`, 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 ("List monitoring checks") and immediately scopes it to the organization with named filter dimensions. It explicitly distinguishes itself from two siblings by name (diagnose_check, get_check), 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?

States the positive case ("browsing or filtering a fleet of checks") and two negative cases with named alternatives: diagnose_check for single-check health, get_check when the UID/slug is already known. The selection rule is fully determined.

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, but the description adds useful context beyond them: the auth requirement ('works with mcp:read tokens') and the fact that samples are complete, valid configs safe to clone and modify. Minor redundancy in restating return shapes, which the output schema already 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?

Front-loaded with the core purpose and the branching instruction, with no filler sentences. It runs long in a single dense block and repeats the '{data: [...]}' shape twice, but every sentence carries usable guidance.

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

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

For a one-optional-parameter read tool with annotations and an output schema, the description covers purpose, sequencing, return content and auth. Slightly over-complete on return values that the output schema already specifies, but nothing an agent needs 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 parameter is already documented, but the description adds genuine semantics the schema lacks: the two distinct behaviors keyed on presence/absence of `type`, and what the returned entries contain in each mode (description, enabled state, period bounds, secretFields vs. samples).

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 all monitoring check types supported by this server') and immediately distinguishes the two modes: enumeration without arguments versus sample configs with `type`. The enumerated examples (http, tcp, dns, icmp, ssl) make it unambiguous versus siblings like list_checks or get_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 prescribes a call sequence: 'Call it without arguments first when you don't know what type to use', then 'Then call it with type=<chosen type>'. It also names the alternative behavior it replaces ('much more reliable than guessing field names'), giving the agent a reason to prefer this over trial-and-error with create_check.

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

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

Beyond the readOnlyHint/idempotentHint annotations it discloses the response shape ({data, pagination}) and a non-obvious operational caveat: the returned cursor is not read back on the next call yet, so paging forward requires narrowing since/until. That is genuinely useful behavioral context. It slightly restates the read-only safety profile, but the pagination limitation is the kind of detail 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?

Three sentences, none wasted: purpose and scope first, return/pagination caveat second, sibling routing third. Front-loaded and appropriately sized for a 7-param list tool.

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

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

Output schema exists and the description still summarizes the return envelope, plus filtering and alternatives. The one friction point is that the description calls the cursor unusable for paging while the schema presents it as a normal pagination cursor, leaving the agent to reconcile the two.

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 still adds filtering semantics (check, state, time range) and the critical guidance that the cursor parameter cannot currently be used to page forward, which contradicts the schema's cursor text and is important for 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) with scope: organization-wide, active or resolved, filtered by check/state/time. It explicitly names the two sibling tools it is not (diagnose_check, get_status_page include=incidents), so an agent can route 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?

Gives explicit alternatives with the condition that selects them: diagnose_check for one check's incidents plus current health, and get_status_page include=incidents for customer-facing entries. The read-only/mcp:read note also signals when the tool is unavailable or inappropriate.

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?

Goes beyond the annotations by describing the return envelope (data/pagination/window/effectiveFilter), the defaulting rules for periodType and periodStartAfter, and the token scope required ('works with mcp:read tokens'). The 'read-only' restatement is redundant with readOnlyHint=true, but the default-window logic and effectiveFilter behavior are genuinely new information.

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

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

Three sentences, front-loaded with purpose and the sibling route, then the return shape, then defaults. The defaults sentence largely duplicates schema text and could be trimmed, but nothing is padding in the harmful sense.

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, all-optional query tool with full schema coverage and an output schema, the description covers purpose, alternative routing, default semantics, and auth scope. An agent has everything needed to call it correctly on the first attempt.

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 each parameter, including the same periodType and periodStartAfter defaults the description repeats. The description adds little beyond the schema here, 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?

Opens with a concrete verb plus resource ('Query monitoring results (raw or aggregated)') and enumerates the filter dimensions. It explicitly names the sibling it is not (diagnose_check) and the scenario that selects that sibling, so an agent can route 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?

States positive use cases ('trend analysis or to inspect a specific window') and an explicit exclusion with the alternative ('For investigating a single check's current state, use diagnose_check instead'). Both sides of the when/when-not decision 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes beyond that with the ordering guarantee (newest first) and the token/scope requirement (mcp:read), though it says nothing about pagination or result limits for large orgs.

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

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

Two sentences, front-loaded with the action and scope, then the alternative-tool routing in a parenthetical. No boilerplate or restatement of the title.

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

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

An output schema exists so return values need no prose, and annotations carry the safety profile; the description still covers scope, ordering, auth tier and the sibling handoff. Nothing an agent needs to invoke this zero-arg 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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It confirms there is no filtering input by describing the call as returning every page in the org.

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") and the response envelope. It also names the sibling get_status_page for the singular case, so an agent can distinguish it from get_status_page without inspecting 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?

Explicitly routes the agent: use this for the full collection, use get_status_page when fetching one page by UID or slug, with a hint about with=sections/include=sections. The read-only token note adds a usability condition (mcp:read tokens) that further constrains when it will succeed.

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?

Substantial disclosure beyond annotations: customer-visible content warnings, subscriber notification with an hourly cap, webhook fanout for every action, append-only entries, PATCH semantics, audit retention on unpublish, and the required mcp scope plus user role. One defect holds it back: it justifies the destructive/non-idempotent hints with 'delete is one of its actions', yet no delete action exists in the enum, which could send an agent looking for one.

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, with the customer-facing safety warning placed before the mechanical action list. Most clauses earn their place; the sentence restating the annotations ('Annotated destructive and non-idempotent because delete is one of its actions') is both redundant with structured fields and factually wrong.

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, five-action mutation tool the description covers action semantics, side effects, auth requirements, and the read path, and an output schema exists so return values need no explanation. Nothing an agent needs to invoke an action 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 meaning the flat schema cannot: it maps parameters to the action that consumes them and clarifies that title/bodyMarkdown/severity are rendered to customers. It does not, however, explain that kind's four state-advancing values interact with the separate state parameter.

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

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

The first sentence names the specific resource (customer-facing status page incidents/publications) and explicitly contrast it with the sibling list_incidents, which returns internal incidents. Each action in the enum is then given a one-line meaning, so an agent can tell create vs publish vs unpublish apart without opening the schema.

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

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

It states which parameters each action needs (create: pageIdentifier+title; add_update: pageIdentifier+publicationUid+kind+bodyMarkdown; publish: incidentUid+pageIdentifier), and routes the agent to get_status_page include=incidents for reads. That is explicit when-to-use plus the alternative read path, with no inference required.

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

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

Beyond the annotations, the description explains why the tool is destructive and non-idempotent, clarifies that delete only unpins the resource and leaves the check/group untouched, and describes return behavior for create and delete. It also discloses scope and role requirements.

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 purpose and then proceeds action by action. Every sentence supplies actionable context about behavior, alternatives, or permissions, 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 mutation tool with nine parameters, three actions, and existing annotations and output schema, the description covers the missing behavioral context: action semantics, side effects, return shapes, authorization requirements, and the read alternative. Nothing essential for correct invocation is omitted.

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 the parameters, but the description adds action-dependent semantics: create requires exactly one of checkUid or checkGroupUid, update requires resourceUid and preserves omitted fields, and delete unpins. It does not add much beyond the schema for fields such as position, publicName, or explanation.

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

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

The description uses specific verbs ('pin, edit or unpin') and a precise resource ('a check or a check group') in a status page section. It also maps each action to its effect, making the tool clearly distinguishable from siblings like get_status_page and manage_status_page_section.

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 what each action does and names the alternative for reading resources: get_status_page include=resources. It also states the required mcp scope and user role, so an agent knows both how and when it may be used.

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

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

Goes beyond annotations by explaining what delete actually destroys ('every resource pinned in it'), what update preserves ('omitted fields are kept'), the return shapes for create/update/delete, and the auth prerequisites (mcp scope, mcp:read tokens refused, user role). This is materially more than the destructive/non-idempotent hints.

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

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

Front-loads the action multiplexing, then one clause per action, then the alternative-read tool, then the annotation rationale and auth constraints. No sentence is filler and nothing is repeated from the schema.

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

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

Despite six parameters, three actions, and destructive behavior, the description covers everything needed to invoke it safely: per-action requirements, destructive blast radius, return values, auth scope, and the read alternative. The output schema exists but the inline return shapes are a helpful bonus.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds conditional semantics the schema cannot express (name+slug required for create, sectionIdentifier required for update, omitted fields retained). 'position' is left entirely to the schema, which keeps this from 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?

States a specific verb set and resource: 'Create, update or delete a section of a status page', then enumerates each action. It clearly separates itself from sibling manage_status_page_resource (pinned resources vs sections) and points to get_status_page for reads.

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 per-action usage conditions (what is required for create vs update vs delete) and routes read-only needs to the sibling 'get_status_page include=sections'. The only exclusions are implicit, but the routing is explicit enough that an agent picks correctly.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds real behavioral context beyond them: nothing is persisted, `secrets` run empty (only names are passed), script executes as a SolidPing worker, fetch returns status/headers/first 16 KB, browser returns a selector-annotated tree, and the mcp:read token scope. These are the failure modes an agent would otherwise hit blindly.

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 point — dry-run before create_check, nothing saved — is front-loaded in the first sentence, and each following clause maps to a distinct parameter concern. It is dense rather than padded, though the semicolon-chained prose for the three kinds is a touch heavier than needed.

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 spelled out, yet the description still previews status/output/metrics per kind. With annotations covering safety, six parameters fully documented, and the secret-handling caveat surfaced, nothing an agent needs to call 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 coverage is 100%, so baseline 3 applies, but the description adds genuine nuance the schema only partly carries: `env` is plaintext while `secrets` only names parameters that execute empty — a distinction that changes how the agent should compose a call. The kind-mode behaviors are restated in prose rather than adding much new beyond the enum descriptions.

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

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

States a specific verb and resource — explore a target and dry-run a js check — and immediately scopes it as a non-persisting precursor to create_check. The three `kind` modes (script/fetch/browser) are named inline, so an agent can distinguish it from create_check, run_check, and validate_check 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 a clear when: test a check before create_check, without saving anything. That establishes the main alternative and the condition that selects it. It does not explicitly exclude the other near-siblings (validate_check, run_check, diagnose_check), which would be the only thing separating a 4 from 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?

The description adds substantial behavioral context beyond annotations: it explains that the run follows the normal result path and can open or resolve incidents, notes rate limits per check and per organization, and specifies required scope and role. It is consistent with readOnlyHint=false and destructiveHint=false.

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, then adds side effects, rate limits, return semantics, follow-up tools, and auth requirements without wasted wording. Each sentence carries actionable 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?

Given a mutation-style trigger with annotations, a full output schema, and a single well-documented parameter, the description is complete. It covers purpose, side effects, rate limits, auth requirements, output status meaning, and follow-up tools.

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

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

The input schema has 100% description coverage for the single identifier parameter, including UID and slug examples. The description does not add identifier syntax or interpretation beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description states a specific action and scope: run a check once, now, in every region, instead of waiting for the next scheduled period. This clearly distinguishes the tool from siblings such as list_checks, get_check, 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?

It names concrete trigger contexts (right after a fix, on a freshly created check) and directs outcome reading to diagnose_check or list_results. It does not explicitly state when not to use the tool, so it falls short of the top score.

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

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

Annotations are absent, so the description carries the full load and it does disclose the key traits: PATCH semantics with untouched fields preserved, plus an auth requirement that mcp:read tokens are rejected and user role is needed. That is useful context, but nothing is said about whether changes are validated or rejected on failure, whether updates are versioned/reversible, or what happens to incidents when a check is disabled. Satisfies the core disclosure bar without going deep.

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 with zero filler, front-loaded with the verb and semantics, then alternatives, then the prerequisite. Every sentence carries distinct 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?

Given a 16-parameter tool with a nested config object, a 100% schema, and an output schema, the definition is mostly complete, but the most complex parameters (regions, regionPool, regionCount, placement) have intricate behavior that is documented only in the schema. That is acceptable, but it leaves the description thin for a tool of this complexity and adds only a global PATCH rule rather than compensating for the interactions between placement parameters.

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

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

Schema coverage is 100%, so a baseline of 3 applies and the description correctly reports that only passed fields change and that enabled:false pauses. 16 parameters with rich per-parameter docs mean the description adds little beyond that global rule, so the baseline level 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 ("Update an existing check by UID or slug") and the observable outcome ("return the updated check"). It also explicitly distinguishes itself from create_check and delete_check so the agent can pick it out of a crowded sibling list 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?

Names the alternative tools explicitly (create_check to create, delete_check to remove) and gives a non-obvious routing rule: to pause without deleting, set enabled:false rather than calling anything else. This is exactly the when/when-not 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 annotations, the description discloses PATCH semantics, that omitted fields keep their current values, that slug collisions are rejected, that mcp:read tokens are refused, and that at least the user role is required. These are material behavioral and authorization details not captured by the structured annotations.

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

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

The description is compact and front-loaded with the core action, then adds semantics, alternatives, and authorization constraints without repeating schema field documentation. Every sentence carries useful 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 15-parameter mutation tool with full schema coverage, annotations, and an output schema, the description covers the key prerequisites and semantics an agent needs. Return-value details are omitted appropriately because an output schema exists.

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 15 fields in detail. The description adds useful global semantics about PATCH behavior and slug rejection, but it does not add field-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: update an existing status page by UID or slug, and return the updated page. It also distinguishes this tool from create_status_page and delete_status_page, so an agent can place it correctly among siblings.

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

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

It explicitly says when to use this tool versus alternatives: use create_status_page to make a new page and delete_status_page to remove one. It also states the precondition that the page must already exist, leaving little 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?

Goes well past the annotations: it explains the response contract (valid is false exactly when fields is non-empty; fields lists ALL blocking findings, not just the first; warnings never block) and states the auth requirement (works with mcp:read tokens). These are exactly the traits an agent cannot infer from readOnlyHint/idempotentHint 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 core action and tightly packed with the return semantics and usage rule. There is minor redundancy: 'a pure read, no side effects' largely restates the readOnlyHint/destructiveHint annotations, though the mcp:read token note in the same sentence adds new 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?

Given an output schema exists, the description could have stopped at purpose, yet it still clarifies how to interpret the returned fields — the highest-value ambiguity for a validation tool. Nothing needed 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 description coverage is 100%, so both parameters (type, config) are already documented with examples in the schema. The description adds the context that config is typically assembled by hand or adapted from a sample, but no format or syntax detail beyond the schema — the 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+resource ('Dry-run validate a check config') plus its scope ('without creating or changing anything'), which cleanly separates it from create_check/update_check in the sibling list. An agent can identify it 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?

Explicitly names the moment to use it ('before create_check when you've assembled a config from scratch or modified a sample') and names the sibling it precedes. The only mild gap is not naming update_check as a second caller, but the routing signal is unambiguous.

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