Swebsy

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a bounded, non-destructive write. The description's main behavioral claim ("appends to the end by default") and the position/targetPath interaction largely restate what the schema text for `position` and `targetPath` already says, so it adds little new disclosure such as reversibility, required page/site state, or undo interaction.

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 purpose and then the placement nuance; nothing is wasted. Minor redundancy with the schema's own `position` default means it is efficient but not maximally economical.

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 a large recursive component schema, no output schema, and full annotation coverage, the description supplies purpose, placement defaults, and targeting guidance adequate to invoke it correctly. It omits any pointer to prerequisite state (an open page) or companion tools like read_page/build-guide, but the schema covers the key mechanics.

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

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

Schema description coverage is 100% and the `position`/`targetPath` properties already document defaults, enum meaning, and the fallback to canvas selection. The description's mention of passing `position` with `targetPath` mirrors that text rather than adding format or syntax detail, so the schema remains the primary source.

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 ("Insert a new section into the current page") plus the concrete section archetypes it targets (hero, features, pricing, CTA). It does not explicitly contrast itself with neighbors like swebsy_insert_block or swebsy_duplicate_section, so an agent still has to infer the boundary from names alone.

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

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

"Use for adding discrete sections ... to an existing page" gives clear context for when this tool applies. It stops short of naming alternatives or exclusions (e.g., when to prefer insert_block or duplicate_section instead), so the routing decision is not fully closed.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=false). The description adds substantive behavioral context beyond that: instances remain linked and stay in sync with the symbol main and all other instances. It also implies the operation affects the currently selected page, a meaningful side-effect note. It doesn't describe failure modes if no page is selected, keeping it just short of 5.

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

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

Three tight sentences, front-loaded with the action and resource before the rationale. Every clause carries information — sync behavior, the reuse pattern, and the page-selection prerequisite — with no filler.

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

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

For a mutation tool with annotations covering safety and a fully-documented schema, the description supplies the missing behavioral context (linking/sync semantics) and the required prerequisite sequence (list_symbols, select_page). No output schema exists but the effect is well-enough implied; minor gap on error/precondition behavior when no page is selected.

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 symbolId, position, and targetPath thoroughly (including enum meanings and the before/after-selected target requirement). The description largely restates that the target is the CURRENT page and references list_symbols for symbolId, adding little beyond the schema. 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 (Add) and resource (a linked INSTANCE of an existing symbol) and explains the mechanism that makes it a distinct operation: it stays in sync with the symbol main and other instances. It clearly separates itself from add_section and promote_to_symbol by naming the reuse goal (one navbar/footer/CTA across pages).

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

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

Provides explicit prerequisites and pointers — call list_symbols to get the symbolId and select_page to set the target page before invoking. It also frames the use case (reusing a shared element across pages) which implies when to choose this over other add options, though it does not explicitly contrast against add_section or insert_block.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuine behavioral context beyond that: it is a one-step operation, the reveal is per-section and staggered, and navbars/footers are deliberately skipped, which lets the agent predict the resulting markup. It does not discuss reversibility (e.g. via undo), a minor gap.

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, front-loaded with the core action and immediately followed by scope/target detail and the alternative. No filler; every clause earns its place.

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

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

For a single-optional-parameter tool with no output schema and annotations covering the safety profile, the description is essentially complete — an agent knows the action, targets, exclusions, and preferred-over alternative. Only the reversibility/undo relationship is left unstated.

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

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

Schema coverage is 100% and the single 'scope' parameter is fully documented in the schema with its enum meanings. The description's reference to 'the page or site' loosely echoes that enum but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Apply Swebsy's built-in scroll-reveal animation') and enumerates exactly what it targets (headings, text, images, buttons, cards) plus what it excludes (navbars/footers). No sibling in the list does page-wide animation, and the description also contrasts itself with the hand-authored 'animate-* classes' approach.

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

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

Gives an explicit trigger ('whenever the user asks to animate the page or site, or wants a consistent reveal') and names the alternative it should displace ('hand-placing animate-* classes'). It stops short of stating when NOT to use it (e.g. pages already animated), but the routing guidance is 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 establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely new context: the capture is styled, the viewport is fixed, the result is returned as a viewable image, and whole-page captures downscale enough to lose component detail. That last point is an important quality caveat not available from any structured field.

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: the first defines the action and its output, the second delivers the scoping advice with its rationale. Nothing is padded and the actionable constraint is front-loaded in the second sentence.

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

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

With no output schema, the description carries the burden of describing the return value and does so ('an image you can see'), and it explains the downscaling tradeoff that affects capture choice. It is complete for a simple read-only capture tool, with only selectionOnly's relationship to targetPath left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, and the enum values and targetPath format are already documented in the schema. The description nonetheless adds the reason to use targetPath (whole-page PNGs downscale so far that component detail becomes unreadable), which is semantic value beyond the schema. selectionOnly goes unmentioned, keeping it from a 5.

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

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

States a specific verb and resource (capture a screenshot of the current page) plus the concrete output form (an image you can see), which is distinct from text-returning siblings like read_page. It stops short of naming the sibling tools it should be chosen over, so it is clear but not fully differentiated.

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 conditional guidance for the targetPath parameter ('when verifying ONE section'), which implicitly tells the agent when to scope vs. capture whole-page. However, it never addresses when to use swebsy_capture instead of visual alternatives such as swebsy_read_page or swebsy_read_selection, so tool-level selection is left to inference.

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

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

Annotations only declare the generic safety profile (not read-only, not destructive, not open-world), so the description carries real weight and delivers: it discloses that the call is one-shot ('ONCE'), must precede first-page generation, and that skipping it causes drift to generic output. It stops short of saying whether a second call overwrites an existing direction or what the applied state looks like afterward, which keeps it off 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 sentences, zero padding, and the ordering constraint is front-loaded before the parameter guidance. Every clause carries actionable information — timing, selection preference, and exclusion.

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 no required parameters, the description supplies everything the agent needs: when to fire, what it mutates, the precondition that makes it necessary, and the choice between the two input shapes. Nothing material is left to inference for a tool whose only real risk is calling it at the wrong time.

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 baseline is 3, but the description adds a genuine decision rule the schema does not: use directionId unless the brief calls for something the menu cannot cover, then author custom fields. That resolves the mutual-exclusivity question the schema leaves implicit, which is real added value on top of the nested object's own docs.

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 ('Commit this site to a specific visual direction') plus the concrete side effects ('apply it (fonts, type roles, palette swatches)'). No sibling tool touches visual direction, so an agent can immediately distinguish it from create_site, create_page, or update_settings.

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 timing ('Call this ONCE, BEFORE generating a new site's first page'), an explicit negative case ('Not needed when editing a site that already has a direction'), and a routing rule between the two input paths ('Prefer a directionId from the sampled menu; supply the custom fields only when...'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already declare non-read-only and non-destructive, so the bar is lower. The description adds real context: the page starts nearly empty, is selected by default, and returns id/fileName. It omits auth/permission needs, but the post-creation workflow guidance is substantial.

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 and default behavior, then workflow and disambiguation. No filler; every sentence carries routing or behavioral 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 creation tool with no output schema, the description covers what it returns (id, fileName), the initial state of the created page, and how to populate/link it. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with all three params (name, select, fileName) fully documented including slug/folder syntax and defaults. The description adds no parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Create a NEW blank page') plus the effect (selects it, returns id/fileName). It explicitly distinguishes itself from replace_page_content and link_page, so an agent can tell it apart from siblings without reading schemas.

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

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

Explicit routing: 'Use THIS to add an additional page; use replace_page_content (NOT this) to overwrite the current page's content.' It also names the follow-up tools (replace_page_content, add_section, link_page) and when to reach for them.

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 it as a non-read-only, non-destructive creation. The description adds useful behavioral context beyond that: the site opens in Studio and must reach editorReady with a matching siteId before editing. This sequencing requirement is valuable and not derivable from annotations alone.

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

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

Front-loaded with the core action, then tight guidance on parameters and the required polling step. Every sentence earns its place with no redundancy.

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

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

No output schema exists, and the description carries the workflow through to readiness (editorReady + siteId match), so an agent knows how to proceed after creation. It does not explicitly address how this differs from opening an existing site, a minor 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 100%, so the baseline is 3. The description adds value beyond the schema by disclosing the default name ("My Website") and clarifying that a provided template is imported "unchanged," neither of which appears in the schema descriptions.

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

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

States a specific verb and resource: "Create a site and open it in Studio." This clearly distinguishes it from siblings like swebsy_open_site and swebsy_rename_site, and the description of what happens on creation (open in Studio) is concrete.

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 conditions: omit templateId for a blank site, provide an installed template ID (from swebsy_list_templates) to import a template unchanged. It also prescribes the follow-up workflow (poll swebsy_status until editorReady and siteId matches). It stops short of explicitly contrasting with swebsy_open_site for opening an existing site.

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 readOnlyHint=false, so the safety profile is partly covered. The description goes beyond that by disclosing the default refusal for assets referenced by pages, symbols, styles, or settings, and by warning that force clears live component references — concrete consequence detail the annotations lack.

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 with the core action and the safe default front-loaded, followed by the force caveat. Slight overlap between the description's force note and the schema's force description costs a point.

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

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

No output schema exists, so the description needn't explain returns, and it covers the key behaviors an agent needs: prerequisite listing, default in-use refusal, and the destructive scope of force. A brief note on the outcome/confirmation would make it fully complete.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description's force explanation largely restates the schema's 'clearing its live references' wording, adding only the usage caution, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete one managed asset') plus the scope ('the open site's asset gallery'). This clearly separates it from sibling deletions such as swebsy_delete_symbol or swebsy_delete_section.

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

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

Explicitly tells the agent to 'call swebsy_list_assets first' to obtain an assetId, and constrains force with 'should be used only when that is explicitly intended.' No alternative deletion tool is contrasted for the case where the target is not a managed asset, so it falls just short of a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds real behavioral context beyond them: which pages are protected from deletion and the important side effect that inbound links are left dangling, plus the remedy.

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 core action, then constraints, then the side-effect remedy. Every sentence carries information an agent needs before calling.

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 single-parameter mutation tool with no output schema, the description covers the action, the guardrails, and the post-deletion consequence. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already states 'Page id, name or slug to delete.' The description adds no format or identifier-resolution detail beyond that, so this is the baseline 3 case.

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 ("Delete a page") that immediately distinguishes it from sibling deletes like swebsy_delete_section, swebsy_delete_asset, and swebsy_delete_symbol. The added constraints sharpen the scope of what 'a page' can mean here.

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

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

Gives explicit when-not conditions (the home/index page and a site's last page cannot be deleted) and names a follow-up alternative (link_page) for repointing links. It stops short of naming a competing tool for deleting other entities, but the guidance is concrete and actionable.

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 readOnlyHint=false, so the description's job is to add context, and it does: it explains the concrete side effect avoided (a stray blank div left behind by emptying) and that the default target is the currently selected component. It does not mention whether the deletion is undoable, which is the one behavioral fact an agent might still want, but the destructive profile is well covered by annotations.

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

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

Three short sentences, front-loaded with the core action, then the key usage contrast, then the parameter nuance. No filler or repetition beyond what is needed.

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

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

For a destructive, no-output-schema mutation tool this covers the essentials: what is destroyed, the default selection scope, and how to target something else. The only material omission is reversibility/undo behavior, which matters for a destructive operation and is not addressed in the description or annotations.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the 'omit to delete the selected component' default and the 'from the most recent read_page call' provenance of targetPath. The description restates those facts rather than adding new syntax, ordering, or format meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove a component from the current page entirely') and distinguishes itself from neighboring deletion tools by scoping to the current page and to sections/components rather than pages or symbols. The contrast with 'emptying a section's contents' further pins down what this operation is and is not.

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

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

Explicitly tells the agent when to use this tool over a tempting alternative ('Use this instead of emptying a section's contents — an emptied section leaves a stray blank div on the page'), and routes the agent to `read_page` when it needs a `targetPath` for a non-selected component. Both the default path and the alternate path are 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 declare destructiveHint=true, so the agent expects data loss; the description usefully qualifies that 'nothing disappears from the site' and that instances become detached plain components. That is genuine behavioral context beyond the annotations, though it omits whether the action is reversible or what happens to the symbol definition itself.

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 key behavioral caveat front-loaded before the alternative-tool pointer. No filler.

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

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

For a one-parameter mutation tool with no output schema, the description covers the essential behavioral surprise (detach-not-delete) and the follow-up path. Minor gaps remain around reversibility and any effect on published pages.

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

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

Schema coverage is 100% and symbolId is documented as coming 'from list_symbols', so the schema carries the semantics. The description adds no parameter detail beyond that, which is the correct baseline for a single fully-documented parameter.

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

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

States a specific verb+resource ('Delete a symbol') and immediately clarifies the non-obvious semantics: instances are detached rather than removed. It does not, however, differentiate itself from the closely related sibling swebsy_detach_symbol, which an agent would reasonably confuse it with.

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 the tool and names an alternative path ('To also remove the copies, delete_section them'), which is actionable routing. It stops short of explicit when-not guidance relative to detach_symbol, the most likely competing 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?

Annotations already declare readOnlyHint=false with destructiveHint=false, so the mutation-but-safe profile is known. The description adds real value beyond that by disclosing blast radius: only the targeted instance becomes editable while 'the symbol and its other instances stay linked.' It does not mention reversibility (undo) or permission needs, but those are secondary here.

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

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

Three short sentences, front-loaded with the core action, then the key behavioral guarantee, then the usage scenario. No filler and nothing that repeats the schema or annotations.

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

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

For a single-parameter mutation with no output schema, the description covers what changes, what is preserved, and when to reach for it. It could be fuller by noting reversibility or that the instance loses its symbol overrides, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% and the single parameter is already documented as a path from read_page. The description adds no syntax, format, or selection guidance for targetPath, so the schema carries the full burden and baseline 3 applies.

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

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

States a specific verb and resource ('turn ONE symbol instance on the current page back into a plain component') and scopes it precisely to a single instance. The inverse relationship to siblings like swebsy_promote_to_symbol and swebsy_add_symbol_instance is clear from the wording alone.

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

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

Gives a concrete use case ('when one page needs a variant of the shared navbar/footer'), which tells the agent the scenario this tool fits. It stops short of naming alternatives or when NOT to use it (e.g. versus delete_symbol), leaving some routing inference to the agent.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the copy is selected as a side effect and the tool returns the new page's id and fileName, which matters for chaining calls.

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 operation and its scope, followed by return values and the use case. 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?

With no output schema, the description usefully names the return values (new page id and fileName) and discloses the selection side effect. Minor gaps remain around failure conditions or permissions, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters (name default, page identifier forms) are already documented in the schema. The description adds no format or constraint detail beyond that, matching the baseline for high-coverage schemas.

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 (copy) and resource (page), and names exactly what is carried over — content, classes and styles — which distinguishes it from create_page and duplicate_section. An agent can identify the operation 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?

"Use it to start a page from an existing layout instead of rebuilding it" gives clear context for when this tool is appropriate. It does not explicitly name the alternative (create_page) or state exclusions, so it stops short of full routing guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description is consistent with that. It adds genuinely useful behavior beyond the annotations: that classes and styles are copied, and that the insertion shifts subsequent path indices, which is a non-obvious side effect an agent must plan around.

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

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

Two sentences, zero filler, with the core action front-loaded and the important caveat immediately after. Every clause earns its place.

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

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

For a single-parameter mutation tool with no output schema and non-destructive annotations, the description covers the action, what is copied, and the path-shift consequence. It stops short of noting whether the new copy is selected or what path it receives, which would fully close the loop.

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

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

Schema description coverage is 100% and the single targetPath parameter is already documented as coming from the most recent read_page. The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Copy a component... and insert the copy right after it'), and the 'with its classes and styles' clause pins down exactly what duplication carries over. This clearly distinguishes it from add_section, edit_section, and move_section, which an agent could otherwise confuse it with.

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 post-condition workflow rule: 'call read_page before the next path-based edit' because 'Paths after it shift by one.' That is strong guidance about sequencing, though it never states when to prefer duplication over adding a fresh section, nor any preconditions.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses non-obvious behavior: id preservation semantics ('an id kept in the edit keeps the styles attached to it; an id you drop loses them') and that `patch` is only for tiny single-property tweaks. This is exactly the kind of behavioral context an agent needs to avoid losing styling.

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 primary action and default target, then the targeting override, then the payload priority, then the id-preservation caveat. Sentences are dense but all earn their place; the flow of preferred/alternative/fallback is easy to scan.

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

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

For a complex mutation tool with a deeply nested component tree and no output schema, the description covers targeting, payload selection, and id/style retention — the three things an agent must get right. Complete enough to call correctly without the builder guide.

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 baseline is 3; the description still adds value by ranking the mutually exclusive payloads and explaining why `component` is best for structural changes versus `patch`. It stops short of clarifying `summary` requirements or the compact-DSL aliases, leaving that to the schema.

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

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

States a specific verb+resource ('Modify an existing component') and implicitly contrasts with the sibling family by emphasizing 'existing' versus add_section/duplicate_section. An agent can tell it edits rather than creates, moves, or deletes without opening the schema.

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

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

Explicitly covers when to use each targeting mode (default = selection, `targetPath` = component named/identified via `read_page`, explicit path overrides selection) and ranks the payload options: preferred `component`, alternative `html`, fallback `patch`, with 'Supply exactly one.' Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the content is 'static' and pre-primed into the AI Builder, which usefully reinforces that repeated calls return the same guidance, but it discloses nothing about return format or size beyond that.

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

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

One sentence, front-loaded with the verb and resource, with a compact parenthetical enumerating the content. Every clause carries information and there is no filler.

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

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

For a parameterless, read-only reference loader with no output schema, the description tells the agent what guidance it receives (component system, theme classes, conventions), which is most of what is needed. It stops short of indicating the form of the returned content or whether the same doc is retrievable by other means.

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

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

The tool takes zero parameters and the schema is empty with additionalProperties=false, so there is no parameter semantics for the description to clarify. Baseline of 4 applies since nothing is left ambiguous for the caller.

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 (Load) and a specific resource (static Swebsy builder guidance), and enumerates what it contains: component system, theme classes, conventions. It does not differentiate itself from the adjacent swebsy_get_skill, which likely also loads reference documentation, so the sibling boundary is left to inference.

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

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

Usage is only implied: an agent infers it should call this before writing sections/pages to learn the conventions. There is no explicit statement of when to load it versus swebsy_get_skill, swebsy_list_skills, or the builder-guidance-adjacent siblings, and no exclusions or prerequisites.

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

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

Annotations already establish readOnly, idempotent, non-destructive, non-open-world semantics, so the burden is light. The description adds that this returns the full instruction text for the chosen skill (content, not state) and is 'on-demand,' which usefully tells the agent this is a pure lookup that yields guidance.

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

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

Two sentences, zero waste, purpose and trigger conditions front-loaded before the return-value note. Nothing 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 single-enum, read-only lookup with no output schema, the description covers purpose, timing, and what comes back ('the full instructions'). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with a single enum parameter, so the schema already documents the argument. The description's parenthetical examples map real agent intents (adding animations, building forms) onto the enum values, adding marginal selection value beyond 'Which skill's guidance to load.'

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

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

States a specific verb and resource ('load ... guidance for a specific area') and names concrete triggering tasks (animations, page composition, copywriting, forms, nav, symbols). It is clearly distinguishable from swebsy_list_skills (which enumerates rather than loads one), though it doesn't name that sibling explicitly.

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

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

Gives clear usage context and timing: 'before acting on it,' with six concrete examples of the actions that should precede a load. No explicit when-not or named alternative is offered, so it stops short of a 5.

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

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

Annotations cover the safety profile (not read-only, not destructive, closed-world), so the bar is lower. The description adds genuinely non-obvious behavior: the block re-themes against the current site, so the result is expected to differ from the catalog thumbnail — a meaningful expectation-setter that prevents false bug reports.

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

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

Three sentences, front-loaded with the action and the preference rule, then the theming caveat. Slightly long final sentence but every clause carries useful information.

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

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

With no output schema, the description should set expectations about the result, and it does so via the theming explanation. It omits what the call returns (e.g., new component path) and whether the insert is undoable, which are minor gaps for a page-mutating tool.

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

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

Schema description coverage is 100%, including the nested adaptations object and its subfields, so the baseline is 3. The description only says content can be 'optionally customized' and adds no syntax or semantics beyond what the schema already documents.

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: insert a pre-built block from the catalog, with optional content customization. It also frames the alternative verb ('generating from scratch'), which helps agent selection, though no sibling tool 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?

'STRONGLY preferred over generating from scratch when a matching block exists' gives clear, actionable selection guidance. It stops short of the obvious workflow prerequisite (e.g., using swebsy_list_blocks to find a matching block) or any when-not-to-use condition.

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-only, non-destructive, closed-world mutation, so the safety bar is partly covered. The description adds real behavioral detail beyond that: for a navbar link it sets the page target so href and active state stay in sync, whereas for a plain link or button it sets href to the page's ./slug.html. It does not say what happens on an invalid targetPath or missing page, so it is not a 5.

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

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

Three sentences, front-loaded with the core action, then parameter sourcing, then the when-to-use trigger. Dense but every sentence contributes; only the UI-picker aside is arguably decorative.

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

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

For a two-parameter mutation with no output schema and annotations covering the safety profile, the description supplies the prerequisite, parameter provenance, and the divergent behavior for navbar vs plain link/button. Error behavior and return value are unstated, which is the only 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?

Schema coverage is 100% and the schema already defines both parameters, including 'Page id or name' and the zero-based index array from read_page. The description reinforces the read_page provenance and maps each parameter to its effect, but adds no syntax or format detail the schema lacks. Baseline 3 is correct when the schema carries the load.

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

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

Specific verb+resource: 'Point an existing link at a project page', with the UI analogue ('Link to' picker) anchoring what it does. It is clearly distinguished from siblings like create_page, update_page, and read_page, which are referenced as different steps in the workflow rather than as competing 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?

Explicitly states the triggering workflow: 'Use after create_page to wire a navbar to the new page', which is genuine when-to-use guidance. It does not state exclusions or name a competing tool for the same job, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds real behavioral context beyond that: usage counts are computed by checking references across every page, shared symbols, styles, and site settings, which explains why counts are expensive/whole-project in nature.

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 scope and the reference-counting behavior, with the actionable tip last. The gallery-images-specific advice in the final sentence is slightly narrower than the tool's general scope, 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 read-only list tool with two optional booleans, full schema coverage, and no output schema, the description is sufficient: it explains scope, count semantics, and the deletion use case. Only the shape of the returned asset/count entries is left implicit, which is acceptable given no output schema is declared.

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

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

Schema coverage is 100% and both booleans are fully documented in the schema, so the baseline is 3. The description frames unusedOnly in a deletion workflow but adds no syntax or edge-case meaning beyond what the schema already states.

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

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

States a specific verb (list), resource (managed assets), and scope (in the open site, with whole-project usage counts). It is clearly distinct from the other list_* siblings (pages, symbols, blocks, sites) and pairs recognizably with delete_asset.

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

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

Explicitly prescribes the intended workflow: 'Use imagesOnly:true and unusedOnly:true before deleting unused gallery images.' This tells the agent when the tool is the right call and what to do with the result, though it does not name delete_asset as the follow-up sibling 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 already declare readOnly, idempotent, non-destructive and closed-world (openWorldHint=false). The description reinforces this by calling it a 'pre-built' catalog, i.e. a fixed enumeration, and discloses the return shape (ids + labels), which matters because no output schema exists.

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

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

A single front-loaded sentence that names the resource, the payload, and the consuming tool. Every clause earns its place; no filler.

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

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

For a no-arg, read-only listing tool with no output schema, the description supplies the essentials: what comes back (ids + labels) and what consumes it (insert_block). Minor gaps remain, such as whether the catalog is static across sites or versioned, but the core need is covered.

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

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

Zero parameters, so the baseline is 4; there is no parameter semantics to explain and the description correctly avoids inventing any. Nothing about the empty schema is left ambiguous.

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

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

States a specific verb (List) and resource (pre-built block catalog), and further narrows scope by noting it is the catalog 'available to insert_block'. An agent can distinguish it from the many other list_* siblings without opening any schema.

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

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

The reference to insert_block implies the workflow (call this first to obtain valid ids, then pass them to insert_block), which is clear usage context. It stops short of an explicit when/when-not statement or naming alternatives like list_templates or list_symbols for other catalogs.

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

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

Annotations already establish the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds value by disclosing the shape of the result set, including the 'which one is selected' state, which is not derivable from the annotations or the empty input schema.

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

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

Two sentences, both front-loaded and earning their place: the first states the resource and payload, the second routes the agent away from a guess-based shortcut. No filler.

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

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

With no params and no output schema, the description carries the burden of telling the agent what comes back, and it does so by naming the key fields. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; baseline for zero-param tools is 4. The description spends its words on the result set instead, which is the right allocation.

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

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

Specific verb (List) plus resource (the project's pages), and it enumerates the returned fields (id, name, fileName, section count, selection state), which distinguishes it from siblings like list_sites/list_templates/list_assets.

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

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

Explicitly routes the agent: 'Call this instead of guessing a page name for select_page or link_page.' It names the downstream tools that consume the result and the failure mode (guessing names) it prevents.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context: results are 'newest-first' and strictly 'metadata only', which tells the agent no page content is fetched. It omits any note on volume, pagination, or result limits, which holds it below 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?

A single front-loaded sentence that leads with the verb and ordering, then enumerates fields via a colon. No filler, no redundancy, nothing that fails to earn 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?

With no input parameters and no output schema, the description must carry the return-shape burden, and it does by listing exactly which fields come back and in what order. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further the description could add about parameter syntax or formats.

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

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

States a specific verb and resource ('List saved sites') plus scope details: newest-first ordering and a full enumeration of the returned metadata fields (IDs, internal names, status, timestamps, template ID, page count, open state). An agent can distinguish this from sibling lists such as list_pages, list_templates, and list_assets purely from the resource noun.

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

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

Usage is implied by the resource name and the 'metadata only' qualifier, which suggests it is the cheap inventory call rather than a content read. However, the description names no alternatives or conditions, so an agent gets no explicit routing help against siblings like open_site or read_page.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact beyond that: results are truncated to one-line summaries rather than full skill content. It still doesn't say how many skills exist or whether the list can change.

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

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

A single sentence with no filler, front-loading the action and the resource and closing with the return shape. Every clause earns its place.

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

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

With no input parameters and no output schema, the description's burden is small, and it does state the enumerated topic domains and the summary-level result. Slightly incomplete in that a reader cannot tell whether the listed names are the exact identifiers expected by swebsy_get_skill.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4 for a no-argument tool.

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

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

Specific verb (list) plus resource (deep-guidance skills), with example topics enumerated and the shape of the result (one-line summaries) stated. It is clearly distinguishable from the many other list_* siblings, though it does not explicitly name swebsy_get_skill as the fetch counterpart.

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 statement of when to use this versus the obvious sibling swebsy_get_skill or swebsy_get_builder_guide. A discovery-then-fetch flow is only weakly implied by 'available'; there are no exclusions or prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the returned fields (id, name, component type, instance count, page usage) and the meaning of each health bucket — orphans, unregistered, ghosts — including the consequence ('editing them changes nothing elsewhere', 'edits propagate one way only'). This is exactly the kind of consequence-level detail annotations cannot carry.

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

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

Front-loaded with the core action, then the return shape, then the repair path, then the sequencing hint. Dense with terminology, but each sentence carries distinct information; the health-definition clause is long yet earns its space given no output schema exists.

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 has to describe results itself, and it does — enumerating the fields returned and the three health categories. Combined with the routing to promote_to_symbol and add_symbol_instance, an agent has everything needed to call this correctly and act on the 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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly spends its space on scope and return content instead of inventing arguments.

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

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

States a specific verb and resource ('List the project's SYMBOLS') and immediately defines what a symbol is ('reusable components that stay in sync across every page'), which separates it from list_pages, list_blocks and list_assets. An agent can identify the tool's scope without opening the schema.

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

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

Explicitly routes the agent: 'Use before add_symbol_instance to find the symbol id', and points to promote_to_symbol for repairing the health issues it reports. That is clear when-to-use guidance with a named alternative, though it never states a when-not-to-use condition.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world). The description adds value beyond them with 'Refresh,' signalling that the call re-fetches/re-syncs template data rather than purely reading a cached snapshot, and it enumerates the payload fields (names, descriptions, tags, fonts, preview and thumbnail URLs) despite there being no output schema.

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

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

Two tight sentences with zero filler; the action and returned data are front-loaded and the environment note trails appropriately. Every clause earns its place by either naming the resource, the payload, or the valid context.

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?

Absent an output schema and with annotations covering read safety, the description supplies the essential missing piece by listing the fields returned. It is complete enough to invoke correctly, though it stops short of clarifying what distinguishes a 'template' from a 'site' in this ecosystem, which would fully close the gap.

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

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

With zero parameters there are no argument semantics to document, so the baseline is 4. The description does not need to compensate for any schema gap, though it also adds nothing parameter-related (correctly, since there is nothing to add).

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

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

States a specific verb (list) and resource (installed site templates) and even enumerates the returned fields, so the agent knows exactly what the call yields. However, it does not differentiate itself from the many sibling list tools (list_sites, list_pages, list_assets, list_blocks, list_skills, list_symbols), leaving the agent to infer what a 'template' is relative to a '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?

The closing phrase 'Works from Home or Studio' gives a usable context clue for where the tool is valid, implying it is a discovery/listing action available outside the editor. It never states when to prefer this over the other list_* siblings or what prerequisites exist, so usage is only implied.

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

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

Annotations cover safety (readOnly=false, destructive=false, openWorld=false), and the description adds genuinely useful non-annotation behavior: the moved component keeps its id, classes, and id-styles, and the operation is scoped to 'the current page'. It does not cover failure modes (invalid anchorPath, cross-page attempts).

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

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

Three short clauses with the core action front-loaded, followed by examples and then the critical usage warning. No filler sentences; each part 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 3-param reordering mutation with no output schema, the description covers the essential 'what happens to the moved element' and the page constraint, and the schema covers the parameters. Minor gaps remain around error conditions and whether paths must be re-read after a move.

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

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

Schema description coverage is 100%, and each parameter (position enum, anchorPath, targetPath) is already documented in the schema, including the 'from read_page' provenance. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a precise verb+resource ('Move a component to just before or after another component') and adds concrete scenarios (reorder sections, swap columns, lift a CTA). An agent can immediately distinguish this from delete_section, duplicate_section, insert_block, or edit_section.

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

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

Explicitly says when to use it ('ALWAYS use this to reorder') and when not to, by naming the wrong alternative ('delete + re-add loses the component's styles'). That is a direct routing rule with a stated consequence.

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

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

Annotations only declare the generic safety profile (not read-only, not destructive, not open-world), so the description must add the real behavior — and it does, disclosing idempotency when already open and the editorReady gate before editing. It stops short of covering failure modes such as an unpaired tab or an unknown siteId.

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, all load-bearing, with the action and target front-loaded before the idempotency note and the readiness workflow. No padding 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?

For a one-parameter tool with no output schema, the description covers what it does, the tab it acts on, idempotency, and the pre-edit readiness check. Only the shape of the returned metadata is left unspecified, which is a minor 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 100% and the single siteId parameter is already documented as coming from swebsy_list_sites. The description's 'by ID' adds no syntax, format, or constraint beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Open a saved site by ID in the paired tab') plus the return ('its metadata'). The word 'saved' plus the need for a siteId cleanly separates it from swebsy_create_site without opening either schema.

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

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

Gives an explicit follow-up workflow: poll swebsy_status for siteId and editorReady before editing, which tells the agent this is a prerequisite step. It doesn't state when-not to use it (e.g., for unsaved/new sites), but the operational context is 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 only declare readOnly=false and destructive=false; the description goes further by disclosing side effects (rebuilding the main, re-linking every copy, registering lost instances) and a failure mode (structure diverged too far → reported as detached). This is substantial behavioral context beyond the annotations.

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

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

Front-loads the primary purpose before the repair/secondary scenario, and every sentence carries information. Slightly dense with the parenthetical naming of sibling tools, but no wasted prose.

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, and the description compensates by describing the return values (symbol id for add_symbol_instance, a repaired count, and detached reporting). Combined with the repair semantics, an agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100%, so targetPath's format is already documented there; the description adds real value by naming the upstream source (read_page) and giving domain examples (navbar, CTA band). The optional 'name' param is left to the schema, which is acceptable at full coverage.

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

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

States a specific verb and resource ('Promote an existing component into a reusable SYMBOL') and its scope ('shared, in sync, across pages'). This clearly separates it from siblings like add_symbol_instance, detach_symbol, and delete_symbol.

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

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

Explicitly tells the agent what to pass (targetPath from read_page) and covers a non-obvious second use case (repairing broken linkage), pointing at list_symbols → health. It even routes the failure case ('detached') to the alternative delete_section + add_symbol_instance.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the default read is bounded and complete (~1-2 KB), outline is character-capped, and full is the entire cleaned JSON — useful cost/fidelity signaling for a read 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?

Front-loads the read purpose, then the before/after discipline and the copy scoping rule. Four sentences with little waste, but dense enough that each clause has to be parsed carefully rather than skimmed.

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 return-format burden and does so: it describes the section list with target path, text preview and descendant count, and characterizes the size/fidelity of each detail mode. Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema by explaining how the two parameters interact — detail: full should be paired with targetPath of the single section being copied, and targetPath scopes the read to one subtree instead of the whole page.

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 — reading the current page structure and addressable component target paths — which is clearly distinct from siblings like read_selection (current selection) and list_pages (page inventory). The description's mention of target paths tells the agent this is the tool that reveals edit coordinates.

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 before/after triggers: call before editing a named or relative component that is not the current selection, and again after applying edits to verify. It also gives a when-not: for copying, use detail: full with a single targetPath rather than a whole-page read. An agent can sequence its calls without guessing.

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 as a read-only, idempotent, non-destructive local operation. The description adds genuinely new behavioral context by stating 'Secrets are never surfaced' and by enumerating what the read returns, which the annotations do not cover.

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

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

A single compact sentence with the resource and return fields front-loaded and no wasted clauses. Every phrase carries information.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the description supplies the two things an agent actually needs: what is read and what fields come back. The secrecy note closes 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?

The tool takes zero parameters, so the schema-based baseline of 4 applies. There is no parameter surface for the description to explain or compensate for.

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

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

States a specific verb (Read) and resource (currently selected component) and enumerates the returned fields (type, classes, attributes, text). It is distinguishable from siblings like swebsy_read_page, though it does not explicitly name the alternative 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 phrase 'currently selected' implies the precondition that something must be selected, which is useful contextual guidance. However, it names no alternatives and does not say what happens when nothing is selected, leaving usage largely inferable.

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, destructiveHint=false, openWorldHint=false, so the mutation/scope profile is covered; the description adds beyond that by disclosing the redo ordering ('oldest-undone last') and the important state fact that any new edit clears the redo buffer. It does not explain what happens when the stack is empty, which keeps it at 4.

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

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

Two short, front-loaded sentences with no filler; the primary purpose leads and the state caveat follows. Every clause carries actionable meaning.

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

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

For a state-mutating tool with no output schema the description covers the undo relationship and the clearing behavior, which is good. However it omits any explanation of the lone 'steps' parameter and says nothing about the outcome when the redo stack is empty, leaving real gaps 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?

The schema has 0% description coverage and the single 'steps' parameter (integer, 1-20) is never mentioned in the description. An agent gets no explanation of what 'steps' controls, how many redo operations it applies, or its default when omitted, so the description fails to 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?

States a specific verb ('Re-apply') and explicitly ties the resource to reverted tool calls, naming the sibling swebsy_undo as its counterpart. This lets an agent distinguish redo from undo without opening either schema. It falls short of 5 only because it never states the resource/domain (the design-editor state) in its own terms.

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 reference to 'tool calls reverted by swebsy_undo' clearly sets the precondition for use, and 'Cleared by any new edit' tells the agent when the tool will no longer have anything to act on. There is no explicit when-not or alternative beyond undo, which is implied, so it stops just short of a full 5.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, and the description adds scoped-mutation context: only the internal name changes, not SEO or public title. It still omits permission requirements, reversibility, and any side effects on saved references, which keeps it from a 5.

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

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

Two short sentences with zero filler; the action is front-loaded and the scope caveat follows immediately. 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 two-parameter mutation with 100% schema coverage, a complete set of annotations, and no output schema, the description covers the essentials plus the key scope boundary. Only the absence of an explicit pointer to the alternative tool for public/SEO titles keeps it from full marks.

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

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

Schema description coverage is 100% and both parameters are fully documented in-schema (non-empty name, trimmed; authoritative siteId from swebsy_list_sites). The description adds no further parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb (Rename) and resource (a saved site) and narrows the target to the internal Studio/Home name, which separates it from general site-metadata edits. It does not name a sibling tool (e.g. update_settings or rename_symbol), so it is clear but not sibling-differentiated by name.

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

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

The clause "This does not change its SEO or public title settings" gives an explicit when-not boundary that steers agents away from the wrong tool for public-facing title edits. It stops short of naming the correct alternative (presumably swebsy_update_settings), so it is strong context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description usefully clarifies that only the display name in the Symbols panel changes, but it says nothing about whether the new name propagates to existing symbol instances, what happens on duplicate names, or error behavior.

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

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

A single tight sentence with the scope clarifier in parentheses, front-loaded with verb and resource. Slight redundancy with the title, 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 simple two-parameter mutation with annotations and no output schema, the description covers the essentials but leaves gaps: rename side effects on instances and failure modes are unstated. Adequate, but not complete for a write operation.

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

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

Schema coverage is 50%: symbolId is documented as coming from list_symbols, but the name parameter has no schema description. The parenthetical 'the name shown in the Symbols panel' adds real meaning for that parameter, which is why this sits at the baseline rather than below it.

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

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

The description gives a specific verb (Rename) and resource (a symbol), and the parenthetical pins down exactly which name is affected. It is clear on its own, though it does not explicitly contrast itself with sibling rename-like tools such as swebsy_rename_site or swebsy_promote_to_symbol.

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 given, and no alternatives are named. An agent must infer that this is the tool for changing an existing symbol's label rather than re-creating or promoting one.

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 readOnlyHint=false, so the safety profile is covered. The description adds meaningful context: it overwrites all top-level sections of the currently selected page and does not create or append, which clarifies the destructive scope. It stops short of stating irreversibility or undo behavior, so it is not fully complete.

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

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

The description is front-loaded with the core action and scope, followed by explicit exclusions and alternatives. Every sentence earns its place by clarifying behavior or routing the agent, with no wasted text.

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

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

Given the destructive mutation and the absence of an output schema, the description covers what is needed: the selected page is overwritten, no new page is created, no single section is appended, and sibling alternatives are named. The annotations already supply the safety profile, leaving no critical gaps for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, and both parameters (`plan`, `components`) are richly documented in the schema. The description adds only the repeated instruction that each top-level component should be wrapped in a container, which is already stated in the schema, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: replace ALL top-level sections of the currently selected page with generated components. It explicitly distinguishes this tool from `create_page` and `add_section`, so an agent can identify the correct tool without opening sibling schemas.

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

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

It states exactly when to use the tool — when the user asks to build, replace, or redesign an entire page — and names the conditions that select alternatives (`create_page` for new pages, `add_section` for appending one section). No inference is required.

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

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

Annotations declare readOnlyHint=false, so this is a state-changing operation, but the description gives no hint that selecting alters the agent's working context (what subsequent tools target) or whether selection persists across sessions. For a mutation-flagged tool with no output schema, the description leaves the behavioral consequence of 'select' entirely unexplained.

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

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

A single short sentence with zero padding and the scope front-loaded. Its brevity is efficient rather than verbose, though it edges toward under-specification.

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

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

For a context-setting tool in a 40-tool suite, an agent needs to know that this changes the active page for later operations and what state it requires. Neither is stated, no output schema exists, and the annotations only cover the safety profile, so the definition is thin.

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

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

Schema coverage is 100% and the schema already states the parameter accepts a page id or name, so the description cannot improve much here. It adds nothing about ambiguity handling (e.g., duplicate names) or format expectations, landing at the baseline.

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

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

Specific verb ('Select') plus resource ('a page') within a named scope ('connected Studio project'), so the agent knows exactly what the tool acts on. It does not distinguish itself from near-siblings like swebsy_read_page or swebsy_open_site, which is what keeps it below a 5.

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

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

The description offers no when-to-use guidance, no prerequisites (does a project need to be connected/open first?), and never names an alternative such as swebsy_read_page or swebsy_list_pages. The agent must infer that 'select' means making a page the active target for subsequent section/block operations.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that: it explains the readiness-check workflow and previews the return payload, which annotations cannot convey.

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

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

Two sentences, no filler, and the payload description is front-loaded before the usage instruction. The field list is dense but each listed field earns its place as a readiness signal.

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

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

With no output schema, the description carries the burden of describing the return contents and does so completely, including the theme summary and the verbose toggle. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, and the single 'verbose' parameter is fully documented in the schema (default false, what it adds). The description mentions the summary but adds no semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb (report) and enumerates the exact fields returned (bridge status, siteName, selected page, editorReady, theme summary), so the agent knows precisely what this tool answers. It is clearly distinguishable from siblings like list_pages or read_page, which are content-oriented rather than connection/diagnostic.

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

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

Explicitly states when to use it: after creating or opening a site, and gives a concrete gating condition (wait until editorReady is true and siteId matches). It doesn't name alternative tools, but the context is clear enough for an agent to sequence it correctly.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds substantial non-obvious behavior: it returns `blocked` on conflict, guarantees hand edits are never overwritten, notes session scoping, ordering, and that restored paths can shift. This is exactly the kind of context an undo tool needs beyond structured fields.

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

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

Three front-loaded sentences with no filler: scope and ordering first, then the exclusion, then the refusal semantics and follow-up. Every clause carries operational information (what it reverts, what it won't, when it blocks, what to do next).

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

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

Despite no output schema, the description discloses the notable return signal (`blocked`), the mutation scope, conflict behavior, and the post-call read_page step. For a single-optional-parameter tool with full schema coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, and the single `steps` parameter is fully documented in the schema (min 1, max 20, default 1). The description's 'tool call(s)' implies multiplicity but adds no syntax or limit detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('Revert') on a specific resource (your own last editing tool call(s)), scoped to the current session and ordered newest-first. It explicitly contrasts itself with the sibling redo and enumerates the covered tool families (add/edit/delete/move/duplicate_section, insert_block, update_settings, page tools), so an agent can distinguish it without opening schemas.

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

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

Gives explicit when-to-use context (last editing call this session), explicit exclusions ('Does NOT undo symbol or asset tools'), and a follow-up instruction ('call read_page afterwards') because paths may shift. The refusal condition ('when a page, CSS or settings it would restore has been edited since') tells the agent exactly when it will fail.

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 a non-read-only, non-destructive write. The description adds genuine behavioral context beyond that: links pointing at the old './slug.html' across every page are rewritten to follow the new slug, and the home page's reserved 'index' slug is locked while its display name remains editable. It does not cover failure modes (e.g. collisions with reserved names) or what the response returns.

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

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

Three short sentences, front-loaded with the core operation, then the side effect, then the edge case. Nothing is wasted and no sentence is merely 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?

For a three-parameter mutation with no output schema, this covers the target selection, the two mutable fields, the cross-page consequence and the one hard constraint (locked index slug). Missing only error/permission behavior and confirmation of how the new slug is reported back.

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

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

Schema coverage is 100%, so the schema already explains name, page and the fileName slug format including folder paths and sanitization/dedup. The description reinforces that both name and slug are optional-ish targets ('and/or') but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (rename) and resource (page) plus the secondary slug change, and maps itself to a known UI affordance ('the Pages panel's rename'). It is easily distinguishable from create_page, delete_page, duplicate_page and rename_site in the sibling list.

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

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

Usage is clear from the phrasing: it is the tool for changing an existing page's name or URL, and the reader is pointed to list_pages via the schema for obtaining the page identifier. It does not name an explicit alternative or call out when not to use it, so it stops short of a 5.

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

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

Annotations already declare a non-readOnly, non-destructive, closed-world mutation, and the description's 'provide ONLY the fields that change' plus 'ALWAYS set BOTH light and dark variants' add genuine partial-update and domain context that the annotations don't carry. It is silent, though, on the fields that are whole-value replacements (customTailwindConfig, customRobotsTxt, advanced.* code, the font arrays) and on the Studio flagging of raw-code changes — the schema carries that burden instead. No contradiction with the non-destructive hint.

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 verb, and the enumeration does function as an index for a very large 12-parameter schema. But it is a single ~90-word run-on whose itemisation duplicates schema keys, and the placement of the image-vibe workflow after the list buries it. Adequately sized, weakly structured.

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 broad mutation tool with no output schema, the description covers scope, partial-update intent and the site-wide vs per-page split. It omits what happens after the change (whether a publish/deploy step is required), any permission or plan caveats, and any undo/reversibility note. Adequate but with clear gaps.

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

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

Schema description coverage is 92% across 12 nested params, so the schema already does nearly all parameter explanation (replace semantics, id formats, token rules). The description only restates the parameter groupings and their parenthetical key names, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Update site settings') and then enumerates the exact surfaces it governs (SEO, fonts, deploy, favicon, analytics, globalTheme, performance, advanced code), so an agent knows this is the site-configuration catch-all. It also draws the key in-tool boundary between site-wide (`general`/`seo`) and per-page (`page`). It never distinguishes itself from the sibling `swebsy_update_page`, so an agent must infer that boundary itself.

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

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

Gives real invocation directives: 'Provide ONLY the fields that change' and 'use `page` to change ONE page', plus a specific situation for the tool ('match the theme to a reference IMAGE's vibe'). However it names no sibling alternative (e.g. `swebsy_update_page` for page content, `swebsy_rename_site` for renames), so when-to-use-this-tool-vs-another is left to inference.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond that, disclosing state-preservation semantics ('components keep their ids, id-styles and symbol links') and the side effect that invalidates cached state ('Paths shift'). That is exactly the behavioral context an agent needs before chaining edits.

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, zero filler, and the core action is front-loaded before the examples, the preservation guarantee, and the path-shift warning. Each sentence carries a distinct, actionable fact.

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 covers purpose, preservation, the required re-read follow-up, and the correct alternative tool. It does not say what the call returns (e.g. new paths for the wrapped block) or how to undo, which would fully close the loop for an agent planning a sequence of edits.

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

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

Schema description coverage is 100%, so all four parameters (including the endPath range semantics and the tagName enum constraints) are already documented in structured form. The description's example of wrapping 'everything between the navbar and footer' illustrates endPath but adds no syntax or format detail the schema lacks. Baseline 3 applies when the schema does the heavy lifting.

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 ('Wrap a run of sibling components in one new element') and immediately grounds it with two concrete examples (navbar/footer into `<main>`, a footer symbol into `<footer>`). It also names the siblings it is not — `edit_section` and `replace_page_content` — so an agent can separate it from the other structural tools without opening schemas.

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

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

Gives an explicit directive ('ALWAYS use this to add a wrapper') plus the consequence of the alternative ('re-sending the components through edit_section/replace_page_content loses their styles'). It also states the prerequisite for the next call: 'call `read_page` before the next path-based edit.' When-to-use, when-not-to-use, and sequencing are all covered.

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