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

No annotations are provided, so the description carries the full burden. It discloses the default append behavior and the positioning mechanism, which is useful. However, it does not mention side effects (e.g., whether the operation is undoable), prerequisites (like having a page open), or the nature of the mutation (persistent vs. temporary). For a mutation tool, this is a moderate disclosure but not comprehensive.

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

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

The description is two sentences, front-loaded with the core purpose and followed by the key positioning caveat. Every word earns its place; no fluff or redundancy. It is efficiently structured for quick agent scanning.

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

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

The tool has a complex nested `component` object, but the schema provides exhaustive descriptions for every property. The description covers the essential usage and placement semantics. It does not explain return values (no output schema) or preconditions beyond 'current page', but these are either implicit or adequately covered by the schema. It is complete enough for a tool of this complexity.

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% (every parameter has a schema description), so the baseline is 3. The description adds value by explicitly tying `position` to `targetPath` ('pass `position` plus the `targetPath` of the component to place it next to'), clarifying the interaction beyond the schema's individual descriptions. It also explains the default for `position` (end) in plain language. This lifts it above baseline.

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

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

The description states a specific verb ('Insert') and resource ('a new section into the current page'), and clarifies the use case ('adding discrete sections (hero, features, pricing, CTA) to an existing page'). This distinguishes it from sibling tools like swebsy_insert_block (which likely targets blocks within a section) and swebsy_create_page (which creates a whole page). The scope is unambiguous.

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

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

It explicitly says 'Use for adding discrete sections... to an existing page', which gives a clear when-to-use. It also explains the default behavior (appends to end) and how to position via `position` and `targetPath`. However, it does not explicitly name alternative tools for other scenarios (e.g., when to use insert_block instead), though the section focus implicitly separates it. This is clear but not exhaustive.

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?

Without any annotations, the description must carry the behavioral disclosure burden. It does disclose that the instance 'stays in sync with the symbol main and every other instance', which is a critical behavioral trait. It also implies a precondition (current page requires selection). However, it does not mention potential side effects, error conditions, or any other behaviors beyond the sync. Given the absence of annotations, the description reveals the core behavior but leaves room for ambiguity about edge cases.

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

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

The description is two sentences with zero wasted words. It front-loads the primary action and sync behavior, then immediately gives the key prerequisite. Every phrase adds value—'linked', 'stays in sync', 'reuse'—without redundancy. It is perfectly concise and well-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 tool with three parameters, no output schema, and clear purpose, the description covers the essential context: why to use it (reuse), how it behaves (linked/sync), and a prerequisite (select page). It does not mention problems like invalid symbol IDs or performance implications, but those are typical and not necessary. It could be a 5, but the lack of any mention of error behavior or what happens if the page already contains such an instance makes it slightly incomplete.

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

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

The input schema covers all three parameters with full descriptions (100% coverage), including the 'targetPath' explanation about needing it for before/after placement. The tool description adds minimal extra parameter semantics—only that 'select_page first' is a prerequisite and 'list_symbols' is the source for symbolId. Since the schema already carries the parameter details, the description does not need to compensate, and the added context is helpful but not crucial.

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

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

The description clearly states a specific action ('Add a linked INSTANCE of an existing symbol') and the target ('to the CURRENT page'). It distinguishes from siblings like add_section or insert_block by emphasizing the linked/sync nature and pointing to list_symbols for the source. The purpose is unambiguous and differentiates from alternatives without needing to open other 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?

The description provides clear usage context: it tells the agent to select the target page with select_page first, and directs to list_symbols to find the symbolId. It also frames the tool as the way to reuse shared components across pages. It lacks explicit when-not-to-use guidance or mention of alternatives like add_section, but the purpose itself is specific enough that an agent can infer the right situation. This is strong but not exhaustive.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: it is a 'smart, per-section staggered entrance' affecting 'headings, text, images, buttons, and cards' while skipping 'navbars/footers'. This gives the agent a good sense of what to expect. It does not mention reversibility or whether it overwrites existing animations, but the core behavior is well conveyed.

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

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

The description is a single, tightly packed sentence that front-loads the purpose and then adds usage guidance. There is no wasted wording, and the key information (what it does, elements affected, when to use) is delivered efficiently. Perfectly structured for agent consumption.

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

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

For a tool with one optional parameter and no output schema, the description is sufficiently complete to enable correct invocation. It covers the purpose, usage trigger, and behavioral details. It does not mention side effects like whether existing animations are overridden, but given the simplicity and the parameter info in the schema, this is a minor gap. Overall, an agent can confidently use this 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?

The schema fully describes the single 'scope' parameter with enum values and a clear description. The tool description adds no additional semantic detail about parameters beyond what the schema already provides. Per calibration, with high schema coverage (>80%), the baseline is 3, and there is no extra value to raise 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 clearly states the specific action ('Apply Swebsy's built-in scroll-reveal animation') and the resource it affects (page/site elements), and differentiates from manual animation via 'hand-placing animate-* classes'. It is specific and unambiguous, distinguishing it from all sibling tools, which focus on sections, pages, or content manipulation.

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

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

The description gives explicit when-to-use guidance: 'Prefer this over hand-placing animate-* classes whenever the user asks to animate the page or site, or wants a consistent reveal.' This not only states the trigger condition but also compares it to an alternative, clarifying the preferred choice. It does not explicitly state when not to use, but the condition is clear enough.

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?

No annotations are provided, so the description carries the burden. It discloses the side effect (writes a file under .swebsy-agent/screenshots/) and the return value (file path), which is good. However, it doesn't mention whether the capture is synchronous, whether it overwrites existing files, or whether it requires a page to be open/selected. These are moderate gaps for a capture 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?

Three sentences, each earning its place: the first states the action and output, the second gives the return value, the third provides scoping guidance. The warning is front-loaded and directly actionable.

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

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

For a tool with 3 params, 100% schema coverage, and no output schema, the description covers the core workflow well: what it does, where it writes, what it returns, and when to scope. The main missing piece is the targetPath vs selectionOnly interaction, and whether a page must be active. These are minor but real gaps.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the relationship between targetPath and read_page target paths, and by warning about downscaling. But it doesn't clarify the interaction between targetPath and selectionOnly, which is a meaningful semantic gap.

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

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

The description states a specific verb ('Capture'), a resource ('styled screenshot of the current page'), and a concrete output ('written under .swebsy-agent/screenshots/', 'Returns the file path'). It also distinguishes itself from sibling tools by mentioning read_page target paths and component-level capture, which no other sibling name suggests.

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

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

The description explicitly tells the agent when to use targetPath ('when verifying ONE section') and warns against whole-page PNGs for component detail. It also implies the alternative (read_page for structural verification) by referencing read_page target paths. This is clear, actionable 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool 'apply[ies]' the direction and should be called once, implying a mutating action. However, it does not disclose whether repeated calls override the existing direction, whether the action is reversible, or any side effects on existing content. This leaves important behavioral details ambiguous.

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

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

The description is concise (about four sentences) and efficiently front-loaded with the core action, followed by timing, parameter preference, and exclusion. Every sentence adds meaningful information without 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?

Given the tool's moderate complexity (nested objects, two parameters) and rich schema, the description covers the essential context: when to call, what it does, and when to use each parameter. It does not specify the return value, but there is no output schema, so that omission is acceptable. The description is nearly complete, though it could explicitly mention that a site must already exist, but this is implied from the timing guidance.

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

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

Schema description coverage is 100%, and the schema itself thoroughly describes each parameter, including the nested custom object's fields. The description adds valuable decision-making guidance by stating which parameter to prefer (`directionId` over `custom`) and when the custom fallback is appropriate, going beyond mere parameter lists.

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

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

The description clearly states the tool's purpose: committing a site to a specific visual direction and applying it (fonts, type roles, palette swatches). It uses a specific verb-resource pairing and distinguishes itself from siblings by describing a unique action (commit design direction) not present in any other tool.

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

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

The description provides explicit when-to-use guidance: 'Call this ONCE, BEFORE generating a new site's first page' and explicitly states when not needed: 'Not needed when editing a site that already has a direction.' It also gives a decision rule between parameters: 'Prefer a `directionId` from the sampled menu; supply the `custom` fields only when the user's brief clearly calls for something the menu doesn't cover.'

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

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

With no annotations, the description carries the full burden. It discloses creation, default selection, the 'nearly empty' initial state, and that the response includes the new page's id and fileName. It does not mention prerequisites or side effects on the current selection, but core behavior is clearly conveyed.

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

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

The description is compact and front-loaded: primary action and return values first, followed by practical workflow guidance and an explicit when-not-to-use note. Every sentence adds distinct value 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 straightforward creation tool, the description is nearly complete: it explains the blank state, return values, and how to continue the workflow. Minor gaps remain around whether a project must already be open and the effect of selecting the page, but these are not critical for correct invocation.

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

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

Schema description coverage is 100%, and each parameter is already well documented. The description adds only minor context around `select` (default true) and the returned `fileName`, so the baseline of 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 states a specific verb and resource: 'Create a NEW blank page in the project.' It also explicitly distinguishes this tool from `replace_page_content` and describes its default select behavior and return values, making the purpose unambiguous.

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

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

Usage guidance is explicit: 'Use THIS to add an additional page; use `replace_page_content` (NOT this) to overwrite the current page's content.' It also tells the agent the intended follow-up workflow with `replace_page_content`, `add_section`, and `link_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?

With no annotations, the description carries the full burden of behavioral disclosure. It explains that the tool creates and opens a site, describes the template behavior, and reveals the asynchronous readiness requirement by instructing polling of swebsy_status until editorReady is true and siteId matches.

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

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

The description is two sentences with no filler. The purpose is front-loaded, the templateId conditional is stated compactly, and the required post-call polling step is given in a clear, actionable way.

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 schemaigator and no annotations, the description includes purpose, template behavior, and an explicit readiness-polling handoff. It does not describe the direct response shape or failure modes, but the polling instruction mitigates the most important operational gap.

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

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

Schema description coverage is 100%: the single optional parameter templateId is already documented as optional and omittable for a blank site. The description adds a small increment by stating the template is imported unchanged, but the schema already carries the core semantic weight.

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

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

The description opens with 'Create a site and open it in Studio,' a specific verb and resource that distinguishes this tool from sibling creation tools like swebsy_create_page. It also clearly differentiates the blank-site and template-import paths.

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

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

The description provides explicit conditional usage: omit templateId for a standard blank site, or provide an installed template ID to import unchanged. It also directs the agent to poll swebsy_status before editing, providing a clear next-step workflow, though it does not explicitly name alternative tools or exclusion criteria.

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

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

With no annotations provided, the description carries full burden. It discloses the key side effects: refusal by default for in-use assets, and that force:true clears live component references. It does not mention reversibility or error conditions, but for a delete tool these are the most critical behaviors and are covered well.

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 with no wasted words. The main action is front-loaded, followed by the default behavior and the force caveat. Every sentence adds necessary information; the structure is clean and scannable.

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 delete tool, the description covers the purpose, prerequisite, default refusal, and force behavior. There is no output schema, so return values aren't required. Minor gaps like error handling on invalid assetId or permanent deletion are implied by 'delete' and are not critical for correct usage.

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

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

The schema already documents both parameters clearly (100% coverage). The description adds value by explaining the default refusal logic tied to assetId and the side effect of force, reinforcing and expanding on the schema descriptions. This extra context helps the agent decide when to set force.

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

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

The description states a specific verb ('Delete') and resource ('one managed asset') within a clear context ('open site's asset gallery'). It distinguishes from siblings like swebsy_delete_section by naming the exact target type. The default refusal behavior further clarifies what the tool does, making it unambiguous.

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

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

It provides explicit guidance: call swebsy_list_assets first to obtain a valid assetId, and notes that force:true should be used only when explicitly intended. While it doesn't explicitly say when to use this instead of other delete tools, the name and description make it clear this is for assets, and the prerequisite is explicitly 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?

With no annotations, the description carries the behavioral burden and largely succeeds: it says deletion is 'entirely,' clarifies the default-selection behavior, and explains the `targetPath` override sourced from `read_page`. It does not explicitly state irreversibility or error behavior, but 'remove entirely' implies permanent destructive action.

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

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

Three sentences, each earning its place: the core action, the key alternative to avoid, and selection/targeting behavior. It is front-loaded with the action and contains 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?

Given only two parameters, no output schema, and no annotations, the description is complete enough for correct invocation. It covers what is deleted, how deletion is scoped, and where `targetPath` comes from, with no critical invocation detail 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 the schema already documents `summary` and `targetPath` well. The description adds little beyond the schema: `targetPath`'s source is already stated as 'exactly as returned by the most recent read_page call.' This matches the baseline expectation when structured 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?

The description opens with a specific verb and resource: 'Remove a component from the current page entirely.' It also distinguishes itself from the alternative of emptying a section's contents, making the tool's purpose unmistakable versus deletion-by-clearing.

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

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

The description gives explicit guidance: use this tool instead of emptying a section's contents, because emptying leaves a stray blank div. It also explains when to use `targetPath` versus relying on the selected component, which fully clarifies invocation 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?

No annotations are provided, so the description carries the full burden. It discloses the critical behavioral consequence of editing: 'Preserve existing IDs: an id kept in the edit keeps the styles attached to it; an id you drop loses them.' It also reveals that a `style` object merges into existing styles rather than replacing them. It doesn't mention whether the operation is reversible or whether it persists immediately, but the ID/style-loss warning is a significant behavioral disclosure.

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

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

The description is dense but well-structured: it front-loads the core action, then orders the three strategies by preference, then ends with the critical ID-preservation warning. Every sentence carries information. It is longer than ideal, but the complexity of the tool (three mutually exclusive input modes plus target selection) justifies the length.

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

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

For a complex mutation tool with no annotations and no output schema, the description covers the key decision points: which input to use, how to target a component, and what behavioral consequences to expect. It doesn't describe the return value or error cases, but the schema already documents all parameters thoroughly, and the description's guidance on selection vs targetPath is complete enough for an agent to invoke the 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%, so the baseline is 3. The description adds value beyond the schema by explaining the relationship between the three mutually exclusive edit modes (component vs html vs patch), the merge semantics of `style`, and the meaning of `targetPath` relative to `read_page` output. The compact DSL aliases (t/c/x/a/k) are also explained in the schema, but the description's 'exactly one' constraint and preference ordering add real semantic guidance.

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

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

The description opens with a specific verb and resource ('Modify an existing component') and immediately distinguishes the default target (canvas selection) from the `targetPath` alternative. It also names three distinct edit strategies (component, html, patch) with clear guidance on when each is preferred, which separates it from siblings like swebsy_add_section and 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?

The description explicitly states when to use each input mode: 'Preferred: provide component... Alternative: provide html... Fallback: provide patch... Supply exactly one.' It also explains when to use targetPath ('when the user names or relatively identifies a component instead of selecting it'). This is explicit routing guidance with no ambiguity.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool writes files to a directory and returns outDir, page paths, and file counts, plus a verification method (grepping HTML files). It does not mention side effects like overwriting or permissions, but the core behavioral traits are covered adequately for a non-destructive export action.

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

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

The description is two sentences with no wasted words. The core action and destination are front-loaded, followed by return value and verification guidance. Every sentence adds value and the structure is optimal.

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

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

The description covers the action, destination, return value (outDir, paths, counts), and a verification method. With no output schema and 5 optional parameters, this is reasonably complete. It lacks explicit error conditions or prerequisites (e.g., site must exist), but given the sibling context, that is not a critical omission.

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

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

Schema coverage is 100% with clear descriptions for each parameter (minify, baseUrl, verbose, includeStatic, includeProjectJson). The description adds a small link between the static/JSON modes and the corresponding boolean parameters but does not enrich the parameter meanings beyond what the schema already provides. 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 clearly states the verb 'Export' and the resource 'the site' to a specific destination (.swebsy-agent/exports/). It also distinguishes two output modes (static files and project JSON) and lists the return values, making it unmistakably different from the sibling editing 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?

The tool is the only export operation among siblings, so its use case is implicitly clear. It mentions two export modes (static and JSON) but does not explicitly state when to choose one over the other; however, the parameter descriptions cover that choice. No alternative export tool exists, so exclusions are unnecessary.

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

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

With no annotations provided, the description carries the full burden. It adds genuinely useful behavioral context: the content is 'static' (deterministic/repeatable) and scoped to component system, theme classes, and conventions. However, it does not disclose the return format, output size, or explicitly confirm read-only semantics, which matters since there is no output schema to fall back on.

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 ~20-word sentence that front-loads the resource ('static Swebsy builder guidance'), adds scoping detail in a parenthetical, and ends with the alignment context. Every word earns its place; there is no boilerplate 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 zero-parameter static-doc loader this is nearly complete: invocation is trivial (no inputs), the object is named, and the content scope is enumerated. The remaining gaps — lack of explicit usage guidance and output format/size — are minor given the tool's simplicity, though a size warning would help an agent manage context when loading a likely lengthy guidance document.

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

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

The tool has zero parameters and the schema is an empty object, so the baseline is 4 per the rubric and there is nothing for the description to clarify. The description correctly implies no inputs are needed. No points are lost for missing parameter detail because none exists.

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

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

The description states a specific verb ('Load') and a specific resource ('static Swebsy builder guidance'), and clarifies the content scope with the parenthetical '(component system, theme classes, conventions)'. Among the 32 siblings, none other loads builder guidance, so it is readily differentiated from list_templates, list_blocks, and get_skill.

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 'that the in-app AI Builder is primed with' implies the intended use — loading the same knowledge the AI Builder uses in order to align with component/theme conventions — but there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Usage must be inferred rather than 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?

With no annotations, the description must carry the behavioral burden. It does communicate the primary behavior ('Returns the full instructions for that skill') and positions the tool as pre-action guidance, which implies a read-only operation. However, it stops short of explicitly stating that it has no side effects or mentioning any prerequisites, so some transparency is left implicit.

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 one front-loaded sentence that packs the core action, timing, relevant examples, and return value with no filler. Every clause earns its place, and the structure makes the most important information immediately visible.

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 is fully sufficient: it says what the tool returns, when to call it, and the schema enumerates every acceptable skill value. An agent has everything needed to invoke it correctly and understand 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?

The schema already documents the only parameter with an enum and a short description, giving it a solid baseline. The tool description goes beyond that by mapping enum values to real-world situations, such as 'adding animations' for animation and 'editing the nav' for nav-management, which helps an agent choose the right skill.

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

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

The description clearly states the action ('Load deep, on-demand guidance') and the resource ('for a specific area'), and the examples make it easy to distinguish this knowledge-retrieval tool from the sibling editing tools. It also explicitly says it returns the full instructions for the skill, so an agent knows what to expect.

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

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

The description gives clear timing guidance ('before acting on it') and enumerates concrete scenarios such as adding animations, composing a page, and editing the nav. It does not name alternative tools (e.g., get_builder_guide or list_skills) or state when not to use it, so it falls just 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the important re-theming behavior, warning that colors and fonts resolve against the current site's theme, so output will differ from the thumbnail. It does not explicitly state that insertion is non-destructive to existing content, but the 'insert' verb implies addition rather than modification.

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

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

Two concise sentences that front-load the core purpose and then add critical usage and behavioral context. No filler; every clause contributes value, including the caution about re-theming.

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

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

For a tool with four parameters and a nested adaptations object, the description covers the essential context: what it does, when to use it, and a key behavioral surprise. It omits explicit prerequisites like having an open site or calling read_page for targetPath, but those are inferable from the schema and sibling tools. Overall, the description is sufficient for an agent to call it correctly.

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

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

The schema already covers 100% of parameter descriptions, so the baseline is 3. The description mentions optional customization but adds no additional parameter semantics beyond what the schema provides for blockId, position, targetPath, or adaptations.

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

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

The description clearly states the action: inserting a pre-built block from the catalog, with optional customization. It identifies the resource (catalog blocks) and the verb (insert), making the tool's purpose unambiguous. It does not explicitly differentiate from sibling tools like swebsy_add_section, but the catalog-block focus is distinct enough.

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

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

The description explicitly says it is strongly preferred over generating from scratch when a matching block exists, giving a concrete condition for use. It implies using list_blocks to find a block and then inserting it, though it does not name alternatives like add_section. This provides clear when-to-use guidance, though it could be more explicit about 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?

With no annotations, the description carries the full burden. It explains the concrete behavioral outcome for navbar links (sets page target, keeps href and active state in sync) and for plain links/buttons (sets href to ./slug.html). This is valuable behavioral transparency beyond just saying 'link a page'. It doesn't cover edge cases like overwriting existing targets, but for this tool's scope it is adequate.

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

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

The description is concise, consisting of three sentences, with the core purpose stated first. It uses no filler and each sentence adds relevant detail (purpose, parameters, behaviors, usage timing). It is well-structured and front-loaded with the most important 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?

Given only two simple parameters and no output schema, the description is complete enough for an agent to understand how to call the tool correctly. It covers purpose, parameter sources, behavioral outcomes, and typical usage. Minor gaps like error handling or effects on existing links are not critical for a tool of this simplicity.

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% (both params have descriptions), but the description adds context beyond the schema: it tells the agent that targetPath comes from read_page and that page is an id or name. It also explains the role of targetPath as the link's location within the page structure, which helps the agent retrieve and pass correct values.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Point an existing link at a project page'. It also references the UI's 'Link to' picker, making the action concrete. It distinguishes itself from siblings like create_page by focusing on linking existing entities, not creating them.

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

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

The description provides clear guidance on when to use the tool: 'Use after create_page to wire a navbar to the new page' and explicitly explains the context for different link types (navbar vs. plain link/button). It doesn't explicitly exclude other scenarios, but it gives enough contextual cues for an agent to decide appropriately.

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?

No annotations are provided, so the description carries the full behavioral burden. It adds valuable non-obvious context by stating that reference checks span 'every page, shared symbols, styles, and site settings,' clarifying how usage counts are computed. It does not mention output shape or pagination, but as a listing tool it is reasonably transparent.

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

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

Three sentences, each with a distinct purpose: the main action and output, the reference-checking semantics, and a practical filter tip. No redundant or filler wording is present.

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 2-boolean listing tool with no output schema, the description covers scope, counting semantics, and a concrete use case, which is nearly complete. It is slightly lacking in that it does not describe the returned asset object shape or any ordering/pagination behavior, but those are modest gaps for this 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?

The schema already describes both parameters (100% coverage), so the baseline is 3. The description adds meaning beyond the schema by advising the specific filter combination 'imagesOnly:true and unusedOnly:true' for the deletion workflow, which is not present in the schema.

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

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

The description clearly states a specific verb ('List'), a resource ('managed assets'), a scope ('in the open site'), and an output trait ('whole-project usage counts'). This makes it easy to tell apart from sibling listing tools like list_blocks or list_pages, though it does not explicitly name an alternative.

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

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

The description provides a concrete usage scenario: 'Use imagesOnly:true and unusedOnly:true before deleting unused gallery images.' This tells the agent when to use the tool with specific filters, but it does not say when to prefer an alternative tool or when not to use this tool.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It states the tool lists catalog data and implies a read-only operation, but it does not explicitly say it is non-destructive or describe any side effects. For a simple read-only list tool, the lack of side effects is fairly obvious, but the description could be more explicit about the absence of mutations.

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

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

The description is a single sentence that is front-loaded with the action ('List') and resource ('pre-built block catalog'), then adds the output detail ('ids + labels') and the consumer context ('available to insert_block'). Every word earns its place; there is no redundancy or filler.

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

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

For a zero-parameter, read-only list tool, the description is nearly complete. It tells the agent what it will get (ids + labels) and why it matters (for insert_block). It does not specify the exact format of the list (e.g., array vs. object) or whether labels are human-readable, but the absence of an output schema and the simplicity of the tool make this 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?

The tool has zero parameters, so there is no schema burden to compensate for. The description adds meaning by specifying what the output contains (ids + labels) and its purpose (available to insert_block). With no parameters, the baseline is 4, and the description meets it by clarifying the return value's role.

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

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

The description states a specific verb ('List'), a specific resource ('pre-built block catalog'), and the exact output content ('ids + labels'). It also names the downstream consumer ('insert_block'), which distinguishes it from other list tools like swebsy_list_pages or swebsy_list_templates. This is a clear, non-tautological purpose statement.

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

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

The description implies when to use this tool: before calling insert_block, to discover available block ids and labels. It does not explicitly state when not to use it or name alternatives, but the reference to insert_block provides clear contextual guidance. Since there are no sibling tools that list blocks, the usage context is sufficiently 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?

With no annotations, the description itself must convey behavior. 'List' communicates a read-only operation, and the parenthetical enumerates exactly what will be returned. It does not mention prerequisites or errors, but for a zero-parameter listing tool this is minor.

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

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

Two concise sentences; the first states the operation and output fields, and the second provides routing guidance. No filler or 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?

For a zero-parameter, no-output-schema listing tool, the description covers operation, output fields, and when to call it. The only unstated detail is the exact JSON shape, but the field list makes it inferable.

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

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

The tool has no parameters, so there is no input ambiguity to clarify. The description adds value by naming the output fields an agent can expect, which is more useful than parameter documentation here.

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 ('the project's pages'), and enumerates the returned fields (id, name, fileName, section count, selected). This clearly differentiates it from sibling page-related tools like select_page and link_page by showing it is the read-only enumeration operation.

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 instructs the agent to call this instead of guessing a page name for select_page or link_page, naming the sibling tools it should precede. This gives clear when-to-use guidance, even though it doesn't enumerate all alternatives.

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

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

No annotations are provided, so the description carries the full burden. It does disclose that the tool returns metadata only and orders results newest-first, which is useful behavioral context. However, it does not mention whether the operation is read-only (though 'metadata only' strongly implies it), whether it requires an active session/pairing, or what happens when there are no saved sites. The description adds some value but leaves the safety profile implicit.

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

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

The description is a single, information-dense sentence that front-loads the core action ('List saved sites newest-first') and then packs the return fields into a compact list. Every word earns its place; there is no filler or repetition of the tool name.

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 zero-parameter, no-output-schema listing tool, the description is nearly complete: it specifies ordering, the metadata-only nature, and the exact fields returned. The only gaps are minor—no mention of empty-result behavior or session requirements—but these are not critical for an agent deciding whether to call this tool. The sibling list confirms it is one of many list tools, and the description gives enough to distinguish it.

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

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

The tool has zero parameters, so there is no schema burden to compensate for. The description fully explains what the tool returns, which is the only semantic content an agent needs. With 0 params, the baseline is 4, and the description meets it by clearly defining the output scope.

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

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

The description states a specific verb ('List'), a specific resource ('saved sites'), and a precise scope ('newest-first as metadata only'). It enumerates the exact fields returned (IDs, internal names, status, timestamps, template ID, page count, open state), which distinguishes it from sibling tools like swebsy_list_pages and swebsy_list_templates. The phrase 'metadata only' also clarifies it is a lightweight read operation, not a content fetch.

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

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

The description implies a read-only listing use case and the 'newest-first' ordering gives some context, but it does not explicitly state when to use this tool versus alternatives such as swebsy_list_pages or swebsy_list_templates. There is no mention of prerequisites (e.g., whether sites must be paired/created first) or exclusions. The context is clear enough for a simple list tool, but the guidance is not explicit.

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

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

No annotations are provided, so the description carries the burden. It discloses that the output is a list of available skills with one-line summaries, which implies a read-only enumeration. It does not explicitly state side-effect-freeness or auth requirements, but for a simple listing tool this is adequate.

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

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

A single, front-loaded sentence that names the action, resource, and output format without any wasted words. Every part of the description 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 parameterless listing tool with no output schema, the description is nearly complete: it names the resource, enumerates the categories, and specifies one-line summaries as the output. A brief pointer to swebsy_get_skill for deeper guidance would improve it, but it is not essential.

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

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

The tool has zero parameters, so the description does not need to explain parameter meaning. The baseline of 4 applies; the description's mention of specific skill categories adds useful context about what the returned list will contain.

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

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

The description uses a specific verb ('List') and resource ('available deep-guidance skills') and enumerates the skill categories (animation, page-composition, copywriting, forms, nav). This clearly distinguishes it from sibling listing tools like swebsy_list_blocks and swebsy_list_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?

The intended use is implied by the verb 'List' and by the existence of swebsy_get_skill as a sibling, but the description does not explicitly say when to use this tool versus alternatives or mention that get_skill provides deeper detail. It is clear but not fully prescriptive.

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

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

With no annotations, the description carries the full burden. It thoroughly explains the output structure and the meaning of health categories, but it does not explicitly state whether the operation is read-only or has side effects. Although listing is intuitively safe, the description could be clearer about behavioral guarantees beyond the returned data.

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

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

The description is fairly long but every sentence adds value: purpose, output fields, health details, and usage pointers. It is front-loaded with the core action and then elaborates. Slight verbosity in the health report could be trimmed, but overall it is efficient.

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 zero-parameter tool with no output schema, the description covers all essential aspects: what it lists, field names, health report interpretation, repair pathway, and typical placement in a workflow. Nothing critical is missing for an agent to use it correctly.

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

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

The tool has zero parameters, so the description cannot add parameter meaning. The baseline of 4 is appropriate; the description does not need to compensate for anything, and it appropriately focuses on output semantics.

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

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

The description states the tool lists the project's SYMBOLS, defines what they are, and enumerates the returned fields. It also references two sibling tools (add_symbol_instance and promote_to_symbol) that it pairs with, making its role distinct from other list tools like list_blocks or list_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?

It explicitly says to use the tool before add_symbol_instance to find the symbol id, and points to promote_to_symbol for repairing broken linkage. This gives concrete when-to-use guidance, though it doesn't discuss exclusions or cases where another list tool would be preferable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool 'refresh[es]' and lists templates and previews the returned data, but it does not clarify whether refreshing has side effects, caches data, or could fail. The word 'list' implies a read-only operation, but this is not made explicit.

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

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

The description is a single, compact sentence that front-loads the core action and resource, then lists the useful output fields and workspace context. Every word 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?

For a zero-parameter list tool, the description is complete: it names the resource, the returned data fields, and the contexts in which it works. There is no output schema, but the described return fields are sufficient for an agent to understand what the tool provides.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter information for the description to add. The baseline of 4 applies because no parameter guidance is needed.

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

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

The description states a specific action ('Refresh and list'), a clear resource ('installed site templates'), and enumerates the exact fields returned (names, descriptions, tags, fonts, preview URLs, thumbnail URLs). This clearly differentiates it from sibling list tools such as swebsy_list_pages or swebsy_list_blocks, even without naming them.

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

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

The description gives useful context by saying 'Works from Home or Studio,' which helps an agent know where the tool can be invoked. However, it does not explicitly state when to choose this tool over other listing tools, nor does it mention any exclusions or alternatives.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses idempotency, the paired-tab environment, the metadata return, and the readiness precondition via swebsy_status. Minor gaps like explicit failure modes remain, but the core behavior is transparent.

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

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

Two sentences deliver purpose, return value, idempotency, and a required follow-up with no filler. The action and resource are front-loaded, so an agent grasps the intent immediately.

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

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

For a one-parameter tool with no annotations and no output schema, this definition is complete: it states what to pass, what happens, what is returned, and what must be checked before editing. The agent has everything it needs to invoke the tool and continue the workflow.

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 only parameter, siteId, is already documented as the authoritative ID from swebsy_list_sites. The description adds little beyond framing the action as opening 'by ID', so the schema-heavy baseline of 3 is appropriate.

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

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

The description names a precise operation ('Open a saved site by ID in the paired tab') and a distinct outcome ('return its metadata'). This is specific enough to distinguish it from sibling tools like swebsy_create_site, swebsy_select_page, or swebsy_status.

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

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

The description implies when to use the tool: before editing, and it instructs the agent to poll swebsy_status afterward. However, it never explicitly contrasts this tool with sibling alternatives or states 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?

With no annotations, the description carries the behavioral burden. It discloses side effects: 'REPAIRS broken linkage... re-promoting an orphaned copy rebuilds its main and re-links every other copy of it, and re-promoting a symbol registers instances it had lost.' It also reveals output behavior (returns symbol id and repaired count) and the 'detached' condition. It does not mention permission requirements or whether the operation is reversible, but overall it is quite transparent.

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

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

The description is a single paragraph but packs necessary detail. It front-loads the main purpose and then explains repair behavior and alternatives. While dense, every sentence adds useful information without fluff. It could be slightly more structured, but it is appropriately sized for the tool's complexity.

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 return values (symbol id, repaired count, detached), and gives alternatives for detached cases. It references related tools (read_page, list_symbols, add_symbol_instance, delete_section). Missing details include what happens if a symbol with the same name exists or edge cases, but overall it provides enough context for correct invocation.

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

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

Schema coverage is 100% (both parameters have descriptions), so baseline is 3. The description adds value by explaining the origin of targetPath ('exactly as returned by read_page') and the meaning of the return value. This goes beyond the schema's field descriptions, improving semantic understanding.

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

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

The description clearly states the tool's primary purpose: 'Promote an existing component into a reusable SYMBOL so it can be shared, in sync, across pages.' It also specifies the resource (component) and the action (promote), and distinguishes its secondary repair role. It differentiates from siblings by referencing read_page for input and mentioning alternative tools for detached copies.

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

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

The description gives explicit when-to-use context: 'Pass its `targetPath` from read_page' with examples, and explains the repair scenario. It also provides an explicit when-not-to-use: 'copies whose structure has diverged too far are reported as `detached` — delete_section + add_symbol_instance those instead.' This clearly routes the agent to alternatives.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does this well by describing output size bounds ('~1-2 KB'), the character-capped outline mode, the complete cleaned JSON for full mode, and scoping behavior. It does not explicitly state 'read-only' or 'non-destructive,' but the verb 'Read' and the verify-after-edits context strongly imply it.

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

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

The description is front-loaded with the core purpose, then gives workflow guidance, then a verification note. Every sentence earns its place; there is no filler or repetition of schema fields.

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

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

For a tool with two optional parameters, no output schema, and no annotations, the description is remarkably complete. It explains all three detail modes, the targetPath scoping mechanism, and the correct calling contexts before and after edits. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by explaining when to prefer `detail: full` and why `targetPath` is 'strongly recommended' with it, plus describing the output character of each mode. This enriches the schema rather than merely repeating 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 states a specific verb and resource: 'Read the current page structure and addressable component target paths.' It immediately clarifies what the tool returns and how it fits into an editing workflow, distinguishing it from the write/edit siblings without needing to name them.

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

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

Usage is explicitly guided: call BEFORE editing a non-current named/relative component, use `detail: full` WITH `targetPath` when copying content, and call again AFTER edits to verify. This is concrete, actionable guidance that leaves little 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?

The description adds a valuable behavioral guarantee that secrets are never surfaced, which goes beyond a simple read. However, it doesn't disclose behavior when no component is selected, potential errors, or confirm it's side-effect free. With no annotations, more transparency is expected.

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, efficient sentence that front-loads the action, lists the returned fields, and includes the security note. No redundant words or filler.

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

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

For a no-parameter read operation, the description adequately lists the return fields (type, classes, attributes, text) and adds a security guarantee. It does not mention empty-selection handling or error conditions, but given the simplicity and no output schema, it is reasonably complete.

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

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

The tool has no parameters, and the schema coverage is trivially 100%. The description adds nothing about parameters because none exist. Baseline 4 applies for a zero-parameter 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?

States a specific verb 'Read' with a clear resource 'currently selected component' and enumerates what is returned (type, classes, attributes, text). This distinguishes it from sibling tools that modify or create, and from other read tools like swebsy_read_page by focusing on the selection.

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 mention of when to use this tool versus alternatives like swebsy_read_page or swebsy_capture. It doesn't clarify the concept of 'selection' or provide any conditional guidance for an agent choosing among read tools.

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

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

With no annotations provided, the description must carry the behavioral burden. It discloses the side-effect boundary (internal name only, not public settings), which is useful, but it does not mention reversibility, required permissions, or what happens to existing references.

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

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

Two concise sentences with no filler. The main action is front-loaded and the clarifying exclusion follows immediately, making it easy to parse.

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

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

For a simple two-parameter rename tool with no output schema, the description covers the key behavioral boundary and the schema covers parameters. The only minor gap is lack of detail about return values or failure modes, but this is not critical for such a straightforward operation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal additional meaning beyond what the schema provides, so the baseline score of 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 states a specific action ('Rename a saved site's internal Studio/Home name') and explicitly scopes what it does not affect (SEO/public title settings). This clearly distinguishes it from related tools like swebsy_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?

It gives clear context by stating the rename does not change SEO or public title settings, implying that swebsy_update_settings would be used for those. It lacks an explicit 'use this when...' statement but provides enough guidance for correct selection.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It clearly states the tool 'OVERWRITES the page', which signals destructive behavior, and emphasizes what it does not do (create/append). However, it does not mention reversibility, confirmation prompts, or whether changes are saved automatically, so it is not fully transparent about all side effects.

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

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

The description is three sentences with no unnecessary words. The main action is front-loaded in the first sentence, followed by explicit exclusions and a condition for use. Every sentence earns its place, making it easy to parse quickly.

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

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

For a destructive replace operation with a rich schema, the description covers the primary action, usage context, and exclusions. It mentions 'CURRENTLY SELECTED page' but does not explain how to ensure a page is selected or what happens if none is selected, and with no output schema it omits any description of return values. These are minor gaps given the tool's moderate complexity, so a 4 is appropriate.

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 provides detailed descriptions for `plan` and `components`, including compact aliases and the instruction to wrap each component in a container. The tool description adds no new parameter semantics beyond restating 'Each top-level component should be wrapped in a container,' which is already in the schema, so it meets the baseline without exceeding 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 clearly states the action—'Replace ALL top-level sections of the CURRENTLY SELECTED page with a generated list of components'—identifying both the specific resource (the selected page) and the operation (full replacement). It further distinguishes itself from siblings by explicitly naming `create_page` and `add_section` as alternatives for different operations, so an agent can easily tell this tool apart.

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

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

The description provides explicit when-to-use guidance: 'Use when the user asks to build/replace/redesign an entire page.' It also gives clear when-not-to-use conditions ('does NOT create a new page (use create_page) and does NOT append a single section (use add_section)') with named alternatives, leaving no ambiguity about which tool to pick.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Select a page' with no detail about side effects, whether selection persists, what happens if the page is not found, or how selection affects subsequent tool calls. The connected-project context is useful but minimal.

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

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

The description is a single, front-loaded sentence with no redundant wording. It is appropriately concise for a simple one-parameter tool, though it omits behavioral context that would make it more useful.

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 tool with one fully documented parameter, the description is minimally adequate: it names the action, the resource, and the connected-project context. However, without annotations or output schema, it leaves unclear what 'select' means operationally and how it relates to sibling tools. The absence of usage guidance and behavioral details makes it only minimally complete.

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

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

Schema description coverage is 100%, so the input schema already documents the single 'page' parameter as 'Page id or name to select.' The description adds no additional meaning beyond what the schema provides. This meets the baseline for high schema coverage.

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

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

The description uses a specific verb and resource: 'Select a page in the connected Studio project.' It clearly distinguishes the action from sibling tools like read_page, create_page, or list_pages. However, the meaning of 'select' is somewhat ambiguous—it doesn't specify whether this sets the active page for subsequent operations or just retrieves a selection.

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

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

The description gives no guidance on when to use this tool versus alternatives such as read_page or list_pages. It implies a connected Studio project but does not state prerequisites, sequencing, or situations where another tool would be more appropriate. There are no exclusions or alternative recommendations.

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?

Since no annotations are provided, the description carries the full disclosure burden. It does well by revealing that the URL is single-use, that clicking it connects automatically, and that raw code/port are available for manual entry. It stops short of explaining session validity or whether starting a new pairing invalidates previous URLs, but the core behavior is transparent.

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

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

The description is compact and front-loaded: it states the action in the first sentence, explains how the output should be used in the second, and adds a brief manual-entry fallback in parentheses. 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 zero-parameter tool with no output schema or annotations, the description adequately covers what the agent receives (pairUrl, code, port) and what the user should do with it. Missing details like URL expiration or whether a new session invalidates an existing one would improve completeness, but the essential invocation flow is present.

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

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

The input schema is empty with zero parameters and 100% schema description coverage, so the baseline is 4. There are no parameter semantics to clarify, and the description instead usefully clarifies the output contract.

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

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

The description clearly identifies a specific action: 'Start a pairing session.' It also names the primary output (single-use pairUrl) and explains its role, which distinguishes this tool from the 30+ sibling tools that are all about pages, sections, assets, or 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?

The description provides clear workflow guidance: give the pairUrl to the user to click, and it automatically connects their Studio tab; a manual fallback via code/port is also offered. It does not explicitly state when not to use the tool or name alternatives, but no sibling tool performs pairing, so the omission is minor.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns a summary by default and can optionally return the full settings object via the verbose parameter. It also implies a read-only nature (reporting status) and gives a practical tip about waiting for editorReady, which is helpful behavioral context.

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

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

The description is concise, two sentences, and front-loaded with the main purpose. The usage tip is added as a second sentence without unnecessary verbosity. Every word earns its place.

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

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

Given that there are no annotations, no output schema, and only one parameter, the description is largely sufficient. It tells the agent what the tool returns and how to use it for readiness checks. The only minor gap is that it doesn't explicitly state that the tool is read-only, but that is implied. Overall, it is complete enough for effective 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 already describes the only parameter (verbose) with its default and purpose. The description adds a little context by explaining what the default summary answers ('am I connected and what is open?'), but since schema coverage is 100%, the description provides minimal additional value beyond the schema.

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

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

The description clearly states the tool reports bridge status, siteName, selected page, editorReady, and a theme summary. It distinguishes it from other tools by focusing on status reporting, not editing or listing. Could be more specific about being a diagnostic/read-only tool, but it is clear enough.

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

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

The description provides explicit usage guidance: after creating or opening a site, wait until editorReady is true and siteId matches the expected site before editing. This implies it is used for checking readiness, which is useful. It does not explicitly mention alternatives, but given the sibling list, status is unique.

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?

No annotations are present, so the text must carry behavioral disclosure. The description and schema do this well: customTailwindConfig and fonts REPLACE prior values, `page: null` clears overrides, brandColors auto-generates both light/dark ramps, and darkThemeTokens must use var() references. Missing only minor operational details like auth, error, or return behavior keeps it from 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?

Despite covering a large surface, the description is a set of front-loaded, dense sentences: capabilities, partial-update rule, site-wide/page routing, and image-matching behavior. No filler or marketing language; every sentence carries operational content.

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

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

For a deeply nested 6-parameter tool, the definition is highly complete: schema property docs cover field formats, constraints, and pitfalls, while the description supplies the cross-cutting rules. The only real gap is the absence of any return/error/output contract, which matters somewhat since no output schema exists.

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 83%, so the schema already documents most parameters and the baseline is 3. The description adds meaningful usage semantics: only send changed fields, site-wide vs per-page routing, and always set both light and dark theme variants when matching an image. These go beyond what the schema alone provides.

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

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

States a specific action ('Update site settings') and enumerates the affected resource categories: SEO, site URL, JSON-LD, per-page overrides, theme tokens, fonts, dark mode, and custom CSS. It immediately draws the site-wide vs per-page distinction, which is the key ambiguity in this tool. No sibling tool overlaps this scope.

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

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

Explicitly instructs partial updates ('Provide ONLY the fields that change') and gives the routing rule: `general`/`seo` are site-wide, `page` is for one page. Schema descriptions reinforce this with 'Use this whenever you mean one page' and 'NEVER use it to build a repeated custom component'. This is near-explicit when/when-not guidance even though no sibling alternative tool is named.

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

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

With no annotations, the description carries the full burden and delivers: it discloses the file source (agent's filesystem), the return value (src), the storage location (project and export), and even SVG sanitization. This is comprehensive and exceeds typical transparency.

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?

Every sentence adds necessary information: action, uniqueness, filesystem source, and persistence. The description is front-loaded with the core purpose and remains informative without being verbose.

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

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

For a tool with two simple parameters and no output schema, the description is fully complete. It explains how to call it, what it returns, and what constraints exist, covering all that an agent needs to use it correctly.

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

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

Even though schema coverage is 100%, the description adds significant value: it requires an absolute path, lists allowed file types and size limits, and advises preferring SVG while noting sanitization. These details go well beyond the schema's own 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?

The description states a specific verb and resource ('Upload a local image file into the open site's asset library'), and it explicitly differentiates from siblings by declaring this is the ONLY way to get your own imagery, clearly distinguishing it from asset listing/deletion tools.

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

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

It provides explicit guidance on when to use the tool (to get your own imagery) and why it matters (empty src yields a stock photo), and it clarifies the file must come from the agent's own filesystem. It effectively communicates the primary use case without leaving alternatives ambiguous.

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