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

Annotations only provide read/destructive hints, so the description carries additional weight. It usefully discloses that nested subtrees are supported and that one call can create a whole section. However, it does not describe return behavior, side effects of force/dry_run, or ordering 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 purposeful, front-loaded sentences: the first states the core action, the second reinforces the critical nesting behavior. There is 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?

The tool has a nested spec, five parameters, and no output schema, yet the description covers the main required usage pattern well. Gaps remain around optional parameters like dry_run and index, and the description does not explain what the call returns or how errors/side effects behave.

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 low (only 'force' has a description), so the description must compensate partially. It adds meaning by clarifying that 'parent_id' is the parent target and that 'children' builds a nested subtree in one call. It leaves index, dry_run, and most spec fields without added semantic explanation.

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

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

The description clearly names the action ('Add'), the target ('under a parent'), and the key differentiator ('whole NESTED subtree', 'complete section'). It is specific enough to be understood, though it does not explicitly contrast with sibling tools like sb_set or sb_duplicate.

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 provides concrete usage guidance: use one call to add an element or build a complete section by passing children rather than calling per node. It lacks explicit when-not-to-use or alternative-tool routing, 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?

The description adds 'dry run by default' which is crucial context given destructiveHint=true, and the note about lists over 60 KB is a useful behavioral quirk. It goes beyond the annotations by clarifying the default safety behavior. However, it doesn't describe what happens when dry_run is false (actual side effects) or how openWorldHint affects external systems, so it's not fully transparent.

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

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

Two sentences, front-loaded with the core purpose and the dry-run default, followed by a compact explanation of the key parameters. Every sentence serves a purpose and there is no redundancy or 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 tool with 10 parameters and no output schema, the description is relatively short. It covers the primary decision (id vs method+path) and the dry-run default, but omits guidance on query, body, path_params, and how they interact. The 60 KB note is a minor quirk, not a comprehensive description of response behavior. While essential information is present, the overall completeness for such a complex tool is only adequate.

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

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

The description explains pick (field selection), max_items (capitalization), item_offset (item skipping), and the id vs method+path distinction. This adds value especially for pick and max_items which lack schema descriptions. With only 50% schema coverage, the description compensates for some but not all parameters; query, body, and path_params are left unexplained, which is a gap but not severe given the tool's general purpose.

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

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

The description clearly states the two modes of operation: using an operation id from sb_api_find, or providing a method+path for routes the catalog lacks. This distinguishes it from the sibling sb_api_find and other tools, and the specific phrasing leaves no ambiguity about what the tool 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?

It explicitly explains when to use id (when you have an operation from sb_api_find) and when to use method+path (routes the catalog lacks). This gives clear decision context. However, it doesn't explicitly mention alternatives or say when not to use this tool (e.g., for other operations that belong to different siblings), so it misses the exclusionary guidance that would earn a 5.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful context about what is returned: parameters, credential, body fields, and handler caveats. It also notes the tool 'reaches all 560 operations,' but does not disclose any additional behavioral nuances such as how empty calls behave or whether results are paginated.

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

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

The description is two focused sentences, front-loading the core purpose and then adding the call-sheet details and broad coverage. Every clause earns its place with no filler.

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

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

With no output schema, the description usefully names the call-sheet contents and overall scope. It does not explicitly state what happens when no query or id is provided, and how tag and limit interact is left to the schema, but the schema examples and defaults mitigate this 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 100%, so the schema already explains the parameters well. The description adds framing for query and id, but does not provide additional semantic detail beyond what the schema already includes.

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

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

The description clearly states the tool's verb and resource: 'Find API operations' by intent, or retrieve a 'call sheet' for a specific id. It distinguishes the two primary modes of use, though it does not explicitly name sibling tools to differentiate 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?

The description gives explicit entry points: use a query to search by intentholiday, or use an id to get a call sheet. It provides clear context for when to use the tool, but does not state exclusions or compare against alternatives like sb_api_call.

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

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

The description indicates the tool modifies a node by binding it to real data, implying a mutation. This aligns with the annotations (readOnlyHint=false). It also discloses that the action parameter turns a button into a purchase control, which is a specific side effect. However, it doesn't mention whether changes are reversible or if there are any guards beyond the 'force' parameter.

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

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

The description is extremely concise, with only two sentences. It front-loads the main purpose and avoids redundancy. Every word contributes to the meaning.

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

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

Given the tool has six parameters and no output schema, the description is too sparse. It doesn't explain what 'id' refers to, how 'source' should be used, or the behavior of 'force' and 'dry_run'. The agent needs more context to call this correctly, especially with many sibling tools.

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

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

The description only mentions the 'action' parameter and doesn't explain 'id', 'source', 'force', or 'dry_run'. The schema provides descriptions for field, action, and source, but not for id, force, and dry_run. With 67% schema coverage, the description should compensate for the gaps, but it doesn'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?

The description clearly states the tool binds a node to real store data, which is a specific action. It also notes that 'action' makes a button a purchase control, adding a concrete use case. While it doesn't explicitly distinguish from siblings like sb_connect, the core purpose 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 description offers no guidance on when to use this tool versus alternatives such as sb_connect or sb_live_join. It doesn't mention prerequisites, scenarios, or exclusions. An agent would have to infer usage from the name and context.

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

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

Annotations already declare readOnlyHint: true, so the safety profile is covered. The description adds useful behavioral context: omitting query browses all types, and detail:true behaves like sb_traits_for. It doesn't describe return format or pagination, but given the read-only annotation, a 3 is appropriate.

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

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

The description is two sentences with zero filler. It front-loads the primary purpose, then adds the browse-omission behavior and the detail alternative succinctly. 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 read-only search tool with 3 optional parameters and no output schema, the description covers the core usage patterns (query vs. browse, detail flag). It doesn't specify the return format or how limit behaves, but those are implied or in the schema, and the read-only annotation covers the safety profile. Slightly incomplete but adequate.

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

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

Schema coverage is 67% (limit and detail have descriptions, query does not). The description adds meaning to query by explaining it as 'by what it does' and clarifies detail's effect, partially compensating for the missing query description. It doesn't elaborate on limit's usage beyond the schema's default note.

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

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

The description clearly states the tool's purpose: 'Find an element type by what it does' – a specific verb (find) and resource (element type). It also distinguishes itself from siblings by mentioning that detail:true provides the same AI hints as sb_traits_for, and that omitting query browses all types, which differentiates it from other catalog 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 gives explicit guidance on when to omit query (to browse every type and discover unknown elements) and notes an alternative for AI hints (sb_traits_for). However, it doesn't explicitly state when not to use this tool versus other siblings like sb_site_list or sb_look, leaving some ambiguity.

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

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

The annotation already marks the call read-only, so no safety contradiction exists. The description adds meaningful behavior beyond that: it authenticates through environment variables unless credentials are passed explicitly, and it is intended as the initial bootstrap call.

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

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

Two short sentences with no filler; the main purpose, ordering requirement, and credential fallback are each stated once and front-loaded.

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

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

For a simple two-parameter bootstrap tool, the description covers purpose, output ('list the sites'), ordering, and credential handling. It remains slightly incomplete because it does not clarify whether login is a persistent session or how it relates to sb_site_list, but no output schema exists so the stated output is still 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 coverage is 0% and the schema gives only type names, but the description clarifies that email and password override environment-provided SB_EMAIL and SB_PASSWORD. This is useful semantic info for deciding whether to pass the parameters at all.

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

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

The description states a specific action ('Log in and list the sites this account can operate') with a clear resource. It is not a tautology and is easy to understand, but it does not explicitly distinguish itself from the nearby sb_site_list tool, which likely also relates to listing 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?

The instruction 'Call this first' gives explicit ordering guidance, and the note about reading SB_EMAIL and SB_PASSWORD tells the agent when parameters can be omitted. It does not state when not to use it or name alternatives such as sb_site_list, so it falls short of full alternative 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 indicate readOnlyHint=false and destructiveHint=false, so mutation is implied but not risky. The description adds 'fresh ids' and 'right after the original', which are useful behavioral specifics. However, it does not explain the 'force' parameter or what happens with dry_run, nor any side effects like affecting parent structure. No contradiction with 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 concise sentences with no wasted words. The core functionality is front-loaded, and the casual example reinforces the purpose without adding bulk. Perfectly sized for an MCP tool description.

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

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

Given the moderate complexity (3 params, no output schema), the description covers the main action but leaves gaps around parameter behavior and edge cases. It is not overly incomplete, but an agent might need to infer the function of 'force' and 'dry_run' or explore the tool schema 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 description coverage is only 33%, meaning the 'force' and 'dry_run' parameters have no schema descriptions. The description provides no additional meaning for these parameters, leaving them ambiguous. It only clarifies the 'id' parameter implicitly through the context of copying a node, but fails to explain the guard that 'force' overrides.

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

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

The description clearly states the verb 'Copy' and the resource 'node and everything under it', plus the specific behavior of placing the copy 'right after the original' with 'fresh ids'. This distinctly separates it from siblings like sb_add, sb_set, or sb_move, which involve different 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?

The description implies common usage ('move a designer makes constantly') but does not explicitly state when to use this tool versus alternatives like sb_move or sb_add. It lacks explicit exclusions or conditions that would route the agent clearly to this tool over others.

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

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

The annotations already mark the tool as non-read-only and non-destructive, and the description adds useful semantic context: 'A wrong one is refused with the list.' However, it does not disclose side effects, return values, or the meaning of force/dry_run beyond what the schema provides.

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

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

The description is two focused sentences with no filler. It front-loads the main purpose and immediately presents the key alternative, making it easy for an agent to parse quickly.

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 covers the primary use case and the main alternative, but the tool has 6 parameters, no output schema, and sparse annotations. An agent would still lack guidance on force, dry_run, payload, and the expected result of the operation.

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

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

The description adds meaning to the action parameter with examples ('open the cart, go to a page, open a pop-up') and clarifies the exclusion of purchase actions. With schema description coverage at only 50%, it does not compensate for undocumented parameters like payload, force, dry_run, and trigger.

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

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

The description uses a specific verb and resource: 'Give a node a click action' with concrete examples like opening the cart, going to a page, or opening a pop-up. It also explicitly excludes purchase actions and points to sb_bind, which clearly differentiates it from 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 gives an explicit when-not condition: a purchase is not a click action and should use sb_bind instead. This directly tells the agent the main decision boundary between sb_event and its sibling.

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 say readOnlyHint=false and destructiveHint=false, and the description goes further by disclosing exactly what happens: real elements are added to the OPEN page, foreign layout/CSS is discarded, and dry run returns findings instead of mutating. It does not mention that image copying uploads into the media library or the cost/latency of fetching a remote origin, which the schema only partially covers.

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

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

Three tight sentences, front-loaded with the core action, then the key scope caveat, then the dry-run behavior. Every clause carries information an agent needs 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 8-parameter mutating tool with no output schema, the description covers the essential behavior and the dry-run return path. It leaves a gap around prerequisites (an OPEN page must already exist, likely via sb_page_open) and around image-upload side effects, which matter for correct invocation.

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

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

Schema coverage is 63% and the description only adds semantics for dry_run ('returns what was found'). dry_run, site_id, and max_sections carry no description in either place, and nothing explains how max_nodes/max_images bound the import beyond what the schema already says.

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

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

States a specific verb+resource+destination: read a public URL page and add its structure/content as real elements into the currently OPEN page, styled with the page's own tokens. It also clarifies scope negatively ('Not a clone: the source's layout and CSS are not copied'), which separates it from a full-site importer like sb_import_site.

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 — reach for it when you want a page's content merged into the open page — but no alternative is named and no when-not condition is given. The sibling sb_import_site (site-level import) is never referenced, so the agent must infer the boundary itself.

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 (so the agent knows it mutates) and openWorldHint=true. The description adds valuable context beyond annotations: 'Dry run returns the page list before anything is created', clarifying the dry_run side effect, and 'Not a clone' sets expectations about output nature. However, it doesn't address permissions required, rate limits, or what happens to the site's existing pages (creation vs. overwrite), leaving some mutation risk opaque.

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

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

The description is two concise sentences that front-load the core action ('Read a WHOLE site from one URL') and then add the dry run note. It's efficient with no fluff, though the second sentence is a fragment that could be integrated more smoothly.

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 14-parameter, mutation-heavy tool with no output schema and 71% schema coverage, the description is somewhat thin. It doesn't explain return values beyond the dry run case, doesn't mention failure modes or whether existing pages are affected, and omits guidance on common pitfalls like theme being 'SITE-WIDE'. It's adequate but leaves 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 71%, so the schema covers most parameters, but several key parameters lack descriptions (e.g., dry_run, exclude, upload_images, site_id). The description adds meaning for the overall import behavior (sitemap vs. link crawling, draft creation) but doesn't compensate for the gaps in the schema's parameter documentation, such as the exact format of include/exclude paths or the effect of site_id.

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+resource ('Read a WHOLE site from one URL' and 'give each page found its own DRAFT page'), and clearly distinguishes the tool from the sibling 'sb_import' by specifying site-level reading. It's clear what the tool does, though the phrase 'built from this site's tokens' is a bit jargon-heavy and 'Not a clone' adds ambiguity about what exactly is produced.

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 gives no explicit when-to-use guidance versus alternatives like sb_import or sb_page_create. It mentions dry run behavior but doesn't say when to prefer this over a single-page import or manual page creation. No exclusions or prerequisites are mentioned.

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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds context beyond these: it explains that writes appear live in editors, the agent is shown by API key name, and that it always yields (safe concurrency). It also clarifies authentication requirements (SB_TOKEN or SB_EMAIL/SB_PASSWORD). This is valuable behavioral disclosure without contradicting 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?

The description is three sentences, with the core action and effect front-loaded. It includes relevant details (visibility, naming, concurrency safety, auth) without excessive verbosity. It could be slightly tighter, but it is well-structured and each sentence adds value.

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 join operation, the description covers the main behavioral aspects, safety, and authentication. It does not describe a return value (no output schema exists), but that is not critical for a side-effect action. It does not mention prerequisites like having a site ID or being connected, but the single parameter and context make this reasonably 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?

The schema defines a single parameter site_id (string) with zero schema description coverage. The description does not explain what site_id refers to or how to obtain it. It only mentions 'the site's live-edit room' but never explicitly maps site_id to that. Since coverage is 0%, the description should compensate, but it does not. The parameter name is somewhat self-explanatory, but no guidance is given on values or format.

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

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

The description states a specific action ('Join the site's live-edit room as a visible peer') and explains the observable effect (writes appear in editors, agent shown by API key name). This clearly distinguishes it from siblings like sb_page_open or sb_connect, which handle different operations. The purpose 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 description notes it 'always yields, so it is safe beside a human,' which implies it's suitable for concurrent use with human editors, but it does not explicitly state when to choose this tool over alternatives or when to avoid it. No comparison to siblings like sb_connect or sb_page_open is given. The guidance is implied rather than 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 idempotentHint=true and destructiveHint=false, so the description does not need to repeat those. It adds valuable context about the platform's own renderer, the outputs (screenshots, boxes, defects), and the node_id framing behavior, which goes beyond the structured annotations. No contradiction with annotations.

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

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

The description is two sentences: the first front-loads the core purpose and outputs, the second gives usage guidance. Every word serves a purpose, with 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?

The description covers the main outputs (screenshots, boxes, defects) and gives purpose, but it does not specify the response structure or how to interpret the defect data. It also omits details on the widths array and with_boxes parameter, leaving some ambiguity for a tool with 6 parameters and no output schema.

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

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

Schema description coverage is 67%, so the baseline is 3. The description adds meaning for url (via published storefront mention), format (jpeg/png), node_id (frames one element), and box_depth (bands and children), but it does not clarify the widths array format or with_boxes behavior, which lack schema descriptions. It partially compensates for the coverage gap but not fully.

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

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

The description clearly states the tool saves, renders, and returns screenshots at multiple widths, measured boxes, and layout defects, giving a specific verb and resource. It also mentions node_id to frame one element, but does not explicitly contrast with sibling tools like sb_outline or sb_node_read, though the features are distinct enough.

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 usage for visual evaluation with 'Judge your work from these, not from memory,' giving context on when to use it. However, it does not explicitly state when not to use it or name alternatives among the many sibling tools, leaving 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 provide readOnlyHint=true, so the read-only nature is known. The description adds that it is a library and supports search/filter/pagination, but it doesn't describe the return format, default pagination limits, or any side effects (none expected). Since annotations cover safety, this is acceptable but not rich.

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

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

The description is a single sentence that starts with the core purpose ('The site's media library'), then provides usage guidance and parameter hints. It is concise and front-loaded, though the phrase 'Reuse an image before adding another' is more of a policy than a functional description, which is acceptable.

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 listing tool with all optional parameters, the description covers the main usage patterns. However, it doesn't explain the return value, the role of site_id, or default pagination behavior. Since there is no output schema, a bit more detail on what is returned would improve 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?

The schema only documents 'media_type' (with an example). The description covers 'search' (search by name), 'media_type' (filter by type), and 'limit'/'offset' (page with limit/offset). It does not mention 'site_id', which remains undocumented. Given low schema coverage (20%), the description compensates well for most parameters but misses site_id.

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 this as the site's media library and lists operations (search, filter, page) that imply a listing/retrieval tool. It doesn't use an explicit verb like 'list' or 'get', and it doesn't differentiate from sibling list tools such as sb_page_list, but the name 'sb_media_list' clarifies the action.

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 instruction to 'reuse an image before adding another' clearly indicates when to use this tool: to find existing media before uploading new ones. It also outlines usage patterns (search by name, filter by type, page with limit/offset). However, it doesn't explicitly name alternatives like sb_media_upload or state when not to use it.

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

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

Annotations establish a non-read-only, non-destructive operation; the description adds valuable behavioral detail beyond them by explaining the return value (URL), accepted input sources, the query/pick search behavior, and the ability to upload several images at once. It does not explain edge effects like dry_run or failure modes, but it remains consistent with the annotated 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?

Three compact sentences front-load the core purpose and then add the necessary source modes and search behavior. There is no filler or repetition; every clause earns its place, and the most important usage guidance is stated early.

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

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

Given a 9-parameter tool with no output schema, the description provides a strong overall mental model: what it does, what it returns for media, the input modes, and batching behavior. However, it leaves several parameters unexplained and does not describe what dry_run or folder_id/site_id do, so it is not fully complete at the invocation level.

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 44%, so the description must compensate. It meaningfully clarifies the key mode semantics (path vs URL vs query+pick, and pick accepting one or many), but it never explains name, dry_run, site_id, folder_id, or orientation. Thus it partially closes the coverage gap but does not fully compensate for the undisclosed parameters.

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?

Description clearly states the action ('put an image into the media library'), the resource, and the key output ('get its URL back'). It also distinguishes itself from siblings by naming the downstream tool sb_set and declaring 'The only way to add an image', so an agent can identify it confidently.

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 tells an agent when to use it: to add an image, it takes either a local path, a URL, or a search/query flow. It additionally explains how query and pick work together, and 'The only way to add an image' strongly signals it over alternative siblings. It lacks explicit conditions for when to avoid it, but the guidance is otherwise clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds the core repositioning behavior. However, it does not disclose side effects such as whether children are preserved, what happens to the old parent, or what force/dry_run actually do at runtime.

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

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

The description is a single concise sentence with no filler. The essential operation and target are front-loaded.

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

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

For a mutating tool with five parameters, no output schema, and an unexplained guard flag (force) plus dry_run, this description is too thin. An agent would need to infer conventional semantics for the optional parameters and possible side effects.

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 phrase 'another parent at an index' gives meaning to the required parameters id, parent_id, and index. Since schema description coverage is only 20%, the description should also clarify optional parameters, but dry_run is left undocumented and force is only explained 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?

The description names a specific verb (Move), a resource (node), and a target location (another parent at an index). This clearly distinguishes it from sibling tools like sb_remove, sb_duplicate, and sb_add.

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 tool's intended use is implied by the action word 'move', but there is no explicit guidance on when to choose it over alternatives such as sb_duplicate, sb_set, or sb_remove. No exclusions or decision criteria are provided.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context by listing what the full node result contains: style, config, specials, per-breakpoint overrides, and bindings. This goes beyond the annotation and sets expectations for the response content, though it does not discuss error behavior or invalid IDs.

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

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

The description is a single front-loaded sentence with a dash-separated list of content categories. Every word adds information, and there is no redundant phrasing or 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 simple one-parameter read tool with a readOnly annotation and no output schema, the description covers the key invocation context: a single node, full detail, and the major content sections returned. It is nearly sufficient but lacks explicit guidance on when to choose this over sibling read-ish tools like sb_outline, sb_look, or sb_traits_for.

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 0%, and the only parameter 'id' is documented only as a string. The description implies the id identifies a node but does not state its format, how to obtain a valid value, or any constraints. With the schema providing no semantics, 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 states 'One node in full' and enumerates the content returned (style, config, specials, per-breakpoint overrides, bindings), clearly identifying a single-node read operation. The name and 'one node' scope distinguish it from search/list siblings like sb_catalog_search and sb_page_list, though the description never explicitly uses a verb like 'read' or 'retrieve'.

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 'One node in full' implies this tool is for retrieving complete node details rather than just outlines or traits, but there is no explicit when-to-use guidance or comparison with read-like siblings such as sb_outline, sb_look, or sb_traits_for. Usage context is implied, not stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful behavior: it returns a compressed tree, never the raw document, and reveals the included node attributes. It does not cover depth-related behavior, but the read-only nature and output scope are clearly communicated.

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

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

The description is short, front-loaded with the core idea, and every sentence earns its place. It efficiently communicates what the tool returns and what it never returns, without unnecessary fluff.

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 outline tool with one optional parameter and no output schema, the description covers the return shape and the key non-behavior. The main gap is the missing semantics of the depth parameter, but the overall context is still adequate for an agent to use the tool correctly in common cases.

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

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

Schema description coverage is 0%, and the description does not explain the depth parameter at all. While the schema gives the parameter name, type, and bounds, the agent is left to infer what the depth controls and what the default behavior is when omitted. The description should compensate for the lack of schema descriptions but does not.

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

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

The description clearly states that the tool returns the open page as a compressed tree and lists the exact fields included. It distinguishes the output from the raw document of the page, which differentiates it from raw page retrieval, though it does not explicitly name sibling 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?

The description gives clear context: use this when you need a compact structural overview rather than the raw page JSON. The explicit warning 'Never the raw document' effectively tells the agent when not to expect full content, but it does not name specific sibling tools or elaborate on when to choose 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 provide only readOnlyHint=false and destructiveHint=false. The description adds some behavior about type-specific seeding and routing, but it is confusing and omits core effects like idempotency, prerequisites, or what happens to existing pages. No contradiction, but insufficient clarity.

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

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

The description is a run-on, ungrammatical sentence that buries the main purpose. It is not front-loaded and requires significant parsing; conciseness is confused with vagueness.

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 11-parameter tool with no output schema and minimal annotations, this description is far from sufficient to invoke the tool safely. Key parameters, return behavior, and use cases are 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 45%, so the description must compensate. It clarifies 'seed:false for blank' and that type determines routing, but leaves name, slug, site_id, dry_run, settings, and is_homepage unexplained 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 description never plainly says 'create a page'; it uses cryptic phrasing like 'a store type arrives with the document' and 'seed:false for blank'. It does not clearly name the verb+resource and does not differentiate from siblings like sb_page_open or sb_page_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?

The description references sb_page_open and sb_page_list but gives no explicit guidance on when to use sb_page_create versus those tools. The routing/404 note concerns page requirements, not tool selection.

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

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

The readOnlyHint annotation already marks this as read-only, and the description adds the output shape (slug and live status). It does not mention ordering, pagination, or behavior when site_id is absent, but those are not major concerns for a simple list operation.

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

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

The description is a single concise sentence with no redundant wording, and the core purpose is front-loaded.

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 list tool, the description provides the output fields and read-only nature, but it omits the only parameter from the schema and does not clarify usage boundaries relative to sibling tools. It is adequate but not comprehensive.

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

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

The input schema has one optional site_id parameter, but the description does not clearly explain its meaning, whether it filters results, or what happens when it is omitted. The phrase 'on the site' gives some context but leaves a significant gap in parameter understanding.

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

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

The description clearly identifies the resource (pages) and the nature of the output (all pages with slug and live status), even though it uses the declarative 'Every page' rather than an explicit verb like 'List'. It is reasonably distinct from sibling tools like sb_page_open and sb_page_create.

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 tool to call when all pages and their live status are needed, but it does not explicitly state when to prefer it over alternatives such as sb_page_open, sb_page_create, or sb_site_list, nor does it mention the effect of omitting site_id.

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?

While the readOnlyHint annotation declares safety, the description adds behavioral context by explaining the tool is a prerequisite for mutations and returns an outline. It does not explicitly state it is read-only, but the annotation covers that.

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

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

The description is two concise sentences, front-loaded with the primary purpose and followed by clear usage instructions. No filler or redundant 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 description provides sufficient context for a straightforward tool: it explains when to call it and how to obtain identifiers. It does not detail return format or error cases, but these are not critical for an outline-returning read operation.

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

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

The schema has no parameter descriptions, and the description only indirectly hints at page_id's purpose via the reference to finding page IDs. site_id is completely unexplained, leaving agents to infer its 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?

The description clearly states the action (open a page for editing) and the return value (outline), and distinguishes it from sibling tools by specifying it should be called before mutation operations and referencing how to find page IDs.

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 the tool ('Call before any sb_add / sb_set / sb_move / sb_remove') and provides guidance on obtaining page IDs via sb_api_find.

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

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

Annotations only say readOnlyHint=true, and the description adds substantial behavioral context: the hydrate gate silently discards documents with a missing root, the Go renderer lacks this gate, and this explains the live-has-data-but-canvas-empty state. It also clarifies the tool reports draft-vs-live differences and recovery points, going well beyond the annotation.

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, but the second sentence is dense and rambling, with a long parenthetical about hydrate gates and renderer differences stuffed into a clause about blank rendering. The information is valuable, but the structure makes it harder to parse than necessary.

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 explaining what the tool reports; it covers copy identity, blank-canvas behavior, draft/live changes, and recovery points. It is complete enough for an agent to know when and why to call it, though 'recovery points' and 'what this session holds' remain somewhat underspecified.

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 50%, with site_id undocumented, and the description does not mention parameters at all. It indirectly refers to 'this page,' aligning with page_id's default, but it adds no meaning for site_id or how the page context is resolved.

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

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

The description clearly identifies the resource (this page's three copies) and the specific diagnostic outputs: which copy is draft/published/session, whether the canvas will render blank, whether the draft differs from live, and where recovery points are. This is distinct from sibling tools like page_open, node_read, or outline, so an agent can tell what this tool is for.

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 scenario described: diagnose which copy is which, understand why the editor canvas is blank while live data exists, or locate recovery points. However, there is no explicit statement of when to choose this over sibling diagnostic tools, nor any exclusions or 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?

Beyond annotations (destructiveHint: true, idempotentHint: true), the description adds substantial behavioral detail: the cascade republishing of shared global sections, the verify flag's fetch-and-report semantics, and the 60-second storefront cache explanation. This goes well beyond the annotations and helps the agent anticipate side effects.

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

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

The description is dense yet well-structured. It front-loads the core action and result, then explains the cascade side effect, then the verify option with its caching nuance. Every sentence adds essential information without fluff, and the logical flow makes it easy to parse.

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 publish action with no output schema, the description covers the return value, the primary side effect (cascade), and the optional verification behavior. The only gap is the lack of explanation for dry_run and site_id, but these are relatively self-explanatory given the context. Overall, it is nearly complete for an agent to call 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 only 25% (only 'verify' has a description). The description explains verify's behavior in detail but provides no additional meaning for page_id, site_id, or dry_run. Since coverage is low, the description should compensate by clarifying all parameters, but it only covers one. The cascade explanation implies page/site context but does not define the parameters themselves.

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 clear verb+resource: 'Compile the draft into the live page', and specifies the output (revision id, publishedAt, fromVersionId). It distinguishes from siblings by being the only publish-related tool among the many page-editing tools, and the cascade note further clarifies its scope.

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 provides clear context for when to use the tool (to publish a draft) and explains the cascade behavior, which is a critical 'when to expect side effects' note. However, it does not explicitly compare to alternatives or state when not to use it, but given the sibling list has no other publish tool, this is implicit.

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, so the destructive nature is known. The description adds valuable context beyond the annotation by specifying that the whole subtree is removed, not just the node itself. However, it does not mention irreversibility, dry-run behavior, or any side effects beyond the subtree scope.

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

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

The description is a single sentence with no filler. Every word contributes meaning, and the most important scoping detail ('whole subtree') is included. It is appropriately concise and front-loaded.

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

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

Given that this is a destructive tool with no output schema and three parameters, the description is too thin. It does not clarify what a successful removal returns, what dry_run does, how force behaves, or whether the operation can be undone. The annotations cover safety but not runtime behavior.

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 33%, and the main description does not explain any parameters. The required 'id' is implied by 'Remove a node' but not explicitly tied to the parameter, and 'dry_run' has no semantic guidance at all. The description fails to compensate for the sparse schema documentation.

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

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

The description uses a specific verb ('Remove') and a clear resource ('a node and its whole subtree'), and it is easily distinguished from sibling tools like sb_add, sb_set, or sb_move. It also adds the important scoping detail that the entire subtree is affected, which makes 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?

The description gives no guidance about when to use this tool versus alternatives, when not to use it, or what prerequisites apply. While the verb 'Remove' implies usage, there is no explicit routing or exclusion compared with related operations like sb_undo or sb_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?

The annotation readOnlyHint=true covers safety, so the description does not need to reiterate that. However, the description does not state what the tool actually returns or what side effects (if any) it has beyond reading. It lists areas of focus (visitor experience, conversion blockers) but remains vague about the behavioral outcome, such as whether it produces a report, a score, or just passes/fails. No contradiction, but limited added context beyond the annotation.

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

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

The description is two sentences and relatively compact. It front-loads the core concept ('What a VISITOR would meet') and adds a usage instruction. However, the jargon ('blank band, placeholder, dead binding') may confuse without context, but it is still concise overall.

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 and only this description, the tool's behavior and return value are not fully specified. The description lists what the tool considers (page elements and conversion blockers) but does not explain what the agent will receive after calling it (e.g., a list of issues, a success/failure flag, or a report). For a review tool that is meant to be used before finishing a page, the expected output is critical. This is a significant gap.

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

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

The tool has zero parameters, so the description is not required to explain any. The baseline for no parameters is 4, and the description does not introduce any parameter-related ambiguity. It correctly focuses on the tool's purpose rather than parameter details.

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 implies a review/audit of a page from a visitor's perspective, mentioning specific elements like 'blank band, placeholder, dead binding' and conversion blockers. However, it does not state a clear verb+resource (e.g., 'reviews the page for issues') and does not distinguish it from sibling tools like sb_outline or sb_look, which might also inspect pages. The purpose is inferable but not explicit.

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 instructs to 'Run it before calling a page finished,' which is a clear usage context. It does not mention when not to use it or alternatives, but the timing guidance is specific and actionable. It implies this is a pre-publication check, which is useful.

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 mark the tool as non-read-only and non-destructive, so the description carries the burden of explaining actual behavior. It adds meaningful detail: edits apply in one save/live frame, breakpoint is the default scope, and base:true targets the fallback layer. It does not discuss side effects like unset or force, but it does not contradict the annotations either.

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

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

The description is only two sentences, front-loaded with the core operation and with no filler. The second sentence adds genuinely important base/breakpoint guidance rather than restating the schema.

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

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

Given 10 parameters, nested edit objects, and no output schema, the description alone is not complete: it does not explain how a node is identified, what state and unset mean, or what edits require structurally. The schema fills many gaps, but the prose still leaves important selection and invocation questions 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 only 30%, so the description needs to compensate, and it does add meaning for base, breakpoint, namespace, and edits. However, it leaves id, state, unset, force, and dry_run unexplained in prose, relying on the schema to carry those details.

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 operation — 'Write style, config or specials keys' — and clearly scopes it to one node or many through edits. This distinguishes it from sibling mutation tools like sb_add or sb_remove, and the base:true clarification removes ambiguity about which layer gets written.

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 provides useful context such as 'Per BREAKPOINT by default' and using base:true for values that should not vary, which implies when certain parameters matter. However, it never explicitly says when to use sb_set versus an alternative, nor does it mention when not to use it.

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

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

The readOnlyHint annotation already establishes the operation is safe and non-mutating. The description adds the account-scoping detail ('this account can operate') but does not disclose return format, ordering, pagination, or failure modes. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single, efficient sentence with no filler. It states the action, resource, and scope immediately, earning its place entirely.

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 zero-parameter read-only list tool, the description is largely sufficient. The only minor gap is that no output schema exists and the description does not specify the exact shape of the returned site list, but 'List the sites' strongly implies a straightforward enumeration.

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 are zero parameters, so the description does not need to explain any. The empty schema is fully covered, and the baseline for a zero-parameter tool is 4.

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

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

The description uses a specific verb ('List') and resource ('sites') with a clear scope ('this account can operate'). It clearly identifies the tool's function and is easily distinguishable from sibling tools like sb_page_list or sb_media_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?

The description implies usage: call this when you need to see which sites are available to the account. However, it does not explicitly state when to use this over alternatives or mention any exclusions, so the guidance is only implied rather than direct.

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

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

The description discloses side effects for each action: checkout 'creates and PUBLISHES', form 'seeds', chrome 'gives every page ONE shared header', overlay_attach 'puts a pop-up' and 're-reads the page', app 'installs', global_attach/detach 'puts/takes off'. It also notes a dry-run plan. These go beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) and add critical behavioral context such as the fixed order and re-reading behavior. No contradiction with annotations.

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

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

The description is long but structured effectively by action, with each action receiving one to two sentences. It front-loads the core purpose and then systematically covers each mode. While verbose, the complexity of the tool justifies the length; it avoids fluff and stays factual.

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 detailed but omits some essential context: it does not specify the exact 'fixed order' it claims is required, nor does it describe return values beyond the dry-run plan. It also lacks error conditions or prerequisites (e.g., whether a page must be open). Given the absence of an output schema, these omissions leave the agent under-informed about expected outcomes and sequencing.

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?

Despite only 63% schema coverage, the description explains the role of most parameters within the context of each action. For instance, it clarifies how 'kind', 'list_id', and 'overlay_id' are used in overlay_attach, 'template' and 'name' for form, 'app_key' for app, and 'global_id' for global_attach. It also explains the 'footer' flag for chrome, filling gaps the schema leaves open. This adds significant meaning beyond the bare property names.

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 clear verb and resource: 'Run a store flow that must happen in a fixed order.' It then enumerates eight distinct actions, each with a specific purpose (e.g., 'checkout' makes, configures, saves, and publishes a checkout page). This distinguishes the tool's modes and their effects clearly, avoiding tautology and ambiguity.

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 provides internal usage guidance, such as using global_attach instead of chrome when a page lacks the header ('where action:"chrome" would wrongly build a second one'). It also references diagnostic context (sb_review reports siteChrome). However, it does not explicitly compare this tool to sibling tools or state when not to use it overall, 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?

The annotation readOnlyHint=true already indicates a read-only operation. The description adds context that these are 'saved' templates, implying a listing of pre-existing sections. It does not contradict the annotation, and it provides a small amount of extra context beyond what the annotation conveys, but it does not disclose any additional behavior such as return format, pagination, or filtering.

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

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

The description is concise (two sentences) but not well-structured for an action-oriented tool. The first sentence is a noun-phrase definition, not an imperative or verb-led description, so the primary purpose is not front-loaded. The second sentence directs to a sibling, which is useful but does not clarify the tool's own action. It is efficient but structurally weak.

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

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

For a tool with no output schema and only one optional parameter, the description fails to explain what the tool returns, how the site_id parameter affects results, or any other usage details. An agent cannot know what to expect from the call or how to interpret the response. The description is inadequate for safe and correct invocation.

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

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

The input schema has one parameter (site_id) with no description, and the schema description coverage is 0%. The description does not mention this parameter at all, leaving the agent to guess its purpose (likely identifying the site). With zero coverage, the description is expected to compensate, but it fails to do so, making this a critical 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 'the store's saved section templates' and distinguishes it from sb_template_use by stating that the sibling is for applying them. However, it never states the actual operation (e.g., 'list', 'get', 'browse'), leaving the agent to infer that this tool retrieves or lists templates. The purpose is clear in context but not explicit, so it does not fully meet the standard of a specific verb+resource.

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 mentions sb_template_use as an alternative for applying a template, but it does not state when to use this tool itself. There is no explicit guidance such as 'use this to view available templates before applying' or any conditions or prerequisites. The implied usage (to see templates) is not clearly articulated, so the guidance is minimal.

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 indicate this is not read-only and not destructive. The description adds useful behavioral detail: site's own templates are copied by the server, while built-in layouts are composed against the page's tokens rather than copied. This clarifies the side-effect model beyond the boolean hints. It does not address dry_run semantics or reversibility, but the core behavior is transparent.

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

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

One dense sentence, front-loaded with the core action and all key distinctions (own template copied vs built-in composed). No fluff, though the grammar is slightly convoluted.

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 covers the main template-id and page-id semantics and the own-vs-built-in distinction, but omits dry_run and site_id behavior and says nothing about return values or side effects. Acceptable for selecting the tool, incomplete for fully invoking with all options.

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 schema description coverage at 0%, the description must compensate, but it only indirectly clarifies template_id and page_id. It says nothing about dry_run or site_id, leaving two parameters semantically unexplained. Some value is added for template selection, but the compensation is incomplete.

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 specific verb, 'Instantiate a section template into a page,' and clarifies the two source types: the site's own templates (server copies) and BUILT-IN layouts listed by sb_templates. This clearly distinguishes the tool from siblings like sb_templates and states the exact action.

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 provides clear context about when to use the tool (to instantiate a section template) and refers to sb_templates for built-in layouts, giving the agent a pointer to a sibling tool. It does not explicitly state when not to use this tool versus alternatives, but the built-in vs. site-own distinction is a strong usage signal.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains the tool operates in two modes: read-only when empty, and patch when colors/text_styles are supplied. It also discloses that unmentioned fields are preserved, which is valuable behavioral context. It does not contradict the annotations, since PATCH is consistent with readOnlyHint=false and 'kept' fields align with destructiveHint=false.

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

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

The whole description is two sentences that pack the core function, the read/patch duality, and the merge behavior without repetition. The cause-effect phrasing 'so one token repaints every page at once' is concise and adds the key consequence. No wasted or unrelated 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 description tells an agent how to read and how to patch safely, and the merge behavior is well communicated. But it omits what dry_run actually does, what site_id refers to, and what the result of the operation looks like. With 4 parameters and no output schema, these missing pieces keep the description 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?

The description adds meaning to colors and text_styles by tying them to the PATCH operation and merge semantics. However, dry_run and site_id are not described in either the schema parameter descriptions or this prose, and at 50% schema coverage the description needs to compensate for those gaps. It fails to do so, leaving the agent to guess at those two parameters.

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 ('the site's palette and type scale') and the actions ('read' / 'PATCH'), which clearly differentiates this from page, media, and publish tools. It does not explicitly name sibling tools for disambiguation, 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?

The description gives explicit invocation guidance: call with no arguments to read the current theme, and call with colors/text_styles to update (PATCH) the saved document. It also explains the partial-update behavior ('what you do not name is kept'). It does not compare against other tools or provide when-not-to-use scenarios, but the intended usage branches are clear.

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

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

The readOnlyHint annotation already covers safety, and the description adds useful behavioral context: the tool exposes inspector structure, control-level write targets, AI hints, and the ability to narrow into one control for fuller detail. This goes beyond the annotation without contradicting it.

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

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

The description is compact and front-loads the core purpose before giving usage guidance. The wording is somewhat dense and uses jargon like 'DECLARED control,' but every clause contributes meaningful 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 simple read-only tool with no output schema, the description gives a reasonable sense of the returned content and how to narrow it. It is incomplete mainly because the required type parameter is not explicitly defined, and there is no mention of response shape or potential size of the inspector output.

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 control parameter is well explained by both the schema and description, including the hint to narrow to one control. However, the required type parameter has no schema description and the description only implies its meaning through 'this element's INSPECTOR,' leaving the agent to infer what values type should take.

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

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

The description clearly identifies what the tool returns: the inspector structure for an element, including tabs, groups, control names, what each control writes, and AI hints. It is tied to 'this element' and styling, which gives it a distinct identity among the sibling tools, though it does not explicitly name a sibling it differs from.

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 explicitly says to read this before styling an element, and explains the optional control parameter as a way to read one control in full. This gives a clear when-to-use signal, though it does not state when not to use it or name alternative tools.

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, openWorldHint=true, so the safety profile is covered. The description adds genuinely non-structured traits: the undo stack is IN THIS PROCESS ONLY, is capped, and disappears when the process exits. It also warns there is no enumerable list of undoable items, which is important agent-facing 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?

Front-loaded with the core action and scope before the caveats, and the page-detour is functional routing rather than filler. Some prose is showy ('anything with a shape', 'That one survives everything') and could be trimmed, 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?

For a 2-parameter tool with no output schema, the description covers session scope, capping, ephemerality, and the page alternative well. Missing details are the meaning of dry_run and behavior when index is out of range, which leaves a small gap.

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

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

The description gives no meaning for either parameter. The schema documents only 'index' (1 = most recent write) and leaves 'dry_run' entirely undescribed at 50% coverage, so the description fails to compensate for the gap. 'No argument lists what is undoable here' gestures at the parameterization but adds no usable 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 concrete verb and resource: it restores what a PUT made through sb_api_call replaced (settings, products, forms). The name sb_api_call is called out as the writer being reversed, which separates it from read/create siblings. 'Anything with a shape' is a bit loose but the core purpose 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?

Explicitly routes the agent: use this for non-page objects, but for a PAGE the platform history endpoints (GET .../pages/{pageId}/history or versions) are 'the better answer whenever the thing to recover is a page'. That is a real when-to-use/when-not-to-use split. It stops short of stating prerequisites for invoking undo here (e.g., that a prior sb_api_call write must exist in the same session), so it is not a full 5.

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