PageHub

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

Annotations already declare non-readOnly, non-idempotent, non-destructive. The description adds one meaningful behavioral constraint beyond that: 'The map holds only new nodes,' telling the agent this call will not update existing nodes and that get_block must be consulted for shapes. It does not cover failure behavior, id generation, or whether the operation is atomic for multi-node payloads.

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?

Purpose and scope are front-loaded, and the node-shape and reference lines earn their space. The node-shape sentence is a dense fragment dump that costs some readability, but there is no filler.

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

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

For a mutation tool with a nested object payload and no output schema, the description supplies the payload structure, the attachment semantics, the parent default, and pointers to get_block and get_style_reference. It stops short of describing the response or id handling, but an agent has enough 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 coverage is 100%, so the baseline is 3, but the description goes further by decoding the otherwise opaque `nodes` object (type.resolvedName, isCanvas, props, parent, nodes[], linkedNodes) and clarifying rootNodeId as 'the single top-level node in nodes to attach.' This is genuine added meaning over the schema's 'Flat map { nodeId: node }'.

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

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

States a specific verb and resource ('Build a section') plus the exact payload shape ('a flat map of new nodes plus the rootNodeId to attach under parentId'). The batch/section-building scope is clear, but it never contrasts itself with the sibling insert_node, so an agent must infer the boundary between the two node-creation 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 default way to design a section for this business' gives clear positive context and the 'Contract: get_style_reference({ topic: "editing" })' line establishes a concrete prerequisite. No explicit when-not guidance or named alternative (e.g. insert_node for single nodes) is provided.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutating, non-reversible-on-retry profile is covered. The description adds two things annotations cannot: the return contract (the pageId consumed by sibling tools) and the behavioral nuance that the first page is home — meaningful given there is no output schema.

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

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

Three dense sentences, front-loaded with the core action, with no filler. The phrasing "a type 'page' Container under ROOT" is slightly jargon-heavy, which costs a point against the cleanest possible front-loading.

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

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

For a 6-parameter, nested-object tool with no output schema, the description covers the domain placement, the return value, and the applicable SEO fields, plus a guide pointer. It leaves the non-SEO parameters (position, is404Page, isHomePage) to the schema, which documents them fully.

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

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

Schema description coverage is 100%, including the nested seo object, so the schema already carries the parameter semantics. The description's mention of seo.title and seo.description repeats schema-level detail rather than adding syntax, defaults, or interactions, so baseline 3 applies.

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

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

States a specific verb+resource ("Create a page") and then pins down the domain model: a type "page" Container under ROOT, with the first page becoming home. This lets an agent separate it from update_page, delete_page, and add_nodes without opening any schema.

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

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

Gives clear sequencing context by naming the consumers of the returned pageId (apply_kit_block, add_nodes) and routing to get_style_reference({ topic: "pages" }) for further guidance. It stops short of any explicit when-not-to-use or alternative-selection rule, so it is clear context rather than full routing.

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

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

Annotations already declare destructiveHint=true and non-idempotent; the description adds real context beyond that by disclosing that target 'header'/'footer' REPLACES the site header/footer, and that contentOverrides sets final copy in the same call. It stops short of stating reversibility or required permissions, so not a 5.

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

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

Front-loaded with the core action and mode selection, then constraints, then alternatives and guide link. Dense but each clause carries information; only slightly long.

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 9-param, destructive, no-output-schema tool, it covers the critical decision points (which mode, header/footer replacement, copy overrides, alternative tool, guide). Missing only return/result behavior and permission requirements, which are secondary.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: the 'exactly one' rule for slug/sourceNodeId, the header/footer replacement semantics, and that contentOverrides is keyed by the block's lib_* ids. This goes beyond the raw schema descriptions.

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

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

States a specific verb ('Stamp a section as-is') and resource, and enumerates the two mutually exclusive modes (library `slug` vs clone of `sourceNodeId`). It clearly distinguishes itself from the sibling add_nodes, so an agent can tell what this does without opening the schema.

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

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

Explicitly frames the tool as 'a shortcut for when an existing pattern genuinely fits' and names the alternative path ('to design a section for this business, use add_nodes with get_block as reference'). It also points to a guide via get_style_reference, covering when and when-not.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value on the read side by disclosing the return shape ('violations by severity with node ids'), which matters given there is no output schema. It stops short of noting scope limits or runtime cost.

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

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

Two compact sentences with zero filler; the core purpose is front-loaded and the return information follows immediately. Every clause carries information.

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

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

With no output schema, the description usefully compensates by describing the violation output and its ordering. Combined with a fully documented 4-parameter schema, an agent has what it needs, though prerequisites such as whether the page must be published are unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents id, level (with default AA), pageId (default page_home), and templateSlug. The description's 'site or template page' phrasing merely echoes the schema's mutual-exclusion note and adds no format or semantic detail beyond 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?

States a specific verb and resource ('WCAG audit of a site or template page') and enumerates the checks performed (contrast, alt text, headings, ARIA, interactive elements), which clearly separates it from the sibling audit_seo. An agent can identify and distinguish it without opening the schema.

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

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

Usage is implied: run this to check accessibility for either a site or a template page, and the schema's id/templateSlug notes encode the mutual exclusion. However, the description never states when to prefer this over audit_seo or any prerequisite (e.g. published vs draft page).

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. On top of that the description discloses the return shape ('Returns fixes with node ids'), which matters because no output schema exists. It could still say whether the audit is static or fetches live pages, but the added return-value context is real value beyond the annotations.

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

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

One sentence, front-loaded with the action and scope, then the checked dimensions and the return contract. No filler and nothing repeated.

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

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

With no output schema, the description usefully notes that fixes with node ids are returned, and the read-only annotations cover side-effect behavior. It is complete enough to invoke correctly, though it omits output format detail (e.g., severity, pagination) that might matter for a broad audit.

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

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

Schema description coverage is 100%, so the schema already explains id, pageId and templateSlug, including the 'Not with templateSlug' exclusion. The description only restates that a site or template can be targeted, adding no syntax or default details beyond the structured fields. Baseline 3 applies.

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

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

Specific verb ('Score') plus resource ('a site or template page') plus an enumerated list of what is scored (meta, heading hierarchy, alt text, link text, content depth). This clearly separates it from the sibling audit_accessibility, which the agent can infer covers a different concern.

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 'a site or template page' implies the two usage modes (id vs templateSlug), but the description never states when to choose a template audit over a site audit, nor does it name or exclude the related audit_accessibility sibling. Usage must be inferred from the schema constraints rather than the prose.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so "changes nothing" is largely redundant. The description does add real value beyond the annotations, though: it discloses that both apex and www are checked and that the response reports free/attached/erroring state plus required DNS records.

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

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

A single sentence with zero filler; the core verb and scope are front-loaded and the non-mutating guarantee is tacked on efficiently at the end.

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

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

With no output schema, the description carries the return-value burden and does so (free/attached/erroring, DNS records to add). Combined with annotations covering the safety profile, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description clarifies that the domain argument is a "candidate" (not the attached) domain but adds no syntax or format beyond the schema, so baseline 3 applies.

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

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

"Preflight a candidate domain (apex + www)" gives a specific verb-like action, a precise resource scope, and the outcomes checked (free/attached/erroring). It clearly reads as a non-mutating inspection, but it never names the closest sibling (get_domain_status) so the agent must infer the distinction itself.

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

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

"Preflight a candidate domain" and "Changes nothing" place it squarely in the pre-set_domain validation slot, giving clear usage context. However it names no exclusion or alternative, so an agent choosing between this and get_domain_status gets no explicit routing rule.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so safety is covered structurally. The description adds real value beyond them by naming exactly what is destroyed (both apex and www variants detached from Vercel) and the side effect of resetting redirectMode to none, though it says nothing about permissions or downstream propagation.

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

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

Two sentences, zero filler, with the primary action front-loaded and the side effects second. Every clause earns its place.

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

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

For a single-parameter mutation with no output schema, the description covers what is removed and what changes on the backend, which is what an agent needs to call it correctly. Return behavior and whether the change is reversible are left unstated.

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

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

Only one parameter, and schema description coverage is 100% ('Site id.'), so the schema already documents it fully. The description adds nothing about the id beyond implying it targets the active site; baseline 3 applies.

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

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

States a specific verb and resource (remove the custom domain from the active site) and the exact scope (apex and www variants, Vercel). An agent can distinguish it from set_domain, check_domain, get_domain_status and set_domain_redirect_mode without opening any schema.

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

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

The scenario is unambiguous: this is the teardown counterpart to set_domain, and 'from the active site' anchors it to the currently selected site. No explicit exclusions or named alternatives are given, so it stops short of a 5.

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

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

Annotations already declare this as a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds real context — 'Plan-gated' signals a permission/plan prerequisite. It does not disclose failure behavior (e.g., slug collision) or what a successful creation returns.

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

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

Front-loaded with purpose, then dense supporting detail in two compact sentences with no filler. The nested-field shape and type list earn their place, though the terse enumeration style borders on cryptic.

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

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

No output schema and no return-value description, so an agent must infer that a collection is returned. The nested `schema` object is well covered, but slug-uniqueness/error behavior and post-creation lifecycle are omitted for a nested-object creation 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?

Top-level schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it specifies the shape of each item in the `schema` array (key, label, type, required, default, help) and enumerates the allowed field types, none of which the schema supplies since items are an untyped object.

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?

Clear specific verb+resource ('Create a collection'), which an agent can distinguish from row-level siblings like create_collection_row. However it never names or differentiates against sibling tools directly, so sibling routing is left to inference.

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

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

No explicit when-to-use or when-not guidance. 'Plan-gated' and 'Source defaults to manual' hint at prerequisites and a default path, but there is no statement of alternatives (e.g., update_collection_schema once a collection exists) or conditions for choosing them.

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

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

Annotations declare readOnly=false, destructive=false, and idempotent=false, so the safety profile is partly covered. The description adds meaningful context beyond them: 'validated against the schema' and especially 'Plan-gated,' which signals a non-obvious precondition the annotations don't convey.

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

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

Three tight fragments, front-loaded with the core action, and every clause carries information (validation, plan-gating). No filler, though the fragmentary style is terse enough that structure is minimal.

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

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

For a 3-param mutation with a nested object and no output schema, the description covers the essentials and flags plan-gating, but omits what a successful create returns, how validation failures surface, and any required site/collection selection context. Minimum viable.

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, making the baseline 3. The description restates that `data` maps field key → value and adds the validation note, but adds little syntax or format detail beyond the schema.

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

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

States a specific verb (Create) and resource (one row), which distinguishes it from the bulk sibling create_collection_rows and from update_collection_row. It doesn't name the sibling explicitly, but 'one row' clearly implies singular creation, so it's clear though not fully differentiated in prose.

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

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

Usage is implied by 'Create one row' versus the plural create_collection_rows sibling, but there's no explicit when-to-use guidance, no prerequisite for selecting a site/collection first, and no routing to alternatives. Adequate but leaves inference to the agent.

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

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

Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false); the description adds non-obvious behavior the annotations can't express: all-or-nothing atomic validation, errors that name the failing rowIndex, a 500-row cap, and a plan-gated prerequisite. This is exactly the context an agent needs before committing a bulk write.

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

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

Three telegraphic clauses, front-loaded with the operation and its limits; the sibling pointer is placed last where it belongs. No filler or restatement of the title.

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

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

For a mutation tool whose safety profile is covered by annotations, the description supplies atomicity, limits, error shape, plan gating, and an alternative route. The only real omission is any hint of the success response, which is minor given no output schema is required to be explained.

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

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

Schema coverage is 100%, so the schema already documents slug, rows, and id; baseline would be 3. The description goes slightly beyond by clarifying that each row object is a field key → value map and by restating the 500 max on rows, which helps the agent build the payload correctly.

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

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

States a specific verb and resource (insert rows into a collection) plus scope (up to 500, one call), and implicitly distinguishes itself from the single-row sibling create_collection_row by stating batch capacity. An agent can identify the tool from the first clause alone.

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

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

Routes the agent explicitly to import_collection_csv when the payload is a big CSV, and the 500-row ceiling implies the threshold for switching. It does not state a negative condition beyond that (e.g., use create_collection_row for a single row), but the batch-size cue covers the main routing decision.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds meaningful context beyond annotations: it returns the site id (the id output matters for the following steps) and clarifies that no node map is provided, so the site is populated afterward. That sequencing info is genuinely useful.

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

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

Two tight sentences front-loaded with the core action and default template, plus an important behavioral note. No wasted words.

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 create tool with no output schema, the description covers the essentials: return value (id) and the workflow (no node map, build afterward). It could mention the template requirement or prerequisites, but the coverage is solid.

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

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

Schema description coverage is 100%, so the schema already documents all four params (name, title, template, description). The description only echoes the template default, adding little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Create) and resource (site) from a template, and notes the default template. It doesn't explicitly distinguish itself from sibling creation tools like duplicate_site or pull_template, but the resource and mechanism are clear.

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

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

Implies usage ('create a site from a template') but gives no explicit when-to-use vs. alternatives such as duplicate_site. The note that the site is built up afterwards is contextual guidance but not a when/when-not directive.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description does add real value beyond the annotations by disclosing the cascade scope ('all its rows') and irreversibility ('No undo'), but says nothing about permissions or what the response reports.

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

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

Two brief sentences, with the destructive scope front-loaded ahead of the irreversibility warning. Nothing is wasted.

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

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

There is no output schema, but for a destructive delete the essential facts – cascade scope and no-undo – are present. Missing detail on permissions and result reporting is minor.

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 'id' and 'slug' are documented in the schema. The description mentions the collection but adds no format, scoping, or precedence guidance (e.g., whether slug or id wins), so the baseline 3 is appropriate.

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

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

States a specific verb (delete) and resource (collection), and the phrase 'and all its rows' pins down the cascade scope that separates it from delete_collection_row. It stops short of naming that sibling, so an agent must infer the contrast.

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 warns 'No undo' but never says when to use this versus delete_collection_row, update_collection_schema, or other collection tools. There is no explicit alternative routing or prerequisite (e.g., permission or site-scoping) guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no mention of irreversibility, permission requirements, or behavior when the rowId does not exist. With annotations doing all the work, the description contributes essentially no additional 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?

A single front-loaded sentence with no filler or repetition. It is efficient, though arguably too terse for a destructive operation.

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

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

For a destructive single-row delete with complete schema coverage and annotations covering the safety profile, this is minimally adequate. It omits any confirmation semantics or failure behavior, but with no output schema there is no return-value burden.

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

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

Schema description coverage is 100%, with each parameter (id, slug, rowId) documented in the schema itself. The description only restates that rowId selects the row, adding no format or constraint detail beyond the schema. Baseline 3 applies when the schema carries the load.

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

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

The description names a specific verb (Delete), resource (row), and scope (one row from a collection) identified by rowId. It implicitly distinguishes itself from delete_collection (whole collection) but does not name any sibling explicitly.

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

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

No guidance on when to use this versus delete_collection, delete_node, or delete_page, and no prerequisites or warnings. The agent must infer usage entirely from the name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds non-obvious behavior beyond that: the deletion is cascading ('and its subtree') and four protected sentinel nodes are rejected. It doesn't mention permission requirements or irreversibility, but the cascade and protected-node rules are meaningful additions.

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

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

Two sentences, zero filler, and the core action is front-loaded ahead of the constraint. Every clause earns its place.

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

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

For a destructive mutation with a fully documented schema and annotations carrying the safety hints, the description covers the two things an agent most needs: that it cascades and which nodes are protected. No output schema exists, so nothing about returns is owed, but permission/auth prerequisites are left unstated.

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

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

Schema description coverage is 100%, and the schema already documents both id and nodeId, including the source hint (list_site_nodes / search_site_nodes). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (node) plus the important scope detail that the entire subtree goes with it. The resource 'node' is distinct from sibling delete operations (delete_page, delete_site, delete_collection), so an agent can route correctly.

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

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

Provides explicit exclusions — ROOT, page_home, hdr_root and ftr_root cannot be deleted — which is real when-not guidance. It stops short of stating when to prefer this over siblings like delete_page or move_node, so it is clear context without full alternative routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description goes beyond that with genuinely non-obvious behavior: the last page is undeletable and deleting the home page promotes the next one. It still omits recoverability and permission requirements, but the added rules are real value.

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

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

Two short sentences, zero filler, with the primary action stated first and the edge cases immediately after. Every clause earns its place.

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

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

For a destructive tool with no output schema, the description covers the cascade (content is deleted) and the two surprising edge cases an agent must not discover by accident. Missing only permission/authorization expectations and irreversibility, which would make it fully self-contained.

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

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

Schema description coverage is 100% and both parameters (id, pageId) are documented with examples in the schema, so the baseline is 3. The description adds nothing about the site-id vs page-id distinction or how the pair is interpreted.

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

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

States a specific verb + resource ("Delete a page") and clarifies scope by noting it removes the page's content too, which distinguishes it from delete_node, delete_collection, and delete_site. It stops short of explicitly naming a sibling, but the resource is unambiguous enough that an agent can route correctly.

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

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

Usage is implied by the obvious delete-a-page semantics, with no explicit statement of when to prefer delete_node or update_page alternatives. The two business rules given are constraints rather than selection guidance, and no prerequisites (permissions, auth) are mentioned.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description only adds 'Requires an explicit id,' which is a restatement of the required field rather than new behavioral context such as permanence, cascade effects, or auth requirements.

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

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

Two short sentences with the action front-loaded and no wasted prose. The second sentence is mildly redundant given the schema marks id as required, keeping it just below a perfect score.

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

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

For a single-parameter, no-output-schema tool whose annotations carry the destructive and idempotent profile, the description is minimally sufficient. It omits any note on irreversibility or side effects, which would be valuable for a destructive 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 single 'id' parameter is already fully documented as 'Site id to delete.' The description's 'Requires an explicit id' adds no syntax, format, or constraint detail beyond the schema, matching the baseline 3.

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

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

States a specific verb and resource ('Delete a site'), which is unambiguous and distinguishable from sibling mutations like delete_page or delete_collection by the resource noun alone. It does not explicitly contrast with those siblings, but the target resource is clear.

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

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

There is no guidance on when to use this tool versus alternatives such as delete_page, unpublish_site, or duplicate_site, and no mention of prerequisites (permissions, confirmation, or irreversibility handling). Usage must be inferred entirely from the name.

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

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

Goes well beyond the annotations by enumerating exactly what is copied (content, title, description, portal, crawlPolicy) and what is not (domain, published state), plus the resulting state ('becomes active'). This is the kind of behavioral detail an agent needs before mutating state.

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 tightly packed sentences with no filler; the copy scope and the not-copied caveats are front-loaded and immediately 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 mutation tool with no output schema, annotations already cover the safety profile and the description covers copy semantics thoroughly. The remaining gap is the absence of any note on the all-optional schema, where duplication realistically requires the source id.

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 id/name/title/description. The description adds only that title and description function as overrides and lists copied fields, but does not explain the 'name' slug parameter or that id is practically required despite the schema marking nothing as required.

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

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

States a specific verb (copy) and resource (site), plus the precise scope: source must be a site you're a member of, destination is a new site you own. This clearly distinguishes it from create_site and pull_template among siblings.

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

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

Provides concrete pre-conditions ('a site you're a member of' into 'a new site you own') that tell the agent when this tool applies, but never names alternatives (create_site, pull_template) or exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the ranked ref format returned and the coverage limitation of the tb set for brand logos, which the annotations do not convey.

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

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

Two dense sentences with no filler, and the core behavior (search all sets, return ranked refs) is front-loaded before the caveat about Tabler and brand sets. Slightly telegraphic, but every clause carries information.

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

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

There is no output schema, so the description usefully explains the return format (`ref-icon:` refs and their consumers). For a simple read-only search tool with full schema coverage and clear annotations, this is nearly complete; only cross-tool routing guidance is missing.

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

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

Schema description coverage is 100%, so all four parameters (q, set, kind, limit) are already documented in the schema, including the kind enum and the limit default. The description's note that brands live in fa/si adds a little color for set/kind selection but no syntax or format beyond the schema, so the baseline 3 holds.

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 (Search) plus scope (every icon set) and specifies the return artifact (`ref-icon:<set>/<Name>` refs) and where they are used (Icon nodes, Button/Link icon.value). This clearly separates it from siblings like find_image and find_video.

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 implies set-selection guidance ('Tabler (tb) lacks many brand logos; brands come from fa / si / …'), which helps pick a set or the brand kind. However, it never states when to use this tool versus the obvious siblings (find_image, find_video) or any prerequisites, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral detail not in the annotations: the provider fallback order (local bank first, then external providers), which tells the agent results may come from different sources.

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

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

A single front-loaded sentence with zero filler; the parenthetical earns its place by conveying the provider fallback. Nothing is wasted.

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

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

With no output schema, the description carries the burden of explaining returns, and 'verified, ready-to-use URLs' only partially covers it — it does not say whether results are a list, what fields come back, or whether attribution/licensing applies to the stock providers. Adequate for a read-only lookup, but there are 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 q, count, category, provider, and orientation are already fully documented with enums and defaults. The description adds no additional parameter semantics beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific resource (stock photos with ready-to-use URLs) and implicitly distinguishes itself from siblings like find_icon, find_video, and upload_image by naming the medium. It does not name those siblings explicitly, so an agent must infer the boundary from the resource type alone.

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

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

Usage is only implied: the mention of 'local bank, then Unsplash/Pexels' hints at a provider fallback, but there is no explicit when-to-use guidance versus find_icon/find_video or upload_image. Nothing tells the agent when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety and network profile are covered. The description adds that results are Pexels stock videos with direct MP4 URLs, which is modest additional context. It does not describe return shape, pagination, rate limits, or whether results are cached.

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

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

It is a single compact sentence with no filler, and the key differentiator (direct MP4 URLs from Pexels) is front-loaded. Every clause earns its place.

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

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

For a read-only lookup tool with a fully described schema and safety annotations, the description is minimally adequate. However, it stops short of explaining what a caller receives (MP4 URLs to attach to Video nodes) or how to use the results, leaving a gap for an agent that needs to wire the output into add_nodes or insert_node.

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

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

Schema description coverage is 100%, so every parameter (q, count, provider, maxDuration, minDuration, orientation) is already documented in the schema. The description adds no parameter syntax or defaults beyond what is already present, so the baseline 3 applies.

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

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

The description names the resource ('Stock videos') and adds useful specifics (direct MP4 URLs, Pexels source, intended for Video nodes), but the verb is implied rather than stated — it never says 'find' or 'search'. Sibling tools find_image and find_icon exist, so a clearer distinction between these 'find_*' tools would help, and those aren't referenced.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The phrase 'for Video nodes' implies a context, but there is no statement of when this tool should be chosen over find_image, find_icon, or upload_file. No exclusions or constraints on usage are provided.

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

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

Annotations already declare this as a readOnly, non-destructive, closed-world generation tool, so the safety profile is covered. The description adds that the output is a foundation to which classes can be appended, which is useful context but not rich behavioral detail (e.g., determinism, defaults).

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

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

Two short sentences with no waste; the return artifacts are front-loaded before the usage caveat. Every clause earns its place.

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

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

There is no output schema, so the description helpfully names what is returned (className + activeModifiers), and annotations cover the safety profile. Complete enough for an 8-param, all-optional generation tool, though the relationship to validate_button_classes is left unstated.

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

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

Schema description coverage is 100% and every parameter already documents its own defaults and example values, so the schema does the heavy lifting. The description merely echoes variant/shape/size without adding syntax or meaning beyond the schema.

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

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

States a specific verb (generate) and resource (Button className + activeModifiers) plus the inputs that drive it (variant, shape, size). It clearly identifies the tool as a class-string generator, though it does not explicitly distinguish itself from the sibling validate_button_classes.

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?

"A starting point; extra classes can be appended" implies a workflow context, but there is no explicit when-to-use guidance or mention of the alternative validate_button_classes. Usage is only weakly implied.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, not open-world). The description adds meaningful context beyond them: 'Counts as a use,' which discloses a quota/billing side effect an agent should know about.

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

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

A single tight sentence with the core purpose front-loaded and no wasted words. Both clauses earn their 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 simple single-param read tool with full schema coverage and annotations, this is nearly complete; 'full tree' hints at the return shape despite no output schema. Minor gap: no mention of error behavior for unknown slugs.

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% for the single slug parameter, so the schema does the documenting. The description only restates 'by slug' without adding format or constraint detail. Baseline 3 applies.

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

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

States a specific verb (Get) and resource (a library block's full tree) scoped by slug, clearly distinguishing it from siblings like list_blocks, search_blocks, and list_block_nodes. An agent can tell what it returns without opening the schema.

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

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

The phrase 'reference for hand-building with add_nodes' gives a concrete use context, linking it to the add_nodes sibling. It doesn't explicitly state when NOT to use it (e.g., vs list_block_nodes or search_blocks), so it falls short of a 5.

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

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

Annotations already declare the safe read-only, non-destructive, closed-world profile, so the safety burden is covered. The description adds useful context by naming what is returned (schema fields, source, isPublic), but says nothing about behavior on a missing/invalid slug or scope resolution between id and slug.

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

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

A single tight sentence with the verb and resource front-loaded and zero filler. Every clause earns its place.

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

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

For a simple read tool whose annotations carry the safety profile and whose parameters are fully documented, the definition is nearly complete, and it compensates for the absent output schema by naming the returned fields. It would be complete with a note on scope resolution or error behavior.

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

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

Schema description coverage is 100%, so both parameters are already documented with maxLength and descriptions in the schema. The description adds no format or resolution details beyond what the schema provides, giving the baseline 3.

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

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

States a specific verb ("Read") and resource ("one collection's definition") and enumerates the content (schema fields, source, isPublic). "One" distinguishes it from the sibling list_collections, though it never names that sibling explicitly.

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

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

No explicit when-to-use guidance, no prerequisites, and no alternative named. An agent must infer from "one" versus the plural list_collections and update_collection_schema siblings on its own.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds a real behavioral trait beyond that — responses become compact in parallel fill and the optional parameter becomes required — which is useful context. However, 'parallel fill' is unexplained jargon, so the disclosure is only partially actionable.

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

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

Three tight sentences with no filler, and the core capability is front-loaded before the parameter notes. The only cost is the undefined 'parallel fill' term, which a reader must decode.

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 read tool with no output schema, the description usefully sketches the return shape (types, props, valid values). It still leaves the 'parallel fill' mode and the resulting compact response format unexplained, which is the one piece of behavior an agent would need to interpret results correctly.

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

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

Schema description coverage is 100% and the schema already explains comma-separated names and 'omit for all'. The description goes further by stating that a comma list acts as a filter and that components becomes mandatory in parallel fill mode — semantics not present in the schema, which lists zero required parameters.

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

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

States a specific resource and payload: full prop schemas for components, including types, props, and valid values. That distinguishes it from sibling getters like get_block or get_style_reference, though it never names those alternatives explicitly.

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

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

Gives a conditional usage note ('a comma list returns only those components', 'in parallel fill ... components is required'), which implies when the parameter matters. But it never says when to call this tool versus get_block/get_style_reference, and the 'parallel fill' context is left undefined for an agent that has no such concept.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is largely covered. The description still adds real context by disclosing what the read returns and explicitly reassuring that `check` makes no changes, which reinforces rather than contradicts the annotations.

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

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

Two tight sentences: the primary read behavior and its output are front-loaded, and the secondary `check` mode follows. No filler or restated title text.

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

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

With no output schema, the description carries the burden of describing return content and does so by listing the domain facets returned. Combined with the annotation-covered safety profile, an agent has enough to call it correctly; only the sibling relationship to check_domain remains unaddressed.

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

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

Schema coverage is 100%, so both parameters are documented in the schema (id = site id, check = candidate domain). The description slightly enriches `check` by framing it as a non-mutating preflight, but adds no format or constraint detail beyond that, matching the baseline for fully-covered schemas.

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

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

The description names a specific verb (Read) and resource (the site's custom domain) and enumerates the returned facets: redirect mode, apex/www Vercel state, and required DNS records. It does not, however, name the very similar sibling check_domain, leaving the agent to disambiguate from the name alone.

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

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

It explains the `check` mode as a change-free preflight, which is genuine usage guidance for that parameter. But it never states when to call this instead of check_domain, set_domain, or set_domain_redirect_mode, so the selection logic against alternatives is only implied.

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

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

Annotations already declare readOnly/destructive=false and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: state-conditional output ('When status is ready it includes the new site id, editor link and preview link'), which is the kind of detail annotations cannot express.

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

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

Two tight sentences, front-loaded with the core purpose and followed by the return contents. 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?

No output schema exists, so the description carries the burden of describing returns — and it does comprehensively (status, counts, warnings, redirects, plus the ready-state fields). Nothing needed to call or interpret this tool is missing.

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

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

Schema coverage is 100% and the single importId parameter is already documented ('From import_site.'). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (returns the progress/status of an import_site run) and enumerates what it reports: status, page/media counts, warnings, redirects. An agent can immediately distinguish it from the write-side sibling import_site.

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

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

The phrase 'Progress of an import_site run' and the param note 'From import_site' clearly establish the context: call this after import_site to track a run. No explicit exclusions or polling guidance are given, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description only adds the 'current configuration' framing and nothing about permissions or return shape, which is a modest addition over what the annotations say.

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

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

One short, front-loaded sentence with zero filler. It is appropriately sized for a simple lookup, though the single sentence leaves no room for the disambiguation the sibling set invites.

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

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

For a read-only one-parameter lookup with annotations covering safety, the description is broadly adequate. However, with no output schema, it does not characterize what 'portal configuration' contains, leaving the agent guessing at the return payload.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented as 'Site id.', so the schema carries the parameter semantics. The description adds no format, sourcing, or default behavior beyond that.

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 ('Fetch') and resource ('current portal configuration for a site'), so the agent can distinguish it from set_portal and remove_portal by verb alone. It does not explicitly name those siblings or the disambiguation condition, keeping it short of a 5.

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

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

Usage is implied: read the portal configuration when you need its current state, versus set_portal to change it or remove_portal to delete it. No explicit when-to-use, preconditions, or alternative is stated, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint/destructiveHint=false/openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them: that missing AI credits cause the chat bubble to be hidden, and that it exposes owner instructions and lead routing. It stops short of describing permissions or response shape.

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

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

A single front-loaded sentence with the core action first and the field list after the colon. The list is somewhat enumerative but every item is informative, so it earns its length.

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

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

With no output schema, the description usefully compensates by enumerating what is read (on/off, name, greeting, instructions, lead capture, destination, credits). Nothing critical for correct invocation is missing, though permissions or error behavior are unaddressed.

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

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

Schema coverage is 100% and there is a single id parameter documented as 'Site id.', so the schema carries the parameter burden. The description only refers to 'the site's' settings, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Read) and resource (the site's chat bot settings) and then enumerates the concrete fields returned. It is trivially distinguishable from the sibling set_site_chat (write counterpart) without opening a schema.

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

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

The read semantics are implied by 'Read' and reinforced by readOnlyHint, but there is no explicit when-to-use guidance and the sibling set_site_chat is never named as the alternative for modification. Usage is inferable 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?

Annotations already declare readOnlyHint, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful content context (only Container/Text/Button/Image/EmailSlot and email-safe classes, no btn/card/shadow/gradient/absolute), but says nothing about errors, auth, or what happens if a slot is duplicated or missing.

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 the core action front-loaded and the structural constraints packed into the second. Dense but each clause carries real information; the parenthetical constraint is slightly awkward but earns its place.

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

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

With no output schema, the description carries the return-value burden and does list the returned elements plus the allowed node/class vocabulary. It stops short of explaining how the node tree is addressed for later edits, which a caller of add_nodes/update_site_email would likely need.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (including the 8-value kind enum sourced from list_site_emails). The description adds no format or constraint detail for id/kind, so the baseline 3 applies.

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

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

Starts with a specific verb+resource ('Read one site email') and enumerates the payload it returns (subject, preheader, node tree, variables, EmailSlot nodes), which clearly separates it from list_site_emails, preview_site_email, and update_site_email.

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

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

It gives an operational constraint ('keep required slots exactly once') but never states when to choose this over preview_site_email or update_site_email, nor the prerequisite 'id from list_site_emails' workflow end-to-end. Usage is implied by the word 'Read' rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the return is 'raw JSON' and frames the result as a value to merge, which is mild extra context, but it discloses nothing about error behavior for missing nodes or the shape of the returned JSON.

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

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

Two short sentences, front-loaded with the core action, with no filler words. However, the second sentence is jargon-dense and grammatically compressed ('propsPatch replaces string props whole'), which costs some readability without adding 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 read tool whose annotations fully cover safety and whose schema fully documents both parameters, the description is close to adequate. It is still incomplete on what a node's raw JSON looks like and what happens on an unknown nodeId, and with no output schema the description is the only place that could have hinted at the return shape.

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

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

Schema description coverage is 100% with only two parameters (id, nodeId), and the schema already supplies examples like ROOT and page_home. The description adds no parameter-level meaning such as which identifiers are valid or how nodeId relates to the site id, so baseline 3 applies.

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

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

States a specific verb+resource: 'Read one node's raw JSON.' The word 'one' implicitly distinguishes it from list_site_nodes and search_site_nodes in the sibling set, but it never names those siblings, so the differentiation is left to inference.

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

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

The second sentence hints at the use case (fetching the current value to merge before patching props), which implies a workflow with patch_site_node, but it never states when to use this tool versus list_site_nodes/search_site_nodes, and the phrasing 'so this is the current value to merge into' is elliptical enough that an agent must decode it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the content inventory of the reference (tokens, modifiers, interactive state, form-confirmation recipe), which is useful context, but says nothing about auth, response size, or whether topics override the core reference beyond a hint.

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

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

Two sentences, front-loaded with the content inventory followed by the parameter guidance. No filler, though the topic list in parentheses is somewhat loose against the actual enum and could have been omitted as redundant with the schema.

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

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

For a read-only, single-optional-parameter reference tool with no output schema and full annotation coverage, the description supplies enough — what the reference contains and what a topic yields. It could go slightly further on how topics relate to the core reference, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the single enum is fully documented, so the baseline is 3. The description restates the parameter's effect and names a few topics (design bar, accessibility, domains, per-tool usage), but these only partially map to the 12 enum values and add little 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 names a specific resource (styling reference) and enumerates its contents — palette variables, styleGuide tokens, spatial scale, modifiers, interactive state, form-confirmation recipe — so an agent knows what it retrieves. It does not, however, distinguish itself from adjacent siblings like suggest_palettes, suggest_font_pairings, or get_component_schema, which also relate to styling.

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 second sentence explains the `topic` parameter's effect (a focused guide vs the core reference) and hints at guide categories, which implies usage. But there is no explicit when-to-use guidance, no statement of when to prefer this over suggest_palettes or get_component_schema, and no prerequisites.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral facts: replace deletes existing rows first, upsert keys off an externalId/id column, unmatched columns are silently ignored, there is an ~8MB cap, and the tool is plan-gated. It does not disclose the response shape or whether the import runs asynchronously.

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

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

A single dense sentence pair, front-loaded with the core action and then the mode contract. Nearly every clause carries information, though 'CSV text' and the restated default slightly overlap with the schema.

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

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

For a destructive, plan-gated bulk mutation with no output schema, the description covers caps, mode behavior, and column handling well. It omits how failures/partial imports behave and, notably, never mentions async execution or status polling despite a get_import_status sibling existing, leaving a real gap 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%, so the baseline is 3, but the description meaningfully enriches two parameters the schema describes only tersely: it explains the CSV header/field-key contract for `csv` and gives the actual merge semantics (and upsert key) behind the `mode` enum, which the schema's 'Merge mode. Default append.' does not convey.

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

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

States a specific verb (import) and resource (CSV rows into a collection, implied by the slug param and title). It distinguishes itself reasonably from create_collection_rows and import_site by naming the CSV format and the header-to-field-key matching rule, though it never explicitly says 'into a collection' in the body.

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 mode breakdown gives clear conditions for append vs replace vs upsert, which is real guidance on how to invoke it. However, it offers no when-to-use-this-vs-alternatives routing (e.g. vs create_collection_rows for small batches or import_site for whole sites), and no prerequisites beyond the plan gate.

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

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

Annotations cover safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true). Description adds valuable workflow behavior: the size→upload URL→PUT→uploadKey sequence, the 3MB inline-file cap, and that it returns an importId for get_import_status. This is real context beyond annotations.

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

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

Dense but earns its place; front-loads the purpose, then enumerates the three input modes compactly. Slightly telegraphic but no wasted sentences.

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

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

No output schema, but the description names the returned importId and points to get_import_status. Covers the staged upload mechanics and constraints well; minor gaps on error handling or cleanup of stale uploads.

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

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

Schema coverage is 100%, so the schema already documents name, size, files, and uploadKey. Description restates the size/uploadKey linkage but adds little syntax detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: turning a static HTML site into a NEW editable multi-page draft. Explicitly distinguishes from create_site (which builds a new site from scratch) and upload_image by scoping to full HTML-site import.

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?

Explains the multi-step workflow clearly (filePath / size→upload URL / uploadKey / files) and notes 'local server only' constraint. Does not explicitly exclude alternative tools or state when NOT to use it, but the staged flow gives strong context.

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

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

Annotations establish a non-destructive, non-idempotent write. The description adds a genuine behavioral fact beyond them: parent and linkedNodes are populated automatically, so the caller need not supply them. It says nothing about duplicate-id handling or failure modes.

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 purpose is front-loaded in the first clause, then the node shape follows. It is dense but every sentence carries information; the trailing lists/tables note is somewhat compressible but earns its place as a usage example.

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

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

For a mutation tool with a nested free-form object and no output schema, the description covers the node shape and auto-set fields, which is the main need. It stops short on lifecycle concerns (id collisions, ordering effects) and enumerates only a couple of the many node types an agent might need.

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

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

Schema coverage is 100%, so the baseline is 3, but the description does real work here by spelling out the otherwise opaque shape of the `node` object (type.resolvedName, isCanvas, props, nodes) that the schema only gestures at. It also illustrates list/table Containers, adding meaning the schema does not carry.

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

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

States a specific verb and resource ('Insert one node under an existing parent'), and the singular scope is clear. It does not explicitly distinguish itself from the sibling add_nodes, so an agent must infer the singular/plural split rather than being told.

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

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

No when-to-use or when-not-to-use guidance is given. The only routing is an incidental pointer to get_style_reference for modifier setup; alternatives such as add_nodes or move_node are never mentioned, leaving selection to inference.

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

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

Annotations already declare it is a non-read-only, non-destructive, open-world write; the description adds genuinely new behavioral context on top: the owner-only authorization requirement and that re-inviting an existing address merely refreshes the invite link rather than erroring. It still does not say whether an email is dispatched or what happens to the previous link's validity window.

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

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

Three compact sentences with zero filler; the operation, the role options and the re-invite caveat are all front-loaded where an agent will see them first.

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

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

For a three-parameter mutation with full annotation coverage and no output schema, the description covers operation, authorization, defaults and the re-invite edge case. Minor gaps remain around notification behavior and the resulting invite state, but nothing blocks a correct call.

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

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

Schema description coverage is 100%, so the schema already documents id, role (with enum) and email. The description's role list and default duplicate the enum/default already encoded in the schema, adding no syntax or format detail beyond 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?

States a specific verb and resource ('Invite someone to a site by email') plus the full role set, which makes it easy to separate from revoke_site_invite and list_site_members. It never names an alternative tool explicitly, so it stops short of the top-bar sibling differentiation.

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

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

'Owner-only' gives the permission prerequisite for calling it, and '(default)' tells the agent what happens when role is omitted. It does not state when *not* to use it (e.g. use revoke_site_invite to undo) or what happens if the person is already a member.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered structurally. The description adds a behavioral trait not present in annotations: 'Counts as a use,' a quota/billing consequence that is genuinely useful for an agent deciding whether to call 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?

One sentence plus a short trailing clause; the resource and its purpose are front-loaded, and the quota note is kept to three words. No wasted prose.

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

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

With no output schema, the description carries the burden of describing returns and does so (node ids and displayNames). It is complete enough to invoke correctly, though it doesn't state whether all nodes are returned or mention any size/pagination limit.

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

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

Schema coverage is 100% and the single slug parameter is documented in the schema, so the baseline is 3. The description only implies the slug refers to a library block (via 'a library block's node ids') and adds no format or syntax detail beyond the schema.

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

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

States a specific verb (List) and resource (a library block's node ids and displayNames), and names the concrete artifact returned (lib_* keys). It also distinguishes itself from the sibling list_blocks by scoping to a single block's nodes and tying the output to apply_kit_block's override keys.

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 frames the output's purpose — the keys feed apply_kit_block's contentOverrides/propOverrides — which tells the agent when this tool is needed. It does not explicitly say 'call this before apply_kit_block' or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Annotations already declare the safe read profile (readOnlyHint=true, destructive=false, openWorld=false), and the description adds real context beyond them: the ~200-result cap, category grouping, and the returned fields. It doesn't discuss pagination or ordering, but the cap implies a single bounded call, so the coverage is solid.

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?

Purpose is front-loaded in the first sentence, the sibling routing comes next, and the parameter nuance closes in a short clause. No filler, no repetition of what the schema already lists verbatim.

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

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

For a read-only, zero-required-parameter list tool with no output schema, the description covers result scope, grouping, fields, filter semantics, and the alternative tool. The only thin spot is ordering/pagination behavior, which the ~200 cap partially resolves.

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

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

With 100% schema coverage the baseline is 3, but the description adds meaning by stating that the `categories`/`styles` arrays OR-match in one call, clarifying the array-vs-single interaction the schema only implies ('merged with categories'). It stops short of explaining enum values, which the schema already enumerates.

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

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

States a specific verb and resource ('List library blocks'), gives the scope ('up to ~200'), the grouping ('by category'), and the returned fields ('slug, name, tags'). It explicitly contrasts with search_blocks ('A broad menu; search_blocks ranks and filters'), so an agent can distinguish it from its nearest sibling without opening either schema.

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

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

Names the alternative explicitly ('search_blocks ranks and filters') and frames this tool as the broad browsing menu, which tells the agent when to prefer it. It stops short of an explicit when-not clause or listing the other related siblings (get_block, list_block_nodes), so it's clear context rather than a complete routing rule.

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

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

Annotations already state readOnlyHint, openWorldHint:false, destructiveHint:false. The description adds pagination semantics (nextCursor, hasMore, totalCount) which tells the agent the operation is cursor-paginated and returns a total count - useful context beyond the annotations.

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

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

One compact sentence with the core behavior and return shape front-loaded. Could arguably include one clause about scope (per-site/per-collection), but it does not waste words.

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?

Read-only and no output schema, and annotations cover safety. However usage guidance relative to sibling listing tools is absent, and the relationship between collection rows and pagination cursor is only implied. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents id, slug, limit, and cursor including defaults and max. The description adds nothing param-specific, so baseline 3 is appropriate.

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

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

States the verb (page through) and resource (collection's rows), which is more specific than the title. However it does not distinguish itself from list_collections or get_collection, nor does it clarify the relationship to create_collection_rows/list_collections.

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 indication of when to use this versus list_collections, get_collection, or the sibling create/update row tools. The reader must infer that this is for paginated retrieval of rows within one collection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (id, name, slug, row and field counts, public flag) in the absence of an output schema, though it says nothing about pagination or ordering.

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

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

A single front-loaded sentence with zero filler; the verb and scope lead and the returned fields follow. Nothing could be trimmed without losing information.

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

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

For a simple read-only list tool with one optional param and annotations covering safety, the description supplies the one thing structured data does not: the returned field set. Complete enough to invoke correctly, with only minor gaps (ordering, pagination, zero-collection behavior).

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

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

There is one optional parameter ('id': 'Site id.') with 100% schema description coverage, so the schema already carries the meaning. The description confirms the listing is site-scoped but adds no format, default, or multi-site behavior detail beyond the schema.

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

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

States a specific verb (List) and resource (the site's collections) and even enumerates what the listing contains (id, name, slug, row/field counts, public flag). It is easy to distinguish from singular get_collection or row-level list_collection_rows, though the description never names those siblings explicitly.

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

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

Usage is only implied: 'the site's collections' suggests a whole-site enumeration rather than a single-collection fetch or a row listing. There is no explicit when-to-use statement, no mention of get_collection/list_collection_rows as alternatives, and no note that it is an overview call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds useful output context, notably the '★ = served' legend for interpreting versions, but says nothing about pagination, limits, or empty-result behavior.

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

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

One front-loaded sentence with no filler, compactly conveying scope and returned fields. The '★ = served' legend is terse but functional, slightly hurting readability without wasting space.

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

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

With no output schema, the description carries the return-value burden and does so by naming link, versions, download count and plan allowance. Combined with annotations covering the safety profile, this is nearly complete, though pagination and ordering remain unaddressed.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already fully documented in the schema. The description implies a site scope but adds no syntax, format, or defaulting detail beyond what the schema 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 identifies a specific resource ('Site's hosted downloads') and enumerates the fields it returns, which cleanly separates it from siblings like list_pages or list_collections. It lacks an explicit verb ('lists') and depends on the title for the action, but the intent is unambiguous.

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

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

There is no statement of when to use this tool, what prerequisites exist (e.g., a selected site), or when to prefer it over related tools such as set_download or remove_download. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the return-field inventory, but says nothing about pagination, ordering, or scope limits for a list operation.

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

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

Two short sentences with no filler, and the returned-field list is front-loaded. The second sentence is thin but functional rather than wasteful.

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

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

No output schema exists, so the description correctly compensates by naming the returned fields. With one fully documented parameter and annotations covering the safety profile, only the missing sibling differentiation and pagination behavior keep it from being 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?

There is one parameter with 100% schema description coverage ('Site id'), so the schema carries the burden. The description does not mention the site id at all, adding no meaning beyond the structured field; baseline 3 applies.

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

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

States a specific verb and resource ('List the site's pages') and enumerates the returned fields (node id, name, slug, home/404 flags), which is more than a restated title. It does not, however, distinguish itself from close siblings like list_site_nodes or get_site_node.

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

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

'Use it to get page ids' gives a use case but no when-to-use versus the many other list/get node tools in the sibling set. Usage is implied rather than scoped, leaving the agent to guess between list_pages, list_site_nodes, and get_site_node.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds the compact return mode, which is genuine behavioral context, but says nothing about volume of presets, ordering, or auth needs. Adequate but not rich for an annotation-backed read tool.

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

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

Three short telegraphic sentences with no filler, and the 'what it is' clause is front-loaded ahead of the compact detail and the follow-up tool. The fragment style is efficient but slightly cryptic in places.

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

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

There is no output schema, but the description signals the two possible return shapes (full preset vs id+name under compact) and points to the tool that consumes the output. For a zero-required-parameter read tool, that covers what an agent needs before calling.

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

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

Schema coverage is 100%, so all three parameters are already documented in detail. The description restates the compact behavior ('compact: true returns id + name only') rather than adding syntax or meaning beyond the schema, and the mood filter and brief alias go unmentioned. Baseline 3 applies.

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

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

States the resource precisely — 'Curated theme presets (palette + fonts + tokens)' — and the parenthetical clarifies what a preset actually contains, which distinguishes it from sibling suggest_palettes or list_templates. The listing verb comes from the name rather than the description, so it is clear but not fully self-contained.

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?

'set_theme({ preset }) applies one' gives a useful downstream workflow hint, telling the agent this is the discovery step in a list-then-apply chain. However it never contrasts with adjacent options like suggest_palettes or list_templates, and states no when-to-use condition explicitly.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false). The description adds real value beyond them by disclosing what the listing reports per email: whether it is customized or default, and whether it sends. It does not discuss pagination or ordering, but for a read-only list this is solid added 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?

One information-dense sentence plus a two-word routing cue. Nothing is wasted and the resource scope is front-loaded before the behavioral detail.

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

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

For a read-only, one-parameter list tool with no output schema, the description tells an agent what comes back and that it is the starting point. Only minor gaps remain, such as how 'whether each sends' is represented and whether results are scoped to the current site.

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

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

Schema coverage is 100% and the single 'id' parameter is documented there. The description adds nothing about the parameter, notably that it is optional and presumably defaults to the currently selected site. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb (List) and resource (the site's transactional emails) and enumerates the categories returned (receipt, welcome, gift card, sign-in link, downloads) plus the customized/default and sends dimensions. It only weakly distinguishes itself from the singular sibling get_site_email via the trailing 'Start here' rather than naming it.

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

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

'Start here' implies this is the entry point into the email workflow, presumably before get_site_email or update_site_email. However it never states when-not to use it or explicitly names the follow-up alternatives, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the meaningful 'Owner-only' authorization requirement on top. It also hints at the returned content (roles, pending invite ids), which partly compensates for the absent output schema, though it omits pagination or result-count behavior.

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

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

Two short sentences, zero filler, with the core 'what' front-loaded and the access constraint last. Every clause earns its place.

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

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

For a simple one-param read with no output schema, the description covers scope, returned data shape at a high level, and the owner restriction. Pagination or ordering behavior is unstated, which is a minor gap but not needed 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% and the single 'id' parameter is documented as 'Site id.', so the schema already carries the semantics. The description only implies site scoping and adds no format or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (list) and resource (site's members), and distinguishes its scope by adding pending invites, which separates it from sibling reads like list_sites or list_templates. An agent can tell it apart from invite_site_member/revoke_site_invite without opening a schema.

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

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

The 'Owner-only' clause gives a clear access precondition for when this call will succeed, which is real usage guidance. It doesn't explicitly name alternatives (e.g., invite_site_member to add members), but the read-vs-mutate split is clear from context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the response is a lightweight tree, DFS-ordered, roughly 2KB, and enumerates the returned fields — all of which help the agent judge cost and shape.

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

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

Two tight clauses: the output contract first, the use case second. No filler, no restating the title, and 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?

With no output schema, the description correctly carries the return-value burden by naming the fields, ordering and size. For a simple one-param read tool it is nearly complete; only the relationship to sibling node tools is unstated.

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

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

There is a single parameter (id) with 100% schema description coverage ("Site id."), so the schema fully documents it. The description adds nothing about the parameter, which is the expected baseline when the schema already does the work.

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 precisely what the tool returns — a lightweight node tree with the exact fields (id, displayName, type, child count) in DFS order and an approximate payload size. That is far more specific than the name alone, though it never explicitly distinguishes itself from get_site_node or search_site_nodes.

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

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

"Use it to find ids and section order" gives a real, actionable reason to pick this tool, which is more than implied usage. However it names no alternatives (search_site_nodes, get_site_node) and no when-not condition, so the agent must infer when the other node-listing tools are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds useful scope context ('authenticated tenant', '(remote)') but says nothing about result size, ordering, or whether the list is paginated/complete. Adequate but not rich.

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

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

A single front-loaded sentence with no filler; the verb and scope come first. The trailing parenthetical '(remote)' is slightly opaque and adds ambiguity rather than information, which keeps this short of a 5.

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-argument, read-only listing tool backed by annotations that already cover the safety profile, this is nearly complete. The only gaps are pagination/ordering expectations, which are minor here and there is no output schema to lean on.

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

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

The tool takes zero parameters, so the schema baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing parameter claims.

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

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

States a specific verb+resource ('List all sites') plus the scoping condition ('belonging to the authenticated tenant'), so an agent knows exactly what collection is returned. It does not explicitly contrast itself with the many other list_* siblings, but the resource noun is unambiguous enough to separate it from list_pages, list_collections, or list_site_members.

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

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

The description never says when to reach for this tool versus alternatives such as select_site, get_site_node, or the other list_* calls, nor does it mention any prerequisites. Usage is only implied by the verb, leaving the agent to infer context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing further – no pagination, result limits, ordering, or empty-result behavior – so it contributes no behavioral context beyond structured fields.

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

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

Two short sentences with the core purpose front-loaded and zero filler. It is efficient, though extremely minimal.

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

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

For a read-only list tool with full schema coverage and no output schema, the description is minimally adequate. It omits how results are returned (pagination, ordering) and how templates relate to sibling tools, leaving some 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 all three filters (q, tag, category) are already documented in the schema. The description merely restates that these filters exist without adding format, matching, or precedence semantics. Baseline 3 applies.

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

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

States a specific verb and resource ("List stock templates") and signals the resource is a catalog of stock templates, which loosely separates it from pull_template/select_template. It does not explicitly distinguish itself from adjacent list tools like list_presets or list_blocks, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as select_template or pull_template. Usage is only implied by the word "List."

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

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

Annotations declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false) but say nothing about preconditions. The description adds real behavioral content by naming the error conditions the agent must avoid (ROOT, page_home, moving into its own subtree), which is non-obvious and not derivable from the schema.

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

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

Two tight sentences, front-loaded with the action and followed by the constraint. No filler or restated name/title 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 4-parameter mutation tool with no output schema and adequate annotations, the description covers purpose and the key failure modes. What it omits (e.g., whether the move reorders siblings via 'position' or affects a published site) is minor.

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 nodeId, newParentId, position, and id are already documented in the schema; the baseline is 3. The description mentions 'new parent' and the subtree, loosely reinforcing two params, but adds no format, default, or ordering detail beyond the schema.

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

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

States a specific verb ('Move') plus resource and scope ('a node and its subtree to a new parent'), which clearly separates it from insert_node, delete_node, and patch_site_node. It does not name an alternative tool, so it stops short of full sibling differentiation.

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

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

The exclusions ('Can't move ROOT or page_home, or into its own subtree') tell the agent when the call will fail, which is useful negative guidance. However, it never states when to use this versus sibling operations like insert_node (creating a new node) or patch_site_node (updating a node in place).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: atomicity of the write, ordered application of patches to a single fetched document, and the concurrency rationale. It stops short of describing failure/rollback behavior or return shape.

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

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

Three tight sentences, front-loaded with the atomicity guarantee and the concurrency justification before the array-format caution. The inline enumeration of patch fields partially duplicates the schema, but it serves the array-vs-string warning, so little is wasted.

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

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

For a destructive bulk mutation with no output schema, the description covers atomicity, ordering, the concurrency motivation, and validation knobs are documented in the schema enums. Missing only return/rollback behavior and the item-count limits, which the schema supplies.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real value: the explicit warning that `patches` must be a real JSON array rather than a stringified one, plus the per-item patch field shape and the deferral to patch_site_node's rules for patch semantics.

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

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

States a specific verb and resource (apply many node patches) with explicit scope (atomic write) and differentiates from the single-patch sibling by naming patch_site_node and noting that parallel single patches lose updates. An agent can distinguish this from patch_site_node without opening either schema.

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

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

Gives a clear reason to prefer this tool over repeated single patches (lost updates under parallelism) and defers patch semantics to patch_site_node. It does not state explicit when-not conditions or limits (e.g. 1000-item cap is only in schema), so it falls short of full routing guidance.

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

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

Annotations only give destructive=true, idempotent=false, openWorld=false. The description adds real behavioral context beyond that: single atomic write, unsetProps runs before other patches, propsPatch deep-merges objects while strings/arrays replace, nodesPatch is reorder-only and blanks the canvas otherwise, image nodes reject content writes, and validation-mode defaults.

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

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

Front-loads the scope and the alternative in the first clause, then uses semicolon-dense fragments to pack merge/unset/image semantics. Every clause carries information, though the compressed telegraphic style slightly hurts readability.

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

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

For an 11-parameter destructive mutation with no output schema, the description covers the dangerous cases (reorder blanking canvas, image content rejection, patch ordering) well. Minor gaps remain, e.g. what the write returns and whether the site id/name fields interact with the node patch, but nothing essential is missing.

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

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

Schema coverage is 100% (baseline 3), but the description goes well beyond it: twMerge class merging, deep-merge vs replace semantics for propsPatch, ordering of unsetProps, and the image src-only/content-rejection constraint. That is genuine added meaning, not restatement.

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

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

States a specific verb+resource (patch one node) and immediately distinguishes itself from the batch sibling patch_site_bulk by noting the single-node, atomic-write scope. An agent can tell it apart from add_nodes/insert_node/move_node without opening another schema.

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

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

Explicitly routes multi-node edits to patch_site_bulk and points to get_style_reference({ topic: "editing" }) for rules, which is strong context. It stops short of saying when to prefer patch_site_node over insert_node/move_node for structural changes, so it is clear but not fully 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious context beyond that: rendering uses sample data, and an email containing errors causes the default email to be sent instead. Those are meaningful behavioral facts not present in the annotations.

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

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

A single front-loaded sentence carrying the action first and the returned fields after. It is compact with no filler, though the trailing list and parenthetical make it slightly dense for one sentence.

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

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

No output schema exists, so the description must convey what a preview returns, and it does list subject, errors, warnings, and plain text. Parameters are covered by the schema, and the safety profile by annotations, so the remaining gaps are minor.

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

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

Schema description coverage is 100%, so both 'id' and the enumerated 'kind' are already fully documented by the schema. The description lists rendered outputs (subject, errors, warnings, plain text) rather than clarifying either parameter, so it adds nothing beyond the schema and the baseline 3 applies.

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

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

States a specific verb+resource: 'Render the saved email with sample data', which clearly separates it from sibling reads like get_site_email (fetch raw data) and update_site_email (mutate). It does not explicitly name those alternatives though, so the differentiation is implied rather than stated.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as get_site_email or update_site_email. An agent can infer this is a dry-run preview, but nothing in the text tells it when previewing is the right call versus fetching or editing.

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 staging model is genuine behavioral context the annotations do not convey, and the omit-to-leave-unchanged note describes state behavior. However, the annotations declare destructiveHint=true and the description never explains what publishing destroys or overwrites (the current live site), nor any auth requirements or failure behavior, which is the most important disclosure for a destructive 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 short sentences, front-loaded with the action and its effect on the live site, and none is wasted. The parameter note is placed last where an agent needs it.

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

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

For a two-parameter publish toggle with no output schema, the description covers purpose, staging semantics, and the optional flag's default behavior. The main remaining gap is the destructive consequence of publishing, which matters given destructiveHint=true.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: that omitting `static` leaves the current setting unchanged, and that the flag toggles static delivery on/off. It does not describe `id`, though the schema already covers it adequately.

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

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

The description gives a specific verb and resource ('Publish the draft so it goes live') and distinguishes this tool from the many write siblings by explaining that 'every write is staged until this runs', which tells the agent that update_site/patch_site_bulk do not go live on their own. It never names the counterpart unpublish_site, so the sibling mapping is implied rather than explicit.

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

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

'Every write is staged until this runs' is real usage guidance: it tells the agent this is the step required to make prior edits visible, and that omitting it leaves the site in draft. There is no explicit when-not-to-use clause (e.g. previewing) or reference to unpublish_site, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the payload is a decoded node tree (useful given no output schema), but says nothing about size, pagination, or whether the template must be selected/installed first.

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

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

One short, front-loaded sentence with no filler. It is efficient, though it is arguably under-specified rather than truly concise.

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

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

For a one-parameter read tool with no output schema, naming the return payload (decoded node tree) partially compensates. Still missing is any hint about the relationship to select_template/list_templates and whether a site context is required, which matters given the crowded sibling set.

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

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

Schema coverage is 100% and the single slug parameter is already documented as 'Template slug to pull' with a maxLength constraint. The description's mention of a template slug adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Download) and resource (a stock template's decoded node tree), which is more informative than a restatement of the name. It does not, however, differentiate itself from nearby siblings like select_template, list_templates, or get_block, leaving the agent to guess which template-access tool fits.

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

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

There is no statement of when to use this tool versus list_templates or select_template, no prerequisites, and no exclusions. The agent must infer usage entirely from the name and the sibling list.

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 two useful facts beyond the annotations: the target collection is created if absent, and the call returns a product count. However, the annotations declare destructiveHint=true, and the description never warns that the existing `products` collection contents are overwritten by the sync — the highest-risk behavior for an agent to know. No contradiction, but a notable disclosure gap.

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

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

Three short sentences, zero filler, with the core action front-loaded. The trigger condition and return value are appended in decreasing order of importance.

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

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

With no output schema, the description helpfully states the return value, and it covers what the tool does, when to run it, and its collection-creating side effect. The one gap is overwrite semantics on the target collection, which the destructive annotation flags but the description does not explain.

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

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

Schema description coverage is 100% with a single, self-explanatory `siteId` parameter, so the schema carries the parameter burden. The description adds no format, default, or scoping detail for siteId, making this baseline 3.

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

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

States a specific verb and resource ('Sync the site's Stripe catalog'), names the destination collection, and notes the side effect (creating it) and the return value. This separates it cleanly from read-only Stripe siblings like stripe_get_product, stripe_search_products, and stripe_list_categories.

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?

'Run after products change in Stripe' gives an explicit trigger condition, which is real usage guidance. It stops short of naming alternatives or exclusions (e.g. what to use instead if you only want to read the catalog), so it is clear context without full routing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: the link 404s after removal, non-current versions can be targeted individually, and unused files are deleted. This tells the agent what actually happens.

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

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

A single sentence with three well-packed clauses. The primary destructive effect (link then 404s) is front-loaded, followed by the version variant and cleanup behavior. No waste.

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

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

For a 3-param destructive mutation with full annotation coverage and no output schema, this covers what the agent needs: the resource, the two removal modes, and the side effects. It could mention that the downloadId is required or whether versionId can be combined, but the schema handles that.

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

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

Schema coverage is 100%, so all three parameters (id, versionId, downloadId) already have documented meanings. The description's phrase 'one non-current version' adds interpretive context for when versionId applies, but the schema already describes it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Remove) and resource (download), and immediately disambiguates the two modes: removing a download (causing link 404) versus removing one non-current version. The parenthetical 'link then 404s' distinguishes this clearly from siblings like delete_page or delete_node.

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

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

The description implies usage through the two mode descriptions (remove download vs remove one non-current version), which suggests when each parameter applies, but it doesn't explicitly state when to use this tool versus set_download or list_downloads. No alternative is named.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds one useful behavioral detail — that the operation nulls the portal — but says nothing about irreversibility of the portal config or required permissions. It does not contradict the annotations.

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

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

A single front-loaded sentence naming the action, target, and resulting state with zero waste. Nothing extraneous.

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 destructive single-parameter tool, the description plus annotations give the agent enough to call it correctly (what it does, that it is destructive and idempotent). Only a note on whether the removed portal can be restored would improve it further.

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

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

With a single parameter ('id', Site id) at 100% schema description coverage, the schema fully documents the input. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (remove/disable) and resource (portal on a site), and clarifies the end state '(sets portal to null)'. The sibling set contains get_portal and set_portal, so the verb distinguishes it, but the description never explicitly names those alternatives.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as calling set_portal with a null value or checking get_portal first. Usage is only implied by the verb.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety behavior is covered. The description adds non-obvious context: only *pending* invites are affected and existing members are untouched, which clarifies blast radius, plus the owner-only authorization requirement.

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

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

A single compact sentence that front-loads the action and resource, then appends prerequisite and scope. No filler.

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

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

For a mutation tool whose annotations carry destructive/idempotent semantics, the description covers authorization, scope, and input provenance, so an agent has what it needs. The lingering id vs inviteId ambiguity is the only minor gap.

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

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

Schema coverage is 100%, so both parameters (id and inviteId) are already documented. The description's 'by id' phrasing slightly muddies which identifier applies since the schema has two id-like params, adding little beyond the schema baseline.

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

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

States a specific verb (revoke) and resource (pending site invite), plus the scope of what is affected ('existing members stay'). It is clearly distinguishable from invite_site_member and other site 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?

Names the prerequisite (Owner-only) and points to where the id comes from (list_site_members), which tells the agent how to obtain input. It does not, however, contrast against alternatives such as removing a member rather than revoking an invite.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that capture happens against the DRAFT in a real browser and that `selector` produces an unscaled full-size render, but it never says what the tool returns (image payload, URL, artifact id) or flags the latency/async nature of real-browser captures.

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

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

Two tight sentences, front-loaded with the action and scope, then the rendering caveat and selector/width advice. Dense but never padded; minor friction from shorthand like '390' without units and a heavy em-dash list.

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?

All six parameters are documented in the schema and the read-only safety profile is covered by annotations, so nothing essential is missing for invocation. However, with no output schema the description should say what a screenshot call yields (and whether it is synchronous or polled), which it omits.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: `selector` yields full-size (not scaled down) section captures, and it recommends concrete widths ('design width and 390') that the numeric `width` parameter alone does not convey as intent.

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 (screenshot) and resource (the DRAFT site) rendered 'in a real browser', and clarifies what that actually captures: compiled CSS, theme, state-driven UI, responsive layout. No sibling tool performs rendering/capture, so an agent can distinguish it immediately.

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?

Frames the tool as 'the only way to see compiled CSS, theme, state-driven UI and responsive layout', which tells the agent when this is the right call, and advises targeting sections with `selector` and shooting at design width and 390. It stops short of naming exclusions (e.g. published vs draft, or what to use for non-visual verification).

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