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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description's only added signal is 'Permanently', which reinforces irreversibility. It says nothing about cascade effects (sharing, published links, child pages), permissions required, or whether the deletion is recoverable.

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

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

A single short sentence with zero padding, and the destructive character is front-loaded in 'Permanently'. It is efficient, though its brevity borders on under-specification.

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

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

The annotations carry the destructive/idempotent profile and there is no output schema to explain, so the safety essentials are present. However, for a destructive mutation with an undocumented required parameter, the description omits authorization needs, recovery options, and side effects on published or shared artifacts.

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

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

Schema description coverage is 0%, and pageId carries no description in the schema. The description does not explain the identifier's format or where the agent obtains it, so it fails to compensate for the documentation gap on the single 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?

States a specific verb and resource ('Permanently remove a page'), and the word 'permanently' implicitly separates it from unpublish_page. It never names a sibling, so an agent must infer the boundary between deleting and unpublishing on its own.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as unpublish_page or update_page. The adverb 'permanently' hints at irreversibility but does not tell the agent when this tool is the right choice over its siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description still earns credit for disclosing what actually gets destroyed (private viewing sessions) and the recovery path (authorized people can reopen the page), which is real context an agent cannot infer from the annotations. It stops short of noting that the operation targets a single page or that it is not idempotent in practice.

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

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

Two short sentences with no filler, and the core effect is front-loaded before the mitigating detail. Nothing here is redundant with the name or title.

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

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

For a destructive mutation with no output schema, the description covers the effect and the recovery behavior adequately, and annotations cover the danger. It is incomplete on the revision/precondition mechanics that determine whether the call succeeds, which matters for a non-idempotent operation.

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

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

Schema description coverage is 0% for both required parameters, so the description carries the full burden and largely fails. It never mentions pageId (only implicitly via "sessions" and "the page"), and expectedRevision — a concurrency token that will cause failures if stale — is completely unaddressed.

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

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

The description names a specific verb ("Invalidate") and a specific resource ("current private viewing sessions"), which is far more precise than the tool name alone. It does not, however, explicitly differentiate itself from siblings like update_page, unpublish_page, or set_page_sharing, which also affect page visibility.

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

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

There is no statement of when to call this versus alternatives such as unpublish_page or set_page_sharing, and no prerequisites (e.g. ownership or edit permission on the page). The second sentence describes a consequence of calling it, not a condition for calling 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?

The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It does usefully enumerate what comes back (status, version, URL), but says nothing about behavior for a missing/invalid pageId or any auth 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?

A single front-loaded sentence with zero filler that names the resource and the returned fields immediately.

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

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

For a simple single-parameter read tool with readOnlyHint coverage and no output schema, stating the returned fields is largely sufficient. Only error/nonexistent-page behavior and pageId provenance are left unaddressed.

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

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

There is exactly one parameter, pageId, with 0% schema description coverage, so the description carries the full burden of explaining it. 'One page' only restates that a page is targeted and gives no hint about the id's format, source, or validity.

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 ('Get') and resource ('one page') plus the exact fields returned (status, version, URL). The 'one page' phrasing implicitly separates it from the list_pages sibling, though it does not name alternatives outright.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as list_pages or get_page_sharing. An agent must infer from the name and the word 'one page' that this is the single-item lookup.

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, so safety is covered by structured data. The description contributes some behavioral value by describing the returned content (who can open, expiry date), which is useful given the absence of an output schema, but it says nothing about auth requirements, permission preconditions, or error behavior.

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

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

A single tight sentence with the key output information front-loaded and zero filler. Nothing wasted.

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

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

For a simple one-parameter read tool with annotations covering safety and no output schema, the description is close to sufficient - it tells the agent what comes back. It falls short on the parameter's expected value, auth/permission context, and when to reach for it over set_page_sharing.

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?

There is 1 parameter with 0% schema description coverage - pageId carries only type/minLength in the schema, and the description never mentions it or its expected format. The name is largely self-explanatory, but the description does not compensate for the documentation gap.

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

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

States a specific verb (Get) and resource (page sharing) and even enumerates what the answer contains: who can open the page and expiry. This distinguishes it implicitly from the write-side sibling set_page_sharing, though it never names that sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the natural alternative set_page_sharing (to modify sharing) or get_page. Usage is only inferable from the verb 'Get'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the output is a 'reviewed prompt and static HTML starter,' which hints at content shape, but it doesn't disclose pagination, catalog size, or failure modes. A 3 is appropriate given annotations carry the heavy lifting.

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

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

A single tight sentence covering both modes and the switching condition, front-loaded with the list action and ending with the discovery hint. No wasted words.

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

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

For a 2-param read-only tool with no output schema, the description is adequate for the main use cases. But it leaves the 'version' parameter unexplained and doesn't describe the return shape (the catalog format, what a recipe object contains), which matters more because no output schema exists to fill that gap.

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

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

Schema description coverage is 0%, so the schema only gives types and constraints (recipeId pattern/maxLength, version integer). The description explains the semantic effect of omitting recipeId and that recipeId selects one recipe, which is genuinely useful. It does not explain the 'version' parameter at all, leaving a real gap. Baseline lift from 0% coverage is offset by the undocumented version param.

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

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

The description clearly states a dual purpose: list the recipe catalog, or retrieve one reviewed prompt and static HTML starter by recipeId. This distinguishes it from publishing siblings (publish_html, publish_presentation) and page-record getters (get_page). However, it doesn't fully separate itself from get_page, which also retrieves an artifact, so it's not a 5.

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

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

It gives one condition: 'Omit recipeId to discover the catalog.' That tells the agent how to switch modes but doesn't state when to use this tool vs get_page or the publish tools, nor any prerequisites or exclusions. Implied usage rather than explicit guidance.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds that results span published, offline, and platform-taken-down artifacts (i.e., not just live content) and that pagination continues via nextCursor. It stops short of stating default result count or ordering, which the schema partially 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?

Two sentences, no filler, with the search scope front-loaded and pagination as the closing instruction. Every clause carries information the 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 not be explained, and the description covers scope, search keys, and pagination. The only gap is that 'platform-taken-down' has no counterpart in the status enum (published/unpublished), leaving the default filtering behavior slightly ambiguous.

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 limit, query, cursor, and status are already fully documented; the baseline is 3. The description only loosely reinforces query ('title or page ID') and cursor ('nextCursor') without adding format or edge-case meaning.

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

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

States a specific verb pair ('search and page through') and a specific resource ('the current user's ... artifacts') with the searchable keys (title or page ID) named inline. It is clearly distinguishable from single-item siblings like get_page, though it never names an alternative 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?

Usage is implied rather than stated: the mention of title/page ID search and 'Follow nextCursor to continue through large libraries' tells the agent when this tool applies, but there is no explicit when-to-use/when-not guidance and no alternative tool is referenced.

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 declaring non-readOnly, non-idempotent, non-destructive, the description still adds meaningful behavior: it returns a stable URL and discloses that omitting sharing defaults to private-to-owner, plus that access can expire. That default-state disclosure is genuinely useful beyond the annotations.

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

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

Three front-loaded sentences that lead with purpose and the returned URL, then the default and the option space. They earn their place, though the final sentence is dense and slightly compacted.

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 no output schema, it covers purpose, return value, default access, and the full sharing option space. It stops short of stating auth/permission needs or reversibility, but is otherwise sufficient to invoke 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 67% and nested sharing detail is spread across a large oneOf, so the description earns its place by synthesizing the restricted mode as combining domain, specific-email, and password access plus optional expiration. It adds the default-selection logic for the sharing param, though html and title gain little.

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 (Publish) plus resource (complete static HTML document) and it even states the return (stable URL). It doesn't name any sibling such as publish_page or publish_presentation to differentiate, but 'static HTML document' implicitly scopes it against those page/presentation 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 gives usage context for the sharing option (omitted = private, choose public or restricted) and the default behavior, but there is no explicit when-to-use-this-vs-a-sibling guidance or prerequisite/auth requirements. The usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the page returns at its existing URL, which is genuinely useful context, but says nothing about permissions, what happens if the page is already published, or whether prior content/settings are preserved.

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

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

A single short sentence with the action front-loaded and no filler. Nothing to trim and nothing buried.

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

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

For a one-parameter tool whose annotations already cover the safety profile and which has no output schema, the description covers the essentials. The remaining gap is the undocumented pageId and the undefined behavior when the page is already published.

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?

There is one required parameter (pageId) with 0% schema description coverage, so the description carries the burden of explaining it and does not. 'Page' implicitly maps to pageId, but no format, ID convention, or source of the ID is given.

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 phrase ('Bring ... back online') plus the resource ('page') and a scope detail ('at its existing URL'), so the action is unambiguous. It does not name siblings such as publish_html or publish_presentation, but 'page' vs 'html' vs 'presentation' is readable from the resource word.

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 condition is implied by 'unpublished page', i.e. use this when a page is currently offline, which implies unpublish_page is the inverse and no other sibling fits. There is no explicit statement of when-not to use it or what alternatives exist.

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 the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real pipeline detail: sanitization, validation, persistence, access-control and CSP application, plus the returned viewer URL. It stops short of stating duplicate/re-publish behavior, but this is well above the annotation baseline.

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

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

Purpose is front-loaded in the first sentence, and the procedural visual-QA guidance that follows is dense but task-relevant. The middle visual-QA paragraph is long and somewhat repetitive about re-rendering, costing a point, but every section carries operational weight.

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 write tool with no output schema, the description supplies the return value (viewer URL), the pre-step (get_recipe), the QA workflow, and the sanitization/access-control behavior. The nested sharing modes are left to the schema, which is acceptable at 75% coverage, but a brief note on the default private behavior would have completed 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 75%, so the schema already documents most parameters, including the nested sharing object. The description only alludes to parameters obliquely ('declared desktop canvas' implying aspectRatio, 'applies access controls' implying sharing) without adding syntax or constraints. 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 (create/publish) and resource (HTML presentation deck), enumerating artifact types (slides, pitch deck, keynote) that make the target unambiguous. It does not explicitly contrast with siblings publish_html or publish_page, so it is clear but not sibling-differentiating.

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

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

Gives a concrete required precondition (call get_recipe with recipeId "presentation-deck" first) and a conditional path for when rendering tools are unavailable. However, it never routes the agent among the actual sibling publish tools (publish_html, publish_page), so alternatives within the toolset remain unaddressed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the agent knows this is a destructive, non-idempotent write. The description adds useful semantics not in the schema ("Restricted methods are OR alternatives"), but never explains the destructive scope — whether existing recipients/passwords are replaced wholesale — or the revision-conflict behavior.

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

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

Three short sentences, front-loaded with the primary action and no wasted words. Efficient, though the terseness leaves unexplained surface area in a very complex 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 tool with an elaborate nested policy schema and zero property descriptions, the description covers the main branches (modes, OR semantics, revision) but omits expiresAt, password action semantics, and emailDomain behavior. No output schema exists, so return values need no explanation, keeping it marginally adequate.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does: the three modes map to policy.mode, the OR rule maps to the restricted methods object, and the revision hint maps to expectedRevision. However, it adds nothing about expiresAt, the password set/keep action, emailDomain, or the recipients cap, leaving much of the large oneOf schema uninterpreted.

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 action ("Choose... access") over a specific resource, enumerating the three access modes (owner-only/private, public, restricted). An agent can tell it is the mutating counterpart to get_page_sharing, though the resource (a page's sharing policy) is implied by the tool name rather than the description.

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?

"Use the revision returned by get_page_sharing" establishes a clear prerequisite and names the sibling that must be called first, giving real workflow context. It stops short of stating when-not to use it or how it relates to update_page / publish_page.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false-ish behavior for reads, and destructiveHint=true; the description adds genuinely new context by stating the page is not deleted and the shareable URL is preserved, which tells the agent the operation is state-toggling and link-stable. It doesn't cover permission requirements or the already-unpublished case, but the added side-effect detail exceeds what annotations 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?

A single front-loaded sentence with no filler; both clauses (offline, non-destructive, URL stable) carry information and the core action leads the sentence.

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

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

For a one-parameter tool with no output schema, the description covers the essential action and its two most important non-effects. Minor gaps remain around required permissions and behavior when the page is already unpublished, but nothing critical 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?

One parameter (pageId) with 0% schema description coverage, so the schema alone gives no guidance. The description refers to 'a page' but adds no format, ID source, or scope detail beyond the parameter name; low-coverage schemas normally demand compensation the description does not supply.

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: 'Take a page offline' names the exact operation on a page. It implicitly distinguishes from siblings by negating deletion ('without deleting it') and from update_page by noting the shareable URL is untouched, though it never names publish_page/delete_page directly.

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 negation clauses (not deleting, URL unchanged) imply the intended scenario — temporarily removing content from public view while preserving links — but no explicit when-to-use trigger or named alternative (delete_page, update_page) is given. Usage must be inferred from the contrast with deletion.

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

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

Annotations already declare write (readOnlyHint=false), non-destructive, and non-idempotent, so the safety profile is covered. The description usefully adds that the shareable URL is preserved and that the page body is wholesale replaced, but it omits authorization requirements, conflict/versioning behavior, and what happens to the prior HTML.

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

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

A single front-loaded sentence with no filler — the replacement semantics and URL-preservation behavior come first. It is tight, though arguably under-sized for a mutation tool with undocumented parameters.

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

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

For a non-idempotent write tool with no output schema and 0% schema description coverage, the description is too thin: it does not cover permissions, whether the HTML must be a full document, size limits, or the result of the call. It leaves more open than it answers.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full documentation burden. It only indirectly gestures at `html` ('new static HTML') and `pageId` ('a page'), and never mentions the optional `title` parameter or format constraints on the HTML.

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 (replace/update) and resource (a page) plus the payload type (static HTML), so an agent can tell it apart from publish_page, unpublish_page, and delete_page. It stops short of explicitly contrasting itself with siblings like publish_page, which would have pushed it to a 5.

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

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

There is no guidance on when to use this tool versus publish_page, publish_html, or unpublish_page, and no stated prerequisites (e.g., whether the target page must already be published). The title hints at 'published page' but the description itself provides no selection criteria.

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