Dotsy

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: returns per-adapter reports plus a proposalEtag, nav declines may carry nextStep (e.g. mega-menu → edit fragments/header.html), and it must wait on a pending requiredDecision. That is meaningful context beyond the structured hints, though it doesn't cover rate limits or the 409/proposal-exists path beyond the param.

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 telegraphic sentences that front-load the core action, then return shape, then the decision-gating constraint. Dense but every clause carries information; the terse style borders on cryptic but wastes little.

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 complex 7-param tool with a nested options object and no output schema, the description does address both the return payload (per-adapter reports, proposalEtag) and the blocking requiredDecision state. It is largely complete, with the main gap being the relationship to the apply/revert siblings.

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

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

Schema description coverage is 86%, so the schema already documents nearly every parameter (full, site, context, options.*, guestToken, refreshProposal). The description adds almost no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (propose/analyze) and resource (nav wiring + blog collectionization) scoped to an imported mirror, and marks it as a draft/opt-in proposal, which distinguishes it from adapt_site_apply. The jargon 'collectionization' is a minor clarity cost, and it doesn't explicitly name its sibling apply/revert tools.

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

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

'draft, opt-in' and 'wait for mirror-vs-editable answer if requiredDecision pending' imply a pre-apply workflow, but the description never names adapt_site_apply or adapt_site_revert as the next/alternative steps, nor states explicit when-not conditions. Usage context is implied rather than spelled out.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing that one undo covers the whole apply, that a repeat apply is refused until revert/force, and that queued applies are polled to completion. These are exactly the behavioral traits an agent needs before mutating.

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, action and scope front-loaded, followed by the undo/refusal guardrail and the polling behavior. No filler or repetition of schema content.

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 7-parameter mutation tool with no output schema, the description supplies the missing operational picture: what is changed, the undo model, the refusal-and-force escape hatch, and how queued applies complete. Nothing essential to 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 carries the parameter documentation and the baseline is 3. The description nevertheless adds cross-parameter meaning: it explains the force/revert relationship and the undo lifecycle that frames ifMatch and adapters, which the schema only states locally.

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 (Apply) and resource (the adapt proposal/draft), then enumerates the concrete effects: wiring nav into the menu store and/or rewriting the blog index to a live <dotsy-collection>. This clearly differentiates it from adapt_site_analyze (which produces the proposal) and adapt_site_revert (which undoes it).

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 real when-to-use context: a second apply is refused until adapt_site_revert or force, and the force param description itself says 'Prefer adapt revert first'. It does not explicitly route the agent to dryRun or analyze in prose, but the conditions around refusal and undo are stated concretely.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: 'Atomically' discloses all-or-nothing semantics, the parenthetical enumerates the exact scope of mutation, and 'the last' implies only the most recent apply is revertible — a meaningful non-idempotency constraint.

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

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

A single sentence, front-loaded with the atomic-restore action and the target, with the scope enumeration in a compact parenthetical. No filler or restated title.

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

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

For a destructive mutation with no output schema, the description covers what gets restored and that the operation is atomic, and annotations carry the safety signals. It omits the failure mode when no prior apply exists and whether the revert itself can be undone, which keeps it short of full completeness.

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 site, context, and guestToken are all documented in the schema itself. The description adds no parameter-level detail (e.g., which site scope the revert targets), so the baseline 3 applies.

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

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

States a specific verb (restore/revert) and precisely scopes the resource: everything the last adapt_site_apply wrote, with an enumeration of the artifacts (fragments, menu doc, index, member configs, routes). This clearly distinguishes it from sibling adapt_site_apply and from the narrower revert_change.

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

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

The phrase 'the last adapt_site_apply' implies the usage context (undo the most recent apply), but the description never explicitly states when to use this versus revert_change, discard_drafts, or what happens if no prior apply exists. Usage is inferable but not spelled out.

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

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

Annotations already declare it is a non-read-only, non-idempotent, open-world write. The description adds two useful facts beyond them: the paid-plan requirement and that it initiates a DNS connect session (implying a multi-step flow). It does not disclose that the connect is asynchronous or what the completion step is, so the picture remains partial.

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 plan constraint and the session outcome front-loaded; every clause earns its place. It is arguably over-terse for a mutation with follow-up steps, but there is no filler.

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

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

With 100% schema coverage and annotations carrying the safety profile, the definition is callable as-is. However, for a domain-connect flow the agent lacks the crucial next-step and polling context, and no output schema exists to fall back on, leaving the workflow incomplete.

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

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

Schema description coverage is 100%: site, hosts, domain, context, and guestToken are each fully documented in the schema, including the hosts-vs-domain fallback and the guestToken lifecycle. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

The description names a specific action (connect apex and/or www) and the initiating effect (starts a DNS connect session), which distinguishes it from read-side siblings like get_custom_domain_connect and list_custom_domains. It stops short of explicitly differentiating from refresh_custom_domain, reapply_custom_domain_oauth, or set_primary_custom_domain, so it is clear but not sibling-aware.

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?

"on a paid plan" gives one precondition, but there is no guidance on when to prefer this over refresh/reapply/set_primary, nor any statement of what the caller must do next (e.g., wait_for_custom_domain). Usage is implied by the action rather than explained.

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 flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds meaningful context beyond them: the operation is atomic, it is capped at 10 writes, and each body/call has 60KB/80KB size ceilings. It still omits auth/guestToken requirements and what a failed batch leaves behind, but the constraint disclosure is substantive.

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 dense sentence that front-loads the core operation and then the limits and the large-page escape hatch. Nothing is padding, though the telegraphic 'dotsy push / PUT content-raw' shorthand assumes prior knowledge and reads more like a note than an instruction.

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

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

For a destructive, non-idempotent batch mutation with six parameters and deep nested objects, the description covers atomicity and size limits but not permissions, partial-failure behavior, or the required context/guestToken flow. The rich input schema carries much of the load and there is no output schema to explain, but the behavioral envelope is only partially closed.

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 only 50% schema description coverage, the description must compensate and it partially does: it explains writes[].route for attaching routes and writes[].bodyStaging for staged bodies. It says nothing about deletes[], message, context, or guestToken, and does not explain the key/body fields, leaving the remaining undocumented half of the schema 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 the operation concretely: an atomic set of writes[] plus deletes[], with routes attached via writes[].route. An agent can tell it performs a batched mutation rather than a single put/patch, though it never names the sibling tools (batch_patch_content, bulk_put_content) it overlaps with, so differentiation is inferred rather than stated.

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

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

It gives real operational guidance for the large-page case (stage_content_chunk then writes[].bodyStaging, or dotsy push / PUT content-raw), which is a genuine routing hint. However there is no explicit statement of when to prefer apply_changeset over batch_patch_content, bulk_put_content, or put_route, nor any when-not condition, so usage is implied rather than specified.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral facts: all-or-nothing (atomic) validation and hard size ceilings (replace-string ≤60KB, call ≤80KB), which an agent cannot derive from structured fields.

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

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

Three compact clauses with no filler, and the defining scope ('on multiple keys') is front-loaded. The phrasing is telegraphic, but 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?

No output schema exists, and for a destructive batch mutation the key concerns — atomicity, size limits, scope — are addressed, so an agent can call it correctly. It leaves per-op semantics to the schema enum, which is a reasonable delegation.

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 75%, so the schema carries most parameter meaning. The description adds quantitative constraints tied to the replace-string op and the overall call size, which is useful, but it does not clarify any of the eight op enums or the expect/find/selector fields.

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

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

States a precise verb+resource ('patch_content on multiple keys'), which immediately distinguishes it from the sibling patch_content and from bulk_put_content/find_replace.

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 selection rule for the sibling: 'Preferred edit path for pages over 60KB,' implying plain patch_content handles the smaller cases. No explicit when-not or prerequisite/auth guidance, but the routing signal is present.

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 discloses that bodySha256 is verified before any write with a named failure mode (body_sha256_mismatch), and explains that the response sha256 is the stored blob, which can differ from submitted bytes for WebP rasters after IMAGES optimization. It also states the immediate-liveness rule (editor and draft preview now, published site at next publish), which is exactly the kind of effect an agent needs and annotations cannot express.

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

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

Three dense sentences that front-load the action and scope, then layer verification and publication semantics. No filler, though the semicolon-chained second sentence packs three distinct ideas and could be split for scanability.

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?

No output schema, so the description carries return semantics and it does (sha256 of stored bytes, mismatch error). The notable remaining gap is batch failure behavior: with 1–200 items it never says whether a single bad item aborts the whole upload or writes partially, which an agent must know before committing a large batch.

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%, and the description supplements it meaningfully: it clarifies the key prefix rule and, more importantly, disambiguates submitted-bytes sha256 from stored-bytes sha256, a distinction the schema only hints at. It adds little for contentType or importFromUrl, keeping it short of a 5.

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

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

States a specific verb and resource with scope: 'Upload 1–200 CMS assets.' The key semantics ('key = path after /assets/') and the batch limit make it instantly distinguishable from get_asset, list_assets, and delete_asset, which are the only nearby siblings.

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

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

Usage is implied by the 1–200 batch bound and the CMS-asset framing, and the publish-timing sentence tells the agent why it might care. But it never states when to reach for this over another write tool (e.g. put_content), nor any precondition beyond the schema's guestToken field.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is partly carried. The description adds non-obvious behavior: hard payload limits (60KB per body, 80KB total) and that large calls may queue above an inline threshold. It does not explain what happens to pre-existing content at a staged key.

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

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

Four short sentences, front-loaded with what the tool does and its content-only scope, then constraints, then alternatives. Dense and mostly waste-free, though 'May queue above the inline threshold' is vague about where that threshold sits.

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

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

With 5 parameters, no output schema, and no enums, the description covers the operation, its scope, its size constraints, and escape hatches for oversized payloads. Missing only the outcome semantics of staging/queuing and overwrite behavior for existing keys.

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 60% and the nested content item fields (key, body, contentType) have no schema descriptions, so the description compensates by stating the per-body and per-call size limits and the kind of keys accepted. It says nothing about the required 'context' or 'guestToken' fields, but those are documented in the schema itself.

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

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

Names a specific verb and resource ('Stage many content keys') and immediately scopes what is included ('pages, layouts, fragments') versus excluded ('not routes or assets'), which lets an agent separate it from bulk_put_assets and put_route without opening schemas. It does not explicitly distinguish itself from batch_patch_content or put_content, which is the only gap.

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 routing for an important case: bodies over 60KB or calls over 80KB should use stage_content_chunk, dotsy push, or PUT content-raw. It also hints at the inline-threshold/queueing condition. It lacks guidance on when to prefer this over single-key put_content or batch_patch_content.

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 non-read-only, non-idempotent, non-destructive, closed-world; the description adds the OAuth Connect auth requirement, which is behavioral context the annotations do not convey. It stops short of saying what happens to the guest draft or whether a repeat call fails or re-claims, which matters given idempotentHint=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?

Two short sentences: the action is front-loaded and the prerequisite/parameter hint follows. Nothing is redundant or padded.

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 mutation with no output schema, the description covers purpose, auth prerequisite, and token source. It omits the post-call outcome (what the claimed site looks like, error behavior on re-claim), which is a minor gap given non-idempotent semantics.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, including the 'one sentence, publicly visible' constraint on context and the pgg_ prefix on guestToken. The description's pointer to start_site for the token largely repeats 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?

The description gives a concrete verb+resource: moving a guest draft onto the signed-in account, which clarifies the otherwise cryptic name 'claim_site'. It implicitly distinguishes itself from siblings like start_site (which creates the guest token) and create_site/graduate_site, though it never names an alternative 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?

It states a clear precondition ('Requires OAuth Connect') and routes the agent to start_site as the source of the guestToken, which is genuinely useful invocation guidance. It does not spell out when NOT to call it or name a competing sibling for the same task.

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 it is a non-readOnly, non-idempotent, non-destructive, non-openWorld create operation. The description adds meaningful behavior beyond that: globally taken slugs are auto-suffixed to a slug-adjective-noun pattern, and onSlugTaken:'fail' returns a 409 instead of renaming. It does not cover permissions or the guestToken/claim lifecycle, but the auto-suffix and 409 semantics are real added context on top of 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?

Two compact sentences front-load the core action and then qualify slug-collision behavior. There is some density with the inline code and default annotation, but no wasted filler. It is appropriately sized for a create tool.

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

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

With no output schema, the description needn't explain returns. But for a 9-parameter create tool with only 44% schema coverage, the description omits guidance on guestToken/claim_site flow, workspace selection, editingMode, and keyConvention, which are relevant to calling it correctly. It covers slug behavior well but is incomplete overall.

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 44%, below the 80% threshold, so the description should help compensate. It only adds meaning for one parameter (onSlugTaken) by explaining the fail/409 behavior. The other eight parameters, including required slug and context plus guestToken, editingMode, keyConvention, and workspace, receive no explanation in the description even though several of those schema entries do carry their own descriptions. This leaves a partial gap.

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

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

States a specific verb and resource ('Create empty site') and adds a notable side effect ('seeds brief'). This distinguishes it from sibling create-like tools such as start_site or import_site_from_url, though it never explicitly names those alternatives. The core purpose is clear.

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

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

The description implies this is the entry point for making a site, and the onSlugTaken guidance ('pass onSlugTaken:"fail" to get a 409') gives conditional usage for one parameter. However, it does not say when to prefer this over start_site or import_site_from_url, nor does it state prerequisites like guestToken or claim_site flow. Usage is only implied.

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, destructiveHint=false and openWorldHint=false. The description adds one genuinely non-structured fact — that the tool is deprecated — which is real behavioral context, but discloses nothing about execution, auth, or failure mode.

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, and the deprecation flag leads before the redirect. Exactly the right size for a tombstone definition.

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

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

For a 9-parameter tool with no output schema, the description is minimal, but deprecation justifies brevity. It omits whether calls still succeed, whether results remain valid, and when the tool will be removed — details an agent choosing between this and structure_site_analyze would benefit from.

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 78%, so the schema documents most of the 9 parameters itself. The description contributes zero parameter-level information, 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?

The description never states what the tool does; it only declares deprecation status and names a replacement. The purpose is recoverable from the name and title ('Analyze site structure'), but the description text itself supplies no verb+resource statement.

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

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

'use structure_site_analyze' is an explicit, unambiguous routing instruction that names the alternative, which is the single most important usage fact for a deprecated tool. It stops short of saying whether this tool still functions or errors if called.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered structurally. The description adds genuinely non-obvious behavior: the editor and draft preview drop the asset immediately while the published site only drops it at the next publish. It omits auth requirements (guestToken is left to the schema) and error semantics.

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. The deletion action and its scope are front-loaded ahead of the propagation caveat.

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 4-parameter mutation tool with rich annotations and a fully documented schema, the description covers the essential non-obvious trait (split-brain propagation between draft and published). It does not mention guestToken auth flow or failure behavior, but those are largely schema- and annotation-territory.

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

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

Schema description coverage is 100%, so all four parameters (key, site, context, guestToken) are already documented in detail, including examples. The description adds nothing beyond the schema's own key-format and propagation notes, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a static asset') plus the addressing mode ('by key'). This distinguishes it from delete_content and bulk_put_assets, whose names imply different resources and operations.

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

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

No guidance on when to use this versus delete_content, bulk_put_assets, or get/list_assets. The only usage-like signal is the propagation note, which describes effect rather than selection criteria.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description does add real value by disclosing that published content is tombstoned rather than hard-deleted, but says nothing about reversibility of that tombstone or permission/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 tight sentence with the destructive scope front-loaded and no filler. It earns its brevity, though it borders on under-specification for a destructive operation.

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

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

For a destructive, four-parameter tool with no output schema, the definition covers the key behavioral nuance but omits what happens to unpublished content, whether the tombstone can be restored, and the guestToken auth flow. Adequate but with clear gaps.

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

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

Schema coverage is 75%, with the 'key' parameter undocumented in the schema, and the description only names it rather than clarifying its format or lookup behavior. site, context, and guestToken are covered by the schema, so the 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?

States a specific verb (delete) and resource (content key), which separates it from the many delete_* siblings like delete_asset, delete_site, and delete_route. The parenthetical adds scope behavior, though 'content key' is jargon an outside agent must infer.

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

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

No guidance on when to use this versus alternatives such as discard_drafts, revert_change, or patch_content. The only hint is the tombstone clause, which is behavioral rather than conditional routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description goes beyond them with two useful facts: variant bodies are released, and the operation does not publish anything. It still omits authorization/permission requirements and 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 front-loaded sentence with a parenthetical that earns its place by clarifying the non-publishing semantics. No wasted words, though it is terse enough to need more content elsewhere.

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 annotations covering the safety hints, the description is adequate but thin: no state preconditions, no note on reversibility, no mention of what happens to the experiment record after the variant bodies are released. No output schema exists, so return expectations are also unaddressed.

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

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

Schema coverage is 75% (site, context and guestToken are documented, experimentId is not), so the schema does most of the work. The description adds nothing about parameters, leaving the required experimentId undocumented in both places; a bare 3 is appropriate for this coverage level.

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 ('Remove a draft A/B test') and the parenthetical narrows the scope to the draft state. It implicitly separates itself from siblings like discard_drafts and promote_experiment, though it never names them.

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 stated condition for choosing this over alternatives such as discard_drafts, delete_content, or promote_experiment, nor any prerequisite (e.g. the test must still be a draft). Usage must be inferred from the name alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description usefully clarifies the blast radius ('page stays live'), which is genuine added context, but it says nothing about authentication requirements, the fact that a required context sentence is logged publicly, or whether the removal 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 sentence with zero filler, and the scope qualifier is placed immediately after the action so the agent reads the constraint first. Every word earns its place.

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

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

For a destructive, five-parameter tool with 60% schema coverage and no output schema, the description is thin. Safety is carried by annotations, but the agent gets no signal about the required context/guestToken workflow, which are the most likely causes of a malformed call.

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

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

Schema description coverage is only 60% and the description contributes no parameter information at all. The undocumented id and menu parameters are inferable from their names, but the description does nothing to compensate for the coverage gap or to explain the mandatory audited 'context' field.

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

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

States a specific verb and resource ('Remove one item from a menu') and adds a scope qualifier ('page stays live') that separates it from the page-level delete siblings. It does not name an explicit sibling (e.g. delete_route, delete_content) but the operation is unambiguous.

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

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

The parenthetical '(page stays live)' implies the tool is for removing a single menu entry without deleting the underlying page, which is a usage hint. However there is no explicit when-to-use guidance, no mention of when to prefer reorder_menu or put_menu_item, and no statement of prerequisites such as the guest token or the mandatory context field.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that — it says nothing about what happens to dependent routes, whether removal is reversible, or the activity-log/auth context that the schema alludes to.

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 well-formed sentence with the verb and key identifier front-loaded and zero filler. It is efficient, though its brevity borders on under-specification rather than pure concision.

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

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

This is a destructive mutation tool with no output schema and only a one-line description. It omits consequences of deletion, handling of child/dependent routes, and any interaction with the required site context — a significant gap even accounting for the annotations that cover idempotency and destructiveness.

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% (site, context, and guestToken are documented; path is not), so the schema does most of the work. The phrase 'by path' marginally clarifies that path is the deletion identifier, which is slightly more than the bare schema offers, but no format or matching semantics are provided.

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 (remove) plus resource (route) and the identifier (path), which cleanly distinguishes it from siblings like delete_content, delete_asset, and delete_menu_item. It does not, however, mention the site scoping that the schema requires, so it stops short of full sibling differentiation.

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

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

No when-to-use or when-not-to-use guidance, and no mention of the obvious related siblings (get_route, put_route, patch_route) that an agent would need to choose between. The agent gets no signal about prerequisites or the effect on routes that reference this path.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature and repeat-call behavior are covered by structured data; the description's 'Permanently' merely reinforces that. It does add one genuine behavioral fact, the confirmSlug==slug interlock, but says nothing about what is destroyed (content, assets, domains, activity log), whether it is reversible, or what quota/ownership checks apply.

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 destructive verb front-loaded and the constraint immediately after. Every clause earns its place and there is no filler.

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

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

For an irreversible site-level destruction with three required parameters and no output schema, the description is thin: it never says what happens to the site's pages, assets, domains, or guests, nor whether any recovery window exists. The confirmSlug gate is documented, but an agent about to invoke this cannot tell what the blast radius is from the description alone.

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%, and the one undescribed parameter (confirmSlug, which has no schema description at all) is exactly what the description explains: it must equal the slug. That is meaningful semantics added beyond the schema. It does not clarify the site slug format beyond what the schema's own example provides, so it is not 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 and resource (permanently delete a site) in the very first words, which cleanly separates it from the many delete_* siblings such as delete_asset, delete_content, and delete_route. It does not name or contrast any sibling explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance, no stated preconditions (e.g. site must be unclaimed, unpublished, or domain-free), and no mention of when a softer alternative like update_site or rename_site would be preferable. The only usage-adjacent content is the confirmSlug constraint, which is a safety interlock rather than routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the adjectival 'Destructive' in the description largely restates structured data. It does add real value by scoping destruction to 'unpublished drafts' and by recommending a status check beforehand, but it omits anything about reversibility, required permissions, or whether discarded drafts can be recovered.

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

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

One sentence for the selection semantics followed by a short safety warning; the destructive nature and the get_draft_status precondition are front-loaded, and there is no filler.

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

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

For a 6-parameter, no-output-schema mutation tool with annotations already covering the safety profile, the description covers the ambiguous selection logic well. The remaining gaps — auth/permission requirements and what a successful discard returns — are minor given the schema documents guestToken and context and the annotations flag destructiveness.

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 only 50%, and the four undocumented parameters (key, keys, routes) are exactly the ones the description explains — including the important default that omitting all three discards everything, and the key-vs-(keys, routes) distinction. This is meaning the schema alone does not convey.

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 and resource ('Discard unpublished drafts') and then enumerates the three distinct scopes the tool can operate on: all, one key, or a selection. 'Discard' plus 'unpublished drafts' cleanly separates it from the sibling delete_content/delete_route tools, which target published/committed resources.

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

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

It gives an explicit precondition ('check get_draft_status first') and encodes the selection rules (omit key/keys/routes for all; key for one; keys/routes for a subset), so an agent knows how to invoke each mode. It does not, however, state when *not* to use this versus delete_content or what happens if the drafts were already published.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: this tool only opens an interactive canvas and requires the user to click an element, with actual mutations deferred to patch_content – which also reconciles the seemingly write-oriented name with the readOnly annotation. It stops short of describing session lifecycle or what happens if the canvas is abandoned.

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, dense sentence that front-loads the action, then the flow, then the alternative. No filler.

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

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

With only 3 fully documented params, no output schema, and simple annotations, the description covers what an agent needs: what happens (interactive canvas), who acts (the user), and what to call next (patch_content). Minor gap in not clarifying whether the canvas session persists or how long it stays open.

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% (site, path, stage all documented, including the caveat that published is not yet supported), so the schema carries the load. The description adds no parameter-level detail, 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?

States a specific action (open the interactive page canvas) and its purpose (change content), and explicitly distinguishes itself from preview_page (verify-only) and names patch_content as the follow-up mutation step. An agent can place this tool among its many siblings 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?

Gives an explicit when ('intent is editing') and when-not ('not for verify-only checks'), and routes the alternative case to a named sibling, preview_page. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the appended 'Read-only' repeats structured data. The useful addition is '(traffic baseline)', disclosing the estimation basis, but no return shape or precision (e.g., a day count vs. a range) is given despite no output schema existing.

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, front-loaded sentences with no padding. Minor waste in the second sentence, which restates the readOnlyHint annotation rather than adding 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?

The safety profile is covered by annotations, but with no output schema the description should say what the estimate returns (a number of days, a confidence band, etc.) and whether it depends on current traffic. That omission keeps it at a minimally viable level for a 4-parameter analysis tool.

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

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

Schema description coverage is 100% and each parameter (site, path, context, guestToken) is already documented, so the baseline is 3. The description adds only an implicit binding of 'a page' to the path parameter and clarifies nothing about context or guestToken semantics.

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 (estimate) plus resource (days to promote readiness) and scope (for a page), with a parenthetical clarifying the method (traffic baseline). 'Promote readiness' is jargon that only resolves by cross-referencing the sibling promote_experiment, so it is clear but not sibling-differentiating 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?

No explicit when-to-use, prerequisites, or alternatives. With siblings like start_test and promote_experiment, the agent is left to infer that this is a pre-promotion estimate; nothing names the sequencing or when NOT to call it.

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

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

Annotations already declare destructive=true, idempotent=false, readOnly=false; the description still adds real value beyond them by disclosing case-insensitivity, the staged-commit semantics, the per-key concurrency conflict behavior, and the 60KB find/replace limit. It stops short of saying how the staged change is applied or reverted.

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 dense sentences, front-loaded with the operation and scope, followed by the two operational constraints. No filler; every clause 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?

For a destructive, non-idempotent mutation with seven parameters, no output schema, and 43% schema coverage, the description covers concurrency and size limits well but omits how the staged commit is finalized (apply_changeset/publish), what happens on conflict/partial match, and the meaning of keys and expectPerKey.

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 only 43%, and the description compensates for at most one parameter by mentioning the 60KB find/replace size bound. It says nothing about what 'keys' scopes, what 'expectPerKey' validates, or that 'replace' can be empty, leaving four parameters semantically thin in both schema and prose.

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 (case-insensitive find→replace across pages) and adds the notable scope detail that it lands in one staged commit. It does not name or distinguish itself from near siblings such as patch_content, batch_patch_content, or bulk_put_content, so an agent must infer when this is the right mutation tool.

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

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

Gives a strong invocation rule (batch everything into ONE call, never parallelize on the same key because of per-key conflicts) and a size ceiling, but says nothing about when to choose this over the overlapping content-mutation siblings. The guidance is about how to call it safely, not when to prefer it over 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds cross-tool context (this tool's memberships drive whether workspace must be passed on writes), which is genuinely useful relational behavior. It does not, however, disclose return format 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?

Two terse fragments with no filler, and the workspace rule is front-loaded effectively. But it is under-specified rather than genuinely concise — the noun-list style borders on cryptic and omits the actual operation, so brevity costs clarity here.

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 context tool with no output schema, the description lists the returned entities (account, user, memberships) and 100% param coverage in the schema carries the inputs. It still lacks any statement of when the tool should be invoked, leaving a real gap for what is likely a first-call bootstrap tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description's 'memberships.length > 1' threshold is a slightly more concrete restatement of the schema's 'Only for multi-workspace users' note, adding marginal value but no syntax or format 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?

The fragment 'Account, user, memberships[]' tells the agent what entities the tool surfaces, which is more than a pure tautology of the name. However, it never states a verb or the operation itself, so the purpose is inferred rather than declared, and nothing differentiates it from context-bearing siblings like get_site or list_my_sites.

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

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

'Pass workspace on writes when memberships.length > 1' gives a conditional rule, but it governs how to use the workspace parameter in *other* (write) tools, not when to call get_account_context itself. There is no when-to-use, no prerequisite, and no alternative named.

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 safety (readOnly, idempotent, non-destructive). The description adds the meaningful disclosure that context notes are publicly visible to everyone on the site with 'no secrets'. Retention floor on since and limit≤20 are also behavioral, though pagination behavior is unspecified.

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

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

Three tight sentences, front-loaded with the primary action and mode, then filters, then the public-visibility warning. Dense but every clause 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 read-only list/diff tool with 100% schema coverage and no output schema, the description covers mode selection, filters, and the safety-relevant visibility of context. Pagination and cursor behavior are the only notable gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics not obvious from the schema alone: id switches the return type to a diff, context must be a one-sentence reason, and 'since' has a 7-day default with a plan retention floor.

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

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

Names specific verb (List/fetch) and resource (site activity/change diff) with a clear mode distinction keyed on the id parameter. Distinguishes itself from siblings like get_analytics and list_pages, though it doesn't cite a sibling by name.

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 two operating modes and when to use each ('pass id' to get a diff instead of the list), plus enumerates available filters. Clear context but no explicit exclusions or alternative-tool routing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. With no output schema, the description usefully discloses what state is returned (etag, applied/consumed flag, undo presence, queued vs active jobs), which an agent cannot get from structured fields. It adds real behavioral context 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?

Two sentences, no filler, with the resource and returned data front-loaded ahead of the usage clause. Dense and well-ordered, though the parenthetical flag notation is slightly compressed.

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

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

With no output schema, the description appropriately covers return content, and annotations cover the safety profile; the schema covers parameters. The main gap is the absence of any mention of continuation behavior between calls, but for a status-read tool this is close to complete.

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

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

Schema description coverage is 100%, so 'site', 'context', and 'guestToken' are fully documented in the schema itself, establishing the baseline of 3. The description contributes nothing further about parameter usage or format, so it neither gains nor loses on this dimension.

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

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

States a specific verb (Read) and resource (adapt state) and enumerates the concrete payload: proposal summary, proposalEtag with applied/consumed flag, undo-record presence, and job progress. This clearly separates it from the mutating siblings adapt_site_analyze/apply/revert, though it never names them 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 single clause 'Use to resume in a fresh session' gives one concrete usage context, which is genuinely helpful. However, there is no guidance on when not to use it or which sibling to prefer for overlapping needs (e.g. get_draft_status, get_site_build_progress), leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description's 'Read-only' largely restates the annotation, and it adds only mode-selection behavior rather than new traits like rate limits or response shape.

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 densely packed sentence with the default mode front-loaded and secondary capabilities (include[], bot) following. No filler sentences.

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

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

With six parameters and no output schema, the description covers invocation modes but does not describe the return structure (overview fields, detail sections, crawlerBotPages). Annotations and full schema coverage compensate for much of the gap, making this adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents site, range, context, bot, include, and guestToken in detail. The description adds marginal gloss on include[] and bot, which is the expected baseline-3 outcome when the schema carries the load.

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+resource (read-only traffic overview / breakdowns) and distinguishes two modes (default overview vs include[] breakdowns) plus a bot drill-down variant. It is clear what the tool does, though it doesn't explicitly contrast itself against sibling tools.

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

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

It states which mode is default ('overview (default)'), how to get more ('full breakdowns via include[]'), and the condition for the bot parameter ('for crawler page drill-down'). There are no explicit when-not-to-use statements or named alternatives, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real value beyond them: it specifies the exact return payload and clarifies that the stored sha256 can differ from the upload bodySha256 when IMAGES re-encodes rasters. That hash semantics detail is non-obvious and useful, though it stops short of noting size limits or large-base64 caveats.

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 return contents, and the sha256 clarification earns its place. The third sentence about files being live in the editor/published site is largely duplicated from the 'key' parameter description and is only loosely relevant to a read tool, slightly diluting focus.

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

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

With no output schema, the description correctly carries the burden of describing returns (metadata, base64, stored hash) and explains the hash's provenance. It is complete enough for correct invocation, though it omits any hint about response size or how the base64 should be consumed.

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 four parameters (key path format, site slug, context, guestToken). The description adds no parameter-level meaning beyond that, 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?

The description opens with a precise verb+resource ('Read one asset') and immediately enumerates what is returned (metadata + base64 + stored sha256). The singular 'one asset' cleanly distinguishes it from the sibling list_assets and from mutators like bulk_put_assets/delete_asset.

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 reach for this tool versus alternatives such as list_assets, get_site_manifest, or search_content. The upload/publish sentence describes asset lifecycle behavior but does not tell the agent when this read tool is the right choice or what prerequisites apply.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavior beyond annotations: the 40KB truncation behavior and the published=true live-body mode. It does not describe auth/guestToken flow, but that lives in 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?

Two dense sentences, zero filler, with the truncation caveat and its remedies front-loaded after the core read statement. Every clause earns its place.

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

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

For a read-only single-key tool with no output schema, the description covers the key gotcha (large-body truncation) and the live/published distinction. Minor gap: it doesn't clarify the guestToken vs signed-in context, but that is documented in the schema.

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

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

Schema coverage is 50%. The description does add meaning for two undocumented params: selector => 'region' and published => 'live body'. However 'key' and 'guestToken' remain unexplained, so the description only partially compensates for the coverage gap; baseline 3 is right.

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: 'Read one content key.' The scope word 'one' implicitly separates it from list_content and search_content siblings. It does not explicitly name those siblings, so it stops short of a 5.

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

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

Gives a concrete conditional: bodies over 40KB without a selector return a truncated summary, and names alternatives (selector, batch_patch_content, dotsy pull). This tells the agent when to add a selector, though it offers no guidance on when to prefer this over list_content or search_content for discovery.

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 profile is covered. The description adds the useful detail that the result may be either a browser URL or a manual DNS guide, but omits auth/session resume behavior and any rate or polling notes.

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. It is efficient, though arguably under-specified rather than maximally concise.

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 workflow/state-inspection tool with no output schema, it does indicate the shape of nextAction, which is the key return field. However it leaves the lifecycle relationship with add_custom_domain, wait_for_custom_domain, and reapply_custom_domain_oauth unstated, which an agent needs to sequence calls 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 documents site, context, sessionId (from add_custom_domain, omit to resume pending), and guestToken in full. The description adds no parameter-level meaning beyond that baseline.

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 is a noun phrase describing the returned payload (current connect session, nextAction with browser URL or manual DNS guide) rather than a verb stating what the tool does. A reader can infer it is a read of connect-session state and distinguish it from add/remove/refresh siblings, but the action itself is only implied.

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 and no named alternatives, despite a dense cluster of sibling domain tools (add_custom_domain, wait_for_custom_domain, reapply_custom_domain_oauth). Nothing tells the agent when to call this versus waiting or re-applying.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is fully covered. The description adds one genuine behavioral fact beyond that – the response may carry a requiredDecision (publish_confirm) gating publish_site – but says nothing about freshness, scope of 'pending', or how the decision should be handled.

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 the payload stated first and the publish-gating note second; nothing is wasted. The telegraphic style ('content keys and routes with status') is compact but slightly cryptic.

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

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

With no output schema, the description carries the return-value burden and does list the returned elements plus the possible requiredDecision field, which is the key thing an agent needs to branch on. It stops short of naming the decision's values or the exact field shape, but is adequate for a three-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?

Schema description coverage is 100%, and the schema itself explains site, context (including the activity-log warning), and guestToken in detail. The description adds no parameter meaning beyond that, so the 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 the resource and payload clearly: pending draft changes with content keys, routes, and status. It implies a read of draft state and is distinguishable from mutations like discard_drafts or publish_site, though it never uses an explicit verb like 'return' or 'list'.

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

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

Usage is only implied via the trailing phrase 'before publish_site', which hints at a pre-publish checkpoint. There is no explicit when-to-use statement, no mention of alternatives such as get_content or list_content, and no note on when this is unnecessary.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds meaningful non-structural context: this call exposes PII in full, which is exactly the kind of consequence an agent should weigh before invoking. It does not, however, discuss logging or retention implications of the returned data.

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

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

A single front-loaded sentence that names the action, the object, the payload scope, and the sensitivity caveat. Nothing is padded and the warning is not 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 four-parameter read tool with no output schema, the description conveys what comes back ('full field payload') and flags the PII risk, which is the main decision factor. Missing only a pointer to the list tool for the lighter-weight alternative.

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 every parameter (id, site, context, guestToken) carries its own schema description, so the baseline is 3. The description adds no parameter-level detail beyond noting the payload is 'full', which does not disambiguate any argument.

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 ('Read one form submission') plus the scope ('full field payload'), which distinguishes it from the sibling list_form_submissions by implying single-record retrieval. It stops short of naming that sibling explicitly, so the differentiation is inferential rather than stated.

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

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

The parenthetical 'explicit PII access — use only when needed' gives a caution and an implicit when-to-use condition, but it never names the cheaper alternative (list_form_submissions) or states a concrete trigger for the full-payload read. Usage is hinted rather than prescribed.

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 result contains 'draft items and etag', useful return-content context in the absence of an output schema, but says nothing about permissions, guest-token behavior, or what an absent menu returns.

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 compact sentence with no wasted words, and the core action ('draft items and etag') is front-loaded ahead of the secondary routing hint. Nothing is padded.

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 4-parameter read tool with no output schema, the description gives only a thumbnail of the return ('draft items and etag') and leaves the relationship to get_menu_doc and the semantics of a draft-vs-published menu unstated. It is minimally viable but not complete.

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

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

Schema coverage is 75% and includes the unusually well-documented 'context' and 'guestToken' parameters, so the schema does the heavy lifting. The description adds no parameter meaning beyond what the schema already states, which is the baseline expectation at this coverage level.

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 ('Read') and resource ('a menu's draft items and etag'), which is precise enough that an agent knows this fetches draft menu state. However, it never distinguishes itself from the sibling get_menu_doc (published doc) or get_menu_doc/put_menu_doc, so the boundary between reading a menu's draft vs. its doc is left implicit.

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

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

The clause 'menu rules → get_skill('nav')' is a genuine routing hint for a related need, which is more than most tools offer. But there is no guidance on when to call this versus get_menu_doc or when a menu read is appropriate at all, so usage is only implied.

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 establish the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, closed world), so the bar is lower; the description adds real value by disclosing the response contents and, crucially, that the issues (page_not_routable, page_missing, page_dead_link, page_is_redirect) are computed from draft routes. It does not restate safety behavior, which is fine given the annotations.

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

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

It is a single front-loaded sentence that leads with the core action, followed by the return contents and the rationale. The parenthetical enumerations of issues and doc parts make it dense, but every clause carries information rather than filler.

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

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

With no output schema, the description carries the return-value burden and does so reasonably: it lists the menu doc, the etag for the paired write, and the four issue categories. Combined with the fully documented input schema, an agent has enough to call and interpret the result, though a note on scoping source=draft/live in the description would round it out.

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

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

Schema description coverage is 100%, with 'source', 'context', and 'guestToken' fully documented in the schema, so the baseline is 3. The description mentions draft routes (implying the draft source) but does not add format or selection detail beyond the schema, so it neither compensates nor detracts.

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

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

Names a specific verb and resource ('Read the whole menu doc'), enumerates what the doc contains (all menus + shell/template), and clarifies scope against the sibling get_menu by emphasizing 'whole' vs a single menu. It also ties itself to put_menu_doc by naming the etag it supplies, so an agent can place it in the read/write pair 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?

Usage timing is only implied by 'shows up before publish', which hints this is a pre-publish verification read, and by the etag mention implying it precedes put_menu_doc. There is no explicit when-to-use/when-not statement or named alternative (e.g. get_menu for a single menu), so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, fully covering the safety profile. The description adds no behavioral context beyond that — nothing about authentication needs, error behavior for a missing path, or any distinguishing characteristic.

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, front-loaded with the verb and resource, with the path convention tucked in parenthetically. Zero waste.

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 get tool with no output schema, the description says nothing about what a retrieved route contains (layout, template, redirect target, etc.), leaving the agent unable to reason about the result. The auth/guest-token story is carried by the schema, which mitigates but does not eliminate the gap.

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

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

Schema coverage is 75%; site, context, and guestToken are all documented in the schema, including the notable requirement to send guestToken until claim_site. The description contributes only the '/' convention for path, which the schema leaves undocumented, so it adds marginal value over the schema baseline.

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: fetch a single route identified by its path, with the home-path convention stated. It does not differentiate itself from near-siblings like get_menu, get_site_outline, or patch_route, so it lands just below the top tier.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives (patch_route/put_route/delete_route all operate on the same resource). The only hint is the parenthetical about '/' for home, which is a path convention rather than usage direction.

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 establish readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: pages[] is a ~25-entry head by default, stats.pages holds the true count, and pages:true is server-capped at 1000. The truncation semantics are the key disclosure an agent needs.

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

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

Dense but front-loaded: the return contents come first, then the pages/pagination guidance. Every clause earns its place, though the em-dash-heavy packing makes it slightly harder to scan than a clean sentence would be.

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

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

No output schema exists, so the description must carry the return shape, and it does (detail, stats, publicUrl, brief, readiness flags, pages truncation). Auth via guestToken and the required context sentence are documented in the schema, so the description needn't repeat them. Adequate for a 5-param 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?

Schema coverage is 100%, so all five parameters are already documented, including pages default/cap and brief default. The description reinforces pages semantics (the ~25-entry head, the 1000 cap) and the stats.pages relationship, but this largely restates the schema. 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?

The description names the resource (site) and enumerates what it returns: detail, stats, publicUrl, brief head, readiness flags. It implicitly distinguishes itself from siblings like list_pages and get_site_manifest in the same breath. It never states the verb outright, but the read-of-a-site intent is unambiguous.

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

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

It routes the agent explicitly: use pages:true for the full array, or enumerate everything with list_content/get_site_manifest, and it flags that list_pages is paginated for large sites. It does not address when to prefer this over get_site_outline, list_my_sites, or get_analytics, but the alternatives it does name are the relevant ones.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description goes beyond them by flagging that the payload lives in structuredContent.forHumans, that the call is optional, and that polling is wasteful because import_site_from_url blocks until completion.

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

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

Three tight sentences, front-loaded with the operation and its timing. The only drag is the parenthetical jargon 'build-theater view', which costs a little clarity without adding much.

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

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

With no output schema, the description usefully names the return field (structuredContent.forHumans) and the conditions under which calling is worthwhile. A brief note on what that payload contains would close the remaining gap.

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

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

There is a single 'site' parameter at 100% schema description coverage, so the schema already defines it fully. The description adds no syntax, format, or slug-resolution detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Read-only build progress') plus the scoping condition ('during structure/adapt or after import') and explicitly names the sibling to prefer for agent logic ('Prefer get_site'). An agent can distinguish this from get_site, get_structure_status, and get_adapt_status 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?

Gives the when (during structure/adapt or after import), the when-not ('do not call in a loop during import_site_from_url (that tool blocks until done)'), and the alternative ('Prefer get_site for agent logic'). All three selection conditions are explicit rather than inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld=false). The description adds genuine context beyond them by disclosing response content (keys+hashes only) and what is excluded (static file bodies, route detail unless routes=true). It omits pagination behavior despite limit/cursor params, but the added content disclosure is real.

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 dense sentences, front-loaded with the return content and immediate clarifications. Every clause earns its place; 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?

No output schema exists, and with 7 parameters and low schema coverage the description leaves gaps around mode, pagination, and auth parameters. It covers purpose and workflow well but is thin for a tool with this much surface area.

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 only 43%, so the description should compensate, yet it addresses just one parameter (routes). It never explains mode (published/draft), limit, cursor, or the guest-token flow, leaving several parameters undocumented in both places.

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

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

States a specific resource (site manifest) and precisely what it returns (content keys + hashes only), and distinguishes its scope from siblings by noting static files belong to list_assets. The verb 'get/lists manifest' is implied rather than explicit, but an agent can tell what the tool yields.

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 workflow ('Diff keys+hashes before apply_changeset; stage only changed bodies') and routes the agent away from this tool when dealing with static files ('list_assets, not manifest'). No explicit when-not conditions, but the alternative is named.

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, non-destructive, closed-world. The description adds real behavioral context beyond them: the returned facets, and importantly the indexing caveat that a freshly imported/graduated site may still be indexing, mirroring list_pages. It doesn't describe pagination or result-size behavior, but the added indexing nuance is valuable.

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 return shape, then usage triggers, then the indexing caveat. Dense but every clause earns its place; the enumeration is long but serves the missing output schema.

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

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

With no output schema, the description compensates by enumerating what is returned (layouts, sections, counts, flags, redirects, menu groupings, collection placements) and adds the indexing timing caveat. An agent has everything needed to call and interpret 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 description coverage is 100%, so site, context and guestToken are already fully documented in the schema. The description adds no syntax or semantics beyond that, which is the correct baseline when the schema carries the parameter burden.

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 resource (site shape: layouts, sections, redirects, menus, collections) with concrete attributes like page count and staged-change flags. It explicitly distinguishes itself from list_pages by promising structure 'without listing every page', 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?

Gives three concrete usage triggers ('is my layout missing', 'what does this section reach', 'where does this menu show') and implies the list_pages alternative via 'without listing every page'. It stops short of naming the sibling tool or stating when NOT to use it, so it's clear context rather than explicit routing.

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

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

Annotations already cover the read-only, idempotent safety profile, so the bar is lower. The description still adds real behavioral context the annotations don't: alias resolution to synonyms like 'list'/'menu', near-miss suggestion on failure, and that the response includes a questions[] payload. This is meaningful disclosure of resolution and return 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 clauses, front-loaded with the return shape then the key behavioral fact (synonym acceptance). Slightly telegraphic ('Skill body + optional questions[]' is a fragment) but every sentence carries load.

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

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

With no output schema, the description usefully describes the return (body + questions[]) and the alias/fallback behavior. Given only two fully-documented required params and a read-only annotation set, this is close to complete, though the 'intake' reference assumes cross-tool knowledge.

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 (id and context) are already fully documented, including the privacy warning about context being publicly logged. The description's note that id may be a synonym duplicates the schema rather than extending it, 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?

The description names the resource (skill) and what comes back (skill body plus optional questions[]), and the id-or-synonym acceptance makes it distinguishable from list_skills. The verb is implicit ('get') but the scope is clear.

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

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

It offers one conditional hint ('Start with intake when ambiguous') and gestures at fallback behavior via near-miss suggestions, but never states when to call get_skill versus list_skills or other siblings. Usage is implied rather than spelled out.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds only the shape of the returned result, not behavior such as what happens when no prior apply job exists or whether the result is cached/expiring.

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 compact sentence with the resource front-loaded and no filler. It is efficiently sized, though the parenthetical field list is a bare enumeration rather than explanatory.

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

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

With no output schema, the description should carry more of the return-value burden; listing the field names helps but says nothing about structure, empty/absent-result states, or the distinction from get_structure_status. Adequate but with clear gaps for a job-status retrieval tool.

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

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

Schema description coverage is 100%, including the noteworthy `full` default-compaction flag and the `context` logging warning, so the schema does the heavy lifting. The description adds no parameter meaning beyond that, making the baseline 3 correct.

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 resource (the last structure apply job result) and names the payload fields (structuredKeys, conflicts, partial), so an agent knows what it gets back. It does not differentiate itself from the sibling get_structure_status or structure_site_apply, which keeps it below a 5.

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

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

There is no indication of when to call this versus get_structure_status, nor any prerequisite (e.g., that a structure apply job must have been started by structure_site_apply first). Usage has to be inferred entirely.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful operational context (the requiredDecision gate on analyze/apply), but the term is left undefined, limiting its value.

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?

Extremely compact — a single line with no filler, and the return-value hint is front-loaded before the behavioral warning. The telegraphic style is terse but every clause 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?

There is no output schema, so the description should carry more of the return-value burden; it only hints at 'flat vs structured page counts' and leaves the return shape, the meaning of requiredDecision, and any next steps unexplained.

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 all three parameters (site, context, guestToken) are documented in the schema, including the guestToken lifecycle. The description adds nothing about parameters, so the 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 conveys what the tool returns — flat vs structured page counts — but uses a noun phrase with no explicit verb or subject (no 'get'/'retrieve'). It gestures at the resource but a reader cannot cleanly distinguish it from the sibling get_structure_result.

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 the relevant alternatives (analyze/apply) and gives a when-not rule: don't auto-run them while requiredDecision is pending. However, there is no positive statement of when to call this tool and no explanation of what a 'requiredDecision' is or how it is set.

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 the safety profile; the description goes far beyond by decomposing the 409 into three distinct gates, describing exactly which gate force overrides, clarifying that the audit payload is aggregate counts rather than row keys, and hammering home the irreversibility of the flip. This is the kind of context an agent needs to avoid a destructive-by-omission mistake.

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, then gate details; every sentence is substantive. Minor redundancy: the 'never the backend or strictDrafts gates' constraint is stated in both the body and the force parameter's schema text, adding a little length.

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

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

No output schema exists, and the description compensates by explaining the blocked response's reason/audit fields. For a one-way mutation it is nearly complete, though it omits auth/permission prerequisites (guestToken is only in the schema) and what happens to already-published content post-flip.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter and client-behavior meaning: force's scope is bounded against the other gates and strictDrafts' default is explained with what this client actually sends. It largely restates the schema's own force/strictDrafts text, hence not 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 ('Enable') plus the exact resource and scope ('site search & collections (kv → do-sqlite), one-way'), and enumerates the concrete capabilities it unlocks (search_content, collection indexes, /__paige/search). An agent can distinguish this migration/flip tool from siblings like reindex_collection or inspect_collection 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 clear context for when the call is appropriate and, importantly, explains when force should and should not be used, plus that the operation is one-way. It does not name a sibling alternative (e.g. a non-migrating path) or state prerequisites like timing relative to publish/discard, so it stops short of full when/when-not routing.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive. The description adds real value beyond that by disclosing that the response may contain requiredDecision and that a user decision is required before structure_*, which is not encoded anywhere else. It omits permissions, size/crawl limits, and failure behavior.

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

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

Two tight sentences, no filler, and the action is front-loaded before the follow-up workflow. The second sentence is dense with opaque tokens (requiredDecision, structure_*) but each word 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 10-parameter, open-world, non-idempotent import with no output schema, the description covers the critical decision handoff but is thin elsewhere: it never clarifies what the resulting 'draft' is, whether prior content is affected, or the auth/guest flow, leaving the schema to carry most of the context.

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 80% and the schema already documents mode, pages, segments, guestToken, workspace, and onSlugTaken in detail. The description contributes no parameter meaning of its own, so the baseline 3 for schema-carried semantics 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 ('Import URL to draft'), which is enough to distinguish it from create_site/start_site and the structure_* siblings. However it never says the import targets a whole site (crawl/sitemap expansion), so the scope of 'import' is left to 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 post-call workflow guidance ('preview then ask mirror vs editable before structure_*'), which is genuinely useful routing. It does not say when to choose this over create_site, start_site, or adapt_site_*, nor any prerequisite (guestToken/claim_site), so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: status semantics (draft = never published; published+hasChanges:true is never draft; scheduled = future visibleAt), the data source split (staged content vs index), and the limit default of 50 clamped to 1-200. This is meaningful behavioral context on top of the safety profile.

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

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

It is front-loaded in a loose sense — the base inspect output comes first and the items[] trigger second — but it is a single semicolon-chained block mixing outputs, status semantics, data sources and limits, which makes it dense and harder to scan than it needs to be. Little is wasted, but structure suffers.

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

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

With no output schema, the description carries return-value disclosure and does so adequately: what the base response contains, when items[] appears, pagination via cursor/limit, and status semantics. Auth (guestToken) and the context requirement are covered in the schema, so no major gap remains for calling 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 baseline is 3, but the description earns more: the status enum is deliberately deferred to the description ('see the tool description for what each means') and the semantics are spelled out there (draft/published/scheduled, hasChanges, visibleAt), plus the '(any one, even empty)' activation rule and limit clamping.

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 enumerates exactly what the tool surfaces (count, server.mode, sample entries, tags, name/noun/URL pattern/layout, post fields) and how it relates to a full items[] page, which clearly separates it from list_collections and list_content. It never states a plain verb like 'inspect', relying instead on the resource name, but the output inventory is specific enough that an agent knows what it gets.

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 a concrete branch: pass status/q/cursor/limit (any one, even empty) for a full items[] page, or omit all four for the base inspect with no items[]. It also ties prefix back to list_collections output ('use the key exactly as list_collections returned it'). It doesn't name a competing sibling to avoid, but the conditional routing is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context that uploads appear immediately in editor/draft preview but only reach the published site at next publish, though it does not discuss authorization or pagination 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 sentences, each contributing distinct information: scope, content exclusion, and publication timing. The front-loaded scope sentence is useful, though the first sentence is a fragment rather than a fully explicit action statement.

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

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

The description is adequate for distinguishing this list tool from key siblings, and annotations cover safety. However, pagination semantics and return-value shape are absent with no output schema, leaving an agent to infer how limit/cursor behave and what an asset listing contains.

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 description contains no parameter guidance at all. With 60% schema description coverage, the schema documents site, context, and guestToken, but limit and cursor remain undescribed in both places, so the description does not compensate for the gap.

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

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

The description identifies the resource as CMS uploads under assets/ and clearly excludes mirrored clone CDN assets and content assets. The action (listing) is implied by the tool name and title but not stated explicitly in the description itself, so it falls short of a full 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 explicitly directs the agent to list_content for content and distinguishes get_site mirroredAssets and import warmJob for clone CDN assets. These are concrete when-not and alternative-tool signals that make routing unambiguous.

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

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

Annotations already establish readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: the return is a bare array rather than a wrapped object, and the listing includes a collection that only a draft page lists. It also notes the item-count placeholder 'not published yet', which signals how unpublished collections appear.

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

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

Two sentences, both front-loaded: the first lists the returned fields and the draft-collection nuance, the second covers the unusual return shape and the downstream handoff. No filler or repetition.

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

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

With no output schema, the description correctly compensates by describing the returned fields and the bare-array shape. It stops short of mentioning ordering or any size limits, but for a simple read-only list tool it is nearly complete.

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

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

Schema description coverage is 100% (site, context, guestToken are all documented in the schema), so the schema carries parameter meaning. The description adds no syntax or format detail for any parameter, so 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?

The description names the resource (collections on the site) and enumerates the exact fields returned, so an agent knows precisely what this produces. The verb is implicit rather than stated, and while it names inspect_collection/update_collection as consumers, it does not explicitly contrast itself with them as alternatives.

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

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

Usage is implied through the handoff instruction to pass each row's key to inspect_collection/update_collection, which reveals the intended workflow. However, it never states when to call this versus a sibling like inspect_collection or list_content, nor any prerequisite beyond the schema's guestToken field.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description goes further by disclosing the measurement behavior: size/missing are auto-measured only on pages of ≤100 rows and are ABSENT past that, with withSize forcing measurement at one storage read per row. This is non-obvious operational cost/behavior an agent could not infer from 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 dense sentences, front-loaded with purpose and sibling exclusion before paging and measurement caveats. Every clause carries distinct operational information; nothing is filler.

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

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

There is no output schema, so the description carries the burden of return semantics, and it does: what a key is, what per-row size/missing mean, when they are absent, and how to page via nextCursor. An agent has everything needed to call and interpret 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 the schema already documents default/max for limit, the cursor source, and the withSize cost, so much of the description's parameter text is restated. It does add real meaning beyond the schema, though: the ≤100-row auto-measurement rule that conditions whether size/missing appear, and the precise 'size: null + missing: true' interpretation.

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 content keys (HTML/md)') and immediately distinguishes itself from the closest sibling by name ('not assets — use list_assets'). An agent can pick this over list_assets or list_pages without opening any schema.

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

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

Explicitly routes the agent to list_assets for the asset case, and details the operating conditions: raise limit (max 1000) or pass cursor from nextCursor to page. It also states exactly when to pass withSize (page >100 rows) and what it costs, so the paging decision is fully specified.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds the useful fact that the response includes connection status, which is behavioral context a caller needs since there is no output schema. It says nothing about ordering, pagination, or empty results.

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 well-formed sentence with the resource and key output field front-loaded and zero filler. Being a one-liner for a 3-parameter tool is lean but not wasteful.

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 complete annotations and full schema coverage, the definition covers what it does and what comes back (hostnames plus connection status) without needing to document return values it has no output schema for. Only the absence of any usage/routing guidance keeps it from being fully complete.

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

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

Schema description coverage is 100%, including the notably instructive context and guestToken parameters, so the schema carries the parameter burden. The description mentions no parameters, which is acceptable at this coverage level but adds no extra 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 (List) and resource (custom hostnames/domains) plus the scope implied by 'all', which distinguishes it from the singular get_custom_domain_connect. It stops short of explicitly contrasting with sibling write tools like add_custom_domain or remove_custom_domain.

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

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

There is no guidance on when to call this versus alternatives such as get_custom_domain_connect (single domain), wait_for_custom_domain (polling), or the custom-domain mutation tools. Usage must be inferred from the word 'List' alone.

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 establish readOnly/idempotent/no-destructive, so the bar is lower, and the description usefully adds that results are a bounded field preview and not full PII, plus the kv/do-sqlite backend support. It stops short of describing pagination behavior via cursor or how 'bounded' the preview actually is.

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 constraint (not full PII) front-loaded and no filler. It is perhaps overly terse for a nine-parameter tool, losing no words but also offering little.

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, read-only listing tool with no output schema and only 56% schema coverage, the description omits pagination, time filters, and search semantics that an agent needs to invoke it correctly. The PII note helps but does not close the larger parameter 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 only 56%, so the description should compensate, yet it mentions none of the nine parameters (q, fromMs, toMs, limit, cursor). Nothing explains how time-range filtering or cursor paging works, leaving the gaps entirely in 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+resource (list form submissions) and adds meaningful scope: metadata plus a bounded field preview rather than full PII. It implicitly contrasts with the singular get_form_submission sibling but never names it, so the differentiation is left to inference.

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

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

No explicit when-to-use guidance and no mention of the obvious alternative, get_form_submission, for retrieving a single record. The agent must infer the list-vs-single distinction from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered structurally. The description's contribution beyond that is workflow context (prerequisite to start_test) rather than behavior; it says nothing about output shape or empty-result handling.

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; the purpose and the critical prerequisite are both front-loaded within a very short string.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the definition covers purpose and the required ordering with start_test. It could mention whether goals must exist before start_test or what an empty list implies, but it is essentially sufficient.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema (including the context-logging caveat and guestToken lifecycle). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (site conversion goals), and clarifies what a goal is with parenthetical examples (pageview paths, form submits). It doesn't explicitly distinguish itself from the sibling put_goals, but the read verb and the examples make the purpose unambiguous.

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

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

"Required before start_test" gives an explicit precondition that tells the agent when this call is mandatory. There is no stated when-not guidance or alternative route to the same data, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds non-obvious behavior beyond them: it renders a site-picker for humans while agents read structuredContent, and it defaults to the active workspace. It does not discuss pagination or result size limits, 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?

Dense but tightly packed with routing and behavioral facts; the purpose and exclusions are front-loaded. It is slightly overloaded with parenthetical cross-references, but no sentence is wasted.

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

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

Single optional parameter, no output schema, annotations present. The description covers purpose, usage routing, rendering behavior, and the parameter's default and source, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with a single optional parameter, so the baseline is 3. The description goes further by explaining where the org id/slug comes from (get_account_context memberships) and that omitting it uses the active workspace, adding practical meaning beyond the schema text.

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

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

States a specific verb+resource ('List your Dotsy sites') and explicitly distinguishes itself from the sibling tools that could be confused with it (edit_page, preview_page). An agent can identify the tool's 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?

Explicitly states when to use it ('Use to choose a site') and when not to, naming the alternative for each excluded case (edit_page for editing, preview_page for verify-only). It also explains the workspace parameter's purpose: listing another workspace without switching the dashboard session.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: pagination via cursor/nextCursor, the meaning of partial:true as a window rather than the full route set, and the fact that redirect and worker routes are omitted from the human page-picker. It stops short of describing auth or rate limits, but the added disclosure is substantive.

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 core purpose is front-loaded, and the dense em-dash clauses each carry information (exclusions, alternatives, mode switch, pagination). It is long but not padded; a slightly tighter phrasing could improve readability, but every sentence earns its place.

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

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

For a 7-parameter, two-mode list tool with no output schema, the description covers the default output shape, the alternate view and its added fields, the human-facing rendering caveat, and pagination/partial semantics. An agent has enough to call it correctly in either mode without inspecting further.

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 each parameter's meaning and baseline would be 3. The description goes beyond that by explaining the mode interaction — that view:'pages' enables layout/noLayout/q and adds page-structure and indexing fields — giving semantic grouping that individual parameter descriptions don't.

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 pages on a site') and immediately distinguishes the tool from siblings by naming edit_page and preview_page. It also crisply contrasts its two modes (default route settings vs view:'pages' layout grouping), so an agent can tell exactly what it does.

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 when to use it ('after picking a site'), when not to ('not for editing — use edit_page; not for verify-only checks — use preview_page'), and routes the alternative mode to specific questions ('what pages use this layout' or 'is this page indexed yet'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that each entry carries id and whenToUse, but says nothing about list size, filtering, or whether skills are site-specific.

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

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

Two short sentences, front-loaded with what is returned and followed by the follow-up action. Dense and waste-free, though the opening phrase is cryptic enough to cost a point.

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 simple read-only list tool with no output schema; the description compensates by stating the returned fields and pointing to get_skill for elaboration. Only pagination/size behavior is unaddressed, which is minor here.

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 there is a single required 'context' parameter whose purpose, format, and privacy constraint are fully documented in the schema. The description adds no parameter meaning beyond that, so the 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?

States a specific verb (list) and resource (build skills) and names the return shape '(id + whenToUse)'. It implicitly distinguishes itself from get_skill, which it tells the agent to call for detail, though the term 'Paige build skills' is domain jargon not defined here.

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 workflow rule: enumerate with this tool, then 'Pull get_skill on demand'. The instruction not to duplicate skill text in tool output is a concrete usage constraint. No explicit when-not-to-use, but the alternative is named.

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 adds useful behavioral content beyond that: it tells the agent what the call yields (a scaffold with suggested key/path, membership meta, and a body that is either blank or a duplicate). No rate limits or error behavior, but the return-shape hint is valuable for a tool with no 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?

Two dense sentences with the read-only nature and outputs front-loaded before the follow-up tool. It is efficient, though the em-dash list is slightly clipped and a phrase like 'membership meta' leans on jargon the schema must disambiguate.

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 scaffold with six fully documented parameters and no output schema, the description covers purpose, produced values, and the next step in the workflow. It stops short of describing pagination or error cases, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so every parameter including the mode enum and templateKey exemplar is already documented in the schema. The description's mention of 'blank or duplicate body' and 'membership meta' loosely echoes mode/collection but adds no syntax, defaults, or format guidance beyond the schema. Baseline 3 for full schema coverage.

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 ('Read-only scaffold for a new post') and enumerates what it produces: suggested key/path, membership meta, and blank or duplicate body. It also distinguishes itself from the write siblings by naming put_post and put_route as the follow-up step, so an agent can place it in the content-creation chain 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?

The 'Then put_post (+ optional put_route)' clause makes the intended workflow position explicit: this is the preparatory read step before writing a post. It gives clear context on when to reach for it, though it states no exclusions (e.g. when not to use it versus inspect_collection or get_content).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the grammar is known. The description adds one valuable behavioral fact beyond annotations: it 'Stages draft' rather than publishing immediately. It does not say whether staged drafts are reversible, how they are committed, or what effect a failed op has.

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, scoping information front-loaded, zero filler. It is arguably too terse ('op shapes in schema') but nothing is wasted and the reader reaches the key fact 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 destructive, non-idempotent mutation with 5 params, no output schema, and 60% schema coverage, the description does cover the single-key scope and the draft-staging behavior. However it omits the draft lifecycle (how the staged change reaches the live site) and any failure/partial-application behavior, leaving real gaps.

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

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

Schema coverage is 60%; get_context's 'context' and guestToken are already documented in the schema. The description adds grouping meaning by telling the agent ops[] splits into selector ops vs replace-string families, and defers detail to the schema. Useful but shallow – it names no field like 'expect' or 'selector' semantics.

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+scope: 'Edit one content key via ops[]', which distinguishes it from batch_patch_content (batch scope) and put_content (whole-key write). The parenthetical '(selector ops or replace-string)' clarifies the two editing modes. It doesn't name siblings explicitly, so 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?

No when-to-use, when-not-to-use, or alternative named. The word 'one' implicitly contrasts with batch_patch_content and find_replace, but the agent must infer that. No prerequisites or follow-up guidance (e.g. how the staged draft gets applied) are given.

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