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?

Adds substantial behavior beyond the annotations: dry-run is on by default (a critical safety valve given destructiveHint=true), pick/max_items/item_offset shape the response, and oversized lists (>60 KB) self-report. It still omits error/failure behavior and auth prerequisites, so it stops short of full disclosure.

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

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

Four telegraphic clauses, front-loaded with the two selection modes and the dry-run default before the result-shaping details. No sentence is redundant.

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

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

For a 14-param, no-output-schema, open-world tool the description covers selection, safety default, and output shaping well. Remaining gaps (body vs merge interaction, query/path_params semantics, failure modes) are real but moderate given the schema carries part of the load.

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 57% across 14 params, and the description compensates by explaining pick (field selection), max_items (list cap) and item_offset (pagination) – none of which carry schema descriptions. Undocumented params such as body, query, site_id and path_params still rely on the schema or inference.

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 (Call) and resource (an operation id from sb_api_find, or a raw method+path route), and explicitly positions itself against the sibling sb_api_find as the executor of what the finder resolves. An agent can tell this is the generic API-call proxy without opening the schema.

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

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

Gives clear selection conditions: use an id from sb_api_find, or fall back to method+path for routes the catalog lacks. It does not name other siblings (sb_set, sb_code, sb_look) as preferred alternatives for their domains, so no explicit exclusions 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavior: it reaches all 892 operations and the id-mode returns a full call sheet with parameters, credential, body fields, and handler caveats — details not derivable from annotations or schema.

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

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

One dense sentence that front-loads the two usage modes and packs in return-value content without waste. No filler, nothing duplicative.

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

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

With no output schema, the description correctly compensates by summarizing what the call sheet contains. A read-only lookup with fully documented params is well covered; only minor gaps remain, such as pagination/limit behavior across 892 operations.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (id, tag, limit, query). The description reinforces the query/id duality but adds no format, default, or constraint detail beyond the schema's own text, so the baseline 3 applies.

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

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

States a specific verb (Find) and resource (API operations) and clarifies the two modes: intent search via query, or call sheet via id. It also declares scope ('reaches all 892 operations'), which implicitly separates it from an executor like sb_api_call, though no sibling is named explicitly.

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

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

The description tells the agent exactly which argument selects which behavior: use query to find by intent, use id to retrieve a call sheet. What is missing is guidance on when not to use this tool or when to prefer a sibling like sb_api_call or sb_catalog_search.

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, so the agent knows this is a non-destructive write. The description adds the effect on rendering (placeholder text becomes real data) and implies validation via the schema note that a wrong source is refused. It does not disclose what happens to existing bindings, whether the change is reversible, or undo behavior, so credit is limited.

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

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

Two tight sentences with the primary outcome front-loaded and zero filler. It is efficient, though the second sentence is a fairly thin addition.

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

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

For a 6-parameter mutation tool with no output schema, the description is very thin: it omits the dry_run/force workflow, how bindings are keyed by id and field, and any interaction with the surrounding page/node tools. An agent would need to infer the invocation flow almost entirely from the schema.

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

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

Schema coverage is 67%, with the schema already documenting field, force, action, and source in useful detail. The description's only parameter-level addition is the action/purchase-control note, which largely restates the enum's intent. It neither documents id nor dry_run, so it does not compensate for the partial coverage.

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

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

Names a specific verb (bind) and resource (a node to real store data) and states the user-visible outcome (real products instead of placeholder text). It does not differentiate itself from write siblings like sb_set or sb_connect, but the purpose is clear.

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

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

The description never says when to choose sb_bind over alternatives such as sb_set, sb_connect, or sb_store, nor does it state prerequisites (e.g. that a store/source must exist). The only routing hint, 'action makes a button a purchase control', explains a parameter rather than the when-to-use decision.

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

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

Annotations only declare readOnlyHint=true; the description adds meaningful behavior beyond that — the query-omitted browse mode, that it is the sole discovery path for types you would not search for, and the detail:true effect. It says nothing about return size, limit interactions, or pagination, which keeps it below the top band.

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?

Compact and front-loaded: the primary verb opens the sentence, with browse mode and the detail/icon notes following. Some clauses are tightly packed together, which slightly reduces readability 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 read-only search with no output schema and 3 parameters, the description covers the key non-obvious behaviors: browse-by-omission, detail hints, and special query syntax. Return shape and limit/pagination behavior are unaddressed but are less critical given the readOnlyHint.

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% (query has no description at all). The description compensates by documenting the special query syntax "icon:<word>" and clarifying what detail:true returns (AI hints), which the schema only partially covers via its useWhen/avoidWhen/contentTips 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 states a specific verb and resource ("Find an element type by what it does") and gives an agent enough to distinguish it from other search-ish tools. It references sb_traits_for as a related tool, though it does not sharply contrast against the many other siblings in this catalog.

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

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

It gives real usage conditions: omit query to browse every type (the only way to encounter an unsearched-for type), and use detail:true for AI hints. It names sb_traits_for as a related route but stops short of an explicit when-not-to-use rule or a clear boundary between this and unrelated siblings.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered; the description adds the non-obvious merge semantics of 'set' with an id (partial update over the stored row), which is real behavioral value beyond annotations. It does not, however, spell out the consequences/dry_run behavior of removal.

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

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

Dense but efficiently front-loaded: resource identification first, then placement, then action semantics, then the exclusion. No filler, though the action clause is crammed and slightly harder to parse than it needs to be.

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

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

Against 11 parameters, 9% schema coverage, no output schema and a destructive annotation, the description covers the resource and action semantics well but leaves several parameters (dry_run, enabled, language, position) undocumented and says nothing about return shape or rollback. Adequate but with clear gaps for a tool this size.

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 9%, so the description must carry parameter meaning, and it explains the key ones: placement values (head/body_start/body_end), page_id scoping (site-wide vs one page), and id create-vs-merge semantics. It leaves dry_run, enabled, language, position, name, content, and site_id unexplained, so compensation is partial.

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

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

States a specific resource (the site's custom code files) with concrete examples (tracking pixels, analytics, chat widgets, site-wide CSS) and the placements where they are injected. It also explicitly excludes 'the custom-code element,' though it never names a sibling tool by name. Purpose is clear and diagnosable, just lacking direct sibling routing.

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?

Guidance for the action lifecycle is explicit: 'list', 'set' (no id creates; with id merges named fields over the stored row), 'remove', and page_id''s dual scope (site-wide when absent). This tells the agent how the modes differ, but there is no when-to-use-vs-alternative guidance against nearby tools like sb_set/sb_remove.

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?

Adds substantial behavior beyond the annotations (readOnlyHint=false, destructiveHint=false): nodes get fresh ids, the copy lands right after the original, cross-site copies push images into the target library, untransportable references are blanked and listed, and the open page becomes the target. This is exactly the side-effect disclosure a mutation tool needs.

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

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

Core behavior is front-loaded in the first sentence. The em-dash framing line ('The move a designer makes constantly') is flavor rather than functional detail, but the rest is dense and earns its place.

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

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

For a 7-param mutation tool with no output schema, the description covers the primary flow and cross-site effects well but omits what force's guard override entails, what dry_run returns, and what index does. Adequate but with visible 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 only 29%, but the description meaningfully explains to_page_id/to_site_id (paste target, cross-site semantics), which is the highest-value pair. However, force, index, dry_run, and id remain undocumented in both schema and description, leaving real gaps.

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 ('Copy a node and everything under it, under fresh ids, right after the original') with precise scope. An agent can immediately distinguish it from siblings like sb_add and sb_move without opening any schema.

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

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

Clearly explains the two invocation modes: default in-place duplication right after the original, versus pasting elsewhere via to_page_id/to_site_id. It does not name sibling alternatives or state exclusions, but the when-to-use context is strong.

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 declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is partly covered. The description adds scoping facts (store types carry bound content, seed default true vs blank, chrome default true, locale default), which is some useful context, but it is impenetrable and omits auth requirements, idempotency, and slug-collision behavior for a write tool.

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

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

It is short but poorly structured and jargon-dense; the lead clause dangles and the key action is buried. Sentences mix seeding rules, routing, and type semantics without a clear front-loaded statement, so length is not the issue — clarity and ordering are.

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 write tool with nested settings, no output schema, and 45% schema coverage, the description is far too thin and muddled. It should explain the create semantics, type branching, and the undocumented parameters but does not.

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 45% with 11 parameters, so the description must compensate. It touches seed, type, and slug context but leaves name, dry_run, site_id, settings, is_homepage, and locale largely unexplained, and its phrasing adds confusion rather than meaning 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 states the primary action (creating a page) in a clear verb+resource form; instead it opens with a list of store types and route behavior. An agent has to infer 'create' from the name and the scattered hints about types and seeding. It distinguishes few siblings and even pulls in routing facts unrelated to the create 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?

There are fragments of guidance ('seed:false for blank', type inference, sb_page_open seeds its ROOT), but no clear statement of when to use this tool versus sb_page_open, sb_page_update, or sb_page_list. The routing remark about /checkout and /products/{slug} does not tell the caller when this tool is the right choice.

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?

Annotations declare readOnlyHint=true, so the safety profile is already covered. The description adds workflow context (it is a prerequisite that returns an outline and can target a form's field document), but the phrase 'open a page for editing' sits in mild tension with a read-only hint and could suggest a state change or lock that the annotation denies.

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

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

Three short sentences, front-loaded with the action and its prerequisite, with no filler. The closing fragment 'fields, specials.formRules on its root' is terse to the point of being cryptic but does not waste space.

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 prerequisite tool with no output schema, the description supplies the essentials: it returns an outline, must precede the edit tools, and offers two ways to identify the target. The remaining gap is the undocumented site_id and the exact shape of the returned outline.

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

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

Schema description coverage is 0%, so the description must compensate. It explains page_id (find via sb_api_find) and form_id (its field document, fields, specials.formRules on its root), but site_id is left entirely unexplained despite having no schema description.

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

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

States a specific verb and resource ('Open a page for editing and return its outline'), so the core action is unambiguous. It routes to sb_api_find and names edit-related siblings, but never explicitly distinguishes itself from sb_outline or sb_node_read, which also surface page content.

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

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

Provides a concrete precondition ('Call before any sb_add / sb_set / sb_move / sb_remove') and tells the agent how to obtain the needed id via sb_api_find 'list pages'. It also covers an alternative entry path (form_id edits that form's field document), though it never states when this tool should not be used.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds real value beyond these: the dry_run default of true (a safety mechanism aligning with non-destructive behavior), the draft-only mutation scope, and the re-publishing note for published pages. It is consistent with the annotations and enriches the behavioral contract.

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

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

Three dense sentences with no filler. The main action is front-loaded, and scope, draft handling, and dry_run safety are packed into ~40 words. 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 batch-capable mutation tool with no output schema, it covers the core operation, scope control, draft-only behavior, and dry_run safeguard. Minor gaps: site_id semantics and what the dry_run listing actually returns are not specified, but the operation is well understood without them.

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

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

Schema coverage is 0%, so the description must carry the parameter meanings. It covers dry_run (default true, lists what would change) and page_id (target one page, or omit for all pages), but site_id is entirely unmentioned. Two of three parameters are meaningfully explained, compensating partially but not fully for the missing 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 states a specific verb (rename), resource (page root), and precise condition (root not 'ROOT', e.g., sppro_1 or rt_<hex> left by older seeds). It clearly distinguishes from siblings like sb_page_create, sb_publish, and sb_page_state, all of which handle 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 gives clear context: it's for fixing legacy malformed page roots, with scope (one page vs every page via page_id) and a draft-only restriction with published pages listed for re-publishing. It doesn't explicitly name alternatives or state when NOT to use it, but the legacy-seed trigger and draft-handling make the use case well understood.

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?

Annotations already declare this is a non-read, non-destructive mutation, so the safety profile is covered. The description adds genuinely non-obvious behavior: it reads the page first and merges settings key by key so unnamed keys survive. It omits mention of dry_run and any auth/permission requirements, keeping it below a 5.

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

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

Three dense but front-loaded sentences with no filler; the editable-fields list and the merge caveat come first, with template semantics last. Slightly packed, but every sentence carries load.

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

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

For a 12-parameter tool with a nested SEO object, no output schema, and low schema coverage, the description covers most meaningful parameters and the key merge behavior. Gaps remain around dry_run and site_id, but an agent has enough to call it correctly.

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

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

Schema description coverage is only 17%, so the description must compensate, and it largely does: it explains seo is merged key by key, and clarifies render_for (move entities onto this page) vs render_default (return to type default) and default_template. Only page_id, site_id, and dry_run are left without added meaning.

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

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

States a specific verb ('Edit') and resource ('a page'), then enumerates exactly which fields are editable (name, slug, home flag, order, SEO, members_only). The template-page sentence further narrows the scope to a distinct behavior class, making it clearly distinguishable from siblings like sb_page_create and sb_page_repair.

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

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

Provides clear context for when the template-specific parameters apply (on a template page such as product, category, post) and what default_template/render_for/render_default accomplish. It does not explicitly name an alternative tool or state exclusions, so it falls short of full when/when-not routing.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds genuinely new behavioral context beyond them: writes are dry runs by default, and restore actually rewrites the draft. It does not say whether a restore is itself reversible, how autosave history interacts with named versions, or what permissions are required.

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 scope statement is front-loaded and the per-action detail is packed into one dense sentence with no filler. It is telegraphic to the point that the quoted action names plus braces require careful parsing, but nothing 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 7-parameter tool with no output schema and near-zero schema coverage, the description covers the action semantics, the recovery scoping, and the dry-run safety default. Missing are site_id behavior and any notion of what list returns (ordering, limits), which an agent would need for real use.

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 14%, so the description carries most of the burden and does so well: it binds label to save, version_id/history_id to restore, and explains the dry_run default. The one gap is site_id, which is neither described in the schema nor mentioned here; page_id is the only parameter documented by the schema itself.

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

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

The first sentence names the resource precisely ('A page's platform recovery points, everyone's edits included') and distinguishes it from the closest sibling by explicitly noting that sb_undo covers a different scope. Each action is then given a concrete verb and object (list = named versions/autosave history, save = snapshot the draft, restore = put the draft back), so an agent can tell exactly what the tool does without opening the schema.

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

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

It routes the agent away from sb_undo with an explicit scope boundary and clarifies which action to pick for each intent (browse vs snapshot vs roll back). It stops short of stating exclusions or prerequisites, e.g. whether restore requires a prior list call or whether saving is allowed on published pages.

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?

Despite annotations already declaring destructive and idempotent, the description adds crucial context: cascading republish of pages sharing global sections, verify semantics with a 60s cache delay explaining why a reload may show the old page, and the exact revision report fields. This goes well beyond the annotations and helps an agent understand side effects and expected timing.

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 main action is front-loaded, and each sentence adds distinct value (purpose, cascade, verify/caching). It is dense but not bloated, though the all-caps 'PUBLISH CASCADES' and em-dash style make it slightly heavier than necessary. Overall it earns its length.

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

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

For a mutation tool with no output schema, the description does state the returned revision fields and explains verify's post-publish check. However, it omits any mention of dry_run behavior and leaves site_id unexplained, which could lead to incorrect invocation. The cascade and cache details are rich, but the parameter coverage gap lowers completeness.

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

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

Schema description coverage is only 40% (verify and publish_drafts have descriptions; dry_run and site_id do not). The tool description enriches only the verify parameter's meaning and mentions the output revision fields, but it does not explain dry_run's effect or clarify site_id's role. It only partially compensates for the low schema coverage.

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

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

The description opens with a specific verb and resource: 'Compile the draft into the live page' and even lists the report fields (id, publishedAt, fromVersionId). It clearly distinguishes the action from generic 'publish' by adding cascade and verify behavior, but it does not name or contrast any sibling tool.

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

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

No when-to-use or when-not-to-use guidance is provided, nor any alternative tool mentioned. The cascade explanation and verify/cache advice are behavioral/interpretive, not selection criteria. An agent would not know from this description when to choose sb_publish over a tool like sb_page_state or sb_page_repair.

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?

Annotations already declare write (readOnlyHint=false) and non-destructive, but the description adds real behavioral context beyond them: checkout PUBLISHES the page, missing pieces cause /checkout to 404, overlay_attach re-reads the page afterwards, checkout_sync republishes forms, and "Dry run returns the plan". It never covers auth/permission requirements or failure modes, so it falls short of a 5.

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

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

Almost no sentence is filler, but the entire twelve-action contract is delivered as one unbroken block with no enumeration or line breaks, which hurts scanability when an agent is trying to locate a single action. Front-loading is partial — the ordering rule leads, but individual actions are not visually separable.

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 twelve-action, twenty-parameter tool with no output schema and only partial annotations, the description covers what each action does, its side effects, and its sequencing caveats. It omits error behavior and return payloads entirely (beyond the dry-run plan), which is the main remaining gap.

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

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

With 20 parameters and only 65% schema coverage, the description carries real load by binding parameters to actions (template, app_key, footer, kind, overlay_id, settings merge behavior, global_kind default custom, relocalize's language rewrite). A few parameters (menu_id, site_id, page_name, headline, template_id) are left to the schema, so it does not fully compensate for the coverage 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?

Each of the twelve actions is described with a concrete verb and effect ("makes the order form... creates and PUBLISHES the checkout page", "re-reads the store's payment and delivery methods into every existing order form"). The ordering constraint ("must happen in a fixed order") and the note that /checkout 404s without all four make the tool's purpose unambiguous. It does not cleanly position itself against every sibling (sb_page_create, sb_bind, sb_publish) but the action-level detail is strong.

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

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

Gives explicit triggers ("run it after adding a shipping method or switching on a gateway") and an explicit when-not with a named alternative: global_attach is "the answer for a page that is missing the site's header, where action:'chrome' would wrongly build a second one". No guidance on when to prefer entirely different sibling tools for the same work, but the intra-tool routing advice is well above average.

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 establish write-but-non-destructive (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context beyond that: insertion happens 'above the footer', and a foreign site's template is copied in whereas built-in layouts are composed against the page's own tokens. It does not, however, explain what dry_run controls.

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

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

A single front-loaded sentence leads with the action and then qualifies the source types. Efficient, though the nested parenthetical makes the back half slightly hard 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?

No output schema, so return values need not be covered, and annotations carry the safety profile. But for a four-parameter mutation tool at 0% schema coverage, the silent dry_run parameter — likely the safe way to preview this operation — is a meaningful omission.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the non-obvious semantics of template_id (two distinct sources) and implies the target page, but says nothing about dry_run or site_id, leaving half the parameters unilluminated.

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 ('Add') and resource ('a section template to a page') and disambiguates the two template sources — an sb_templates row that gets copied versus a built-in layout composed against page tokens. This distinguishes it well from a generic add tool, though the dense phrasing requires a second read.

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

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

It references sb_templates as the listing source for template_id, implying this is used after looking up a template, but never states when to use it versus siblings like sb_add or sb_page_create, nor any prerequisites. Usage is inferable but not 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?

Beyond the annotations, the description discloses that colors and text_styles PATCH the saved document, that unspecified keys are preserved, and that locale applies site-wide. This is useful behavioral detail, though dry_run behavior is not explained and might have been valuable given the mutation-oriented operations.

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, front-loaded with the tool's role, and every sentence adds functional value. The backticked parameter references are clear, and the patch semantics are stated with minimal wording.

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 core read/patch/locale behaviors are covered, but dry_run and site_id are not explained, and there is no output schema or return-format note. For a 5-parameter tool with no output schema, the description leaves meaningful gaps an agent would need to resolve.

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

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

The schema already documents colors, locale, and text_styles, but the description adds meaning: it clarifies partial-update behavior and connects locale to settings.locale and <html lang>. This goes beyond the schema, though dry_run and site_id remain undefined in both places.

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

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

The description clearly identifies the tool as the site-wide palette and type scale layer, and gives specific verbs: read with no arguments, PATCH colors/text_styles, and set locale. It is clear about the resource and operations, though it does not explicitly differentiate from likely siblings like sb_look or sb_set.

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

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

The description explains concrete call patterns: invoke with nothing to read, use colors/text_styles to PATCH, use locale for language. It gives clear context and partial-update semantics, but does not mention when to prefer a sibling tool or any exclusions.

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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutating tool. The description adds useful constraints (writes limited to 'registry fields only', 'machine-fill missing'), but omits the dry_run parameter entirely and says nothing about side effects or reversibility for the write/auto actions.

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

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

A single dense pipe-delimited line that is front-loaded with the domain and then enumerates actions. It is compact, but 'as the editor does it' is cryptic filler and the run-on structure trades readability for brevity.

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 12 parameters, no output schema, and 0% schema description coverage, the definition is too thin for the tool's complexity. Critically, the dry_run safety flag is never mentioned, and there is no explanation of what write/auto actions return or how they modify content.

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

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

Schema description coverage is 0% across 12 parameters, so the description must compensate. It partially does: 'add/remove' maps to the locales params, 'node id+field+value' maps to the entries fields, and 'machine-fill' maps to source=machine. But most parameters (dry_run, offset, locale, site_id, page_id, entity_type, all, from) remain undocumented anywhere.

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 lead 'Multilingual, as the editor does it' is vague about the resource and verb, but the following pipe-delimited action list (status, locales, page, write, auto, review) reveals that this is a multilingual translation-management tool. An agent can infer the domain but must decode the terse sub-command markers to understand what the tool actually 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?

The parentheticals act as light usage notes ('write (node id+field+value; registry fields only)', 'auto (machine-fill missing)', 'review (approve)'), implying when each action applies. However, no alternative tools are named and there is no explicit when-to-use/when-not-to-use guidance relative to siblings like sb_review 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?

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds substantial context beyond them: conflict behavior (a page is refused if someone else saved it since), process-lifetime and capping (in-process only, capped, vs platform history surviving a restart), and redo lineage (the newest entry after an undo is its redo). The vague 'capped' without a number is the only soft spot.

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

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

Front-loaded with the core purpose, then layers redo semantics, conflict handling, and scope. Sentences are dense but each carries distinct information; nothing is pure padding, though the parenthetical sibling list and trailing history note add length.

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

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

For a stateful undo tool with no output schema, the description covers the critical behaviors an agent needs: what it reverts, redo lineage, conflict refusal, and process-scoped lifetime. The unaddressed dry_run parameter is the main completeness gap.

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

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

Schema coverage is 50%: index is documented in the schema ('1 is the most recent write'), but dry_run is undocumented in both schema and description. The description's 'No argument lists what is undoable' touches index semantics indirectly but does not compensate for the missing dry_run explanation, leaving half the parameters opaque.

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 (put back/undo) and resource (a write's replaced content), and explicitly scopes it to edits made via named siblings (sb_add, sb_set, sb_duplicate) or a PUT through sb_api_call. An agent can distinguish this from those write tools and from the read-oriented platform history endpoint without opening any schema.

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

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

Gives clear context for use (reverting a write made here or via sb_api_call) and names an alternative for durability (the platform's own page history survives restarts). It also flags that no argument enumerates undoable items, implying a trial-by-index workflow, but does not state explicit when-not-to-use cases.

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