PageHub

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds the important constraint that the map must contain only new nodes and points at the get_style_reference contract, but says nothing about error behavior, attachment conflicts, or what happens when parentId does not exist.

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 front-loaded: the core action and attach point come first, followed by the node shape and then the alternatives/contract. The 'Contract:' fragment is slightly telegraphic but every sentence carries information relevant to correct invocation.

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 nested-object mutation with 7 parameters and no output schema, the description covers the payload contract and defers styling details to get_style_reference. It nonetheless omits return behavior and failure modes, leaving the agent partially informed for a structurally complex write.

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 would be 3, but the description genuinely extends the schema: it enumerates the internal node shape (type.resolvedName, isCanvas, props, parent, nodes[], linkedNodes) which the schema only summarizes as 'Flat map { nodeId: node }'. This clarification of nested-object structure is real added value.

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 ('Add a subtree') and explains what constitutes the payload (flat map of new nodes plus rootNodeId). It distinguishes itself from one sibling by noting apply_kit_block covers standard sections, but leaves its relationship to insert_node/move_node/add_page unstated.

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 an implied when-not ('apply_kit_block covers standard sections') and a contract reference to get_style_reference({ topic: "editing" }), which is genuinely useful context. However, there is no explicit statement of when to choose add_nodes over the nearby insert_node, move_node, or add_page siblings.

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

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

Annotations establish the non-readonly, non-idempotent, non-destructive write profile. The description adds genuinely useful behavior that annotations lack: the return payload (pageId, needed since there is no output schema) and the ROOT/Container placement semantics plus the home-page special case.

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 action and the return value, then supporting context in a compact parenthetical. No filler sentences; every clause carries distinct 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 correctly identifies the return value and its downstream consumers, and it explains the ROOT placement model. It omits only minor points like slug-collision handling or the footer default position (covered in schema), so it is nearly complete for a 6-param nested-object write tool.

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

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

Schema description coverage is 100%, so the schema already documents name, id, position, is404Page, isHomePage, and every seo field. The description's only addition is that seo.title and seo.description can be set at creation time, which is marginal. 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 specific verb and resource ("Create a page") and pins down what a page is: a type "page" Container under ROOT, with the first being home. An agent can distinguish this from create_site, insert_node, or 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 context: it returns the pageId that apply_kit_block and add_nodes consume, which tells the agent the create-first ordering, and it routes to get_style_reference({topic:"pages"}) for guidance. It doesn't explicitly say when to prefer update_page over this, but the create-vs-update boundary is obvious from 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 flag destructiveHint=true and non-idempotent, and the description adds meaningful detail beyond that: header/footer targets *replace* the existing header/footer, and sourceNodeId "deep-clone[s] with fresh ids". `contentOverrides` applying final copy in the same call is also useful behavioral context, though permissions/return behavior are unstated.

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 its two modes, then the override/target semantics. Dense but every clause carries information; the trailing guide pointer is a minor bit of overhead but justified.

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, 9-parameter mutation tool with no output schema, the description covers the key modes, mutual exclusivity, replacement side effects, and override purpose. It stops short of stating permission requirements or failure/return behavior, but is largely sufficient to invoke 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 baseline is 3, but the description adds semantics the schema doesn't: contentOverrides is keyed by the block's lib_* ids, and target semantics (header replaces hdr_root, etc.) are clarified. This nudges it above baseline.

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

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

States a concrete verb and resource ("Add a section") and enumerates the two mutually exclusive creation modes (stamp a library block via `slug` or deep-clone a page section via `sourceNodeId`). This clearly separates it from siblings like add_nodes/insert_node that lack the library/clone semantics.

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

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

Gives explicit operating rules: "exactly one" of slug/sourceNodeId, target "header"/"footer" replaces the site header/footer, heroes are page sections, and points to get_style_reference({ topic: "blocks" }) for guidance. It does not, however, contrast this with sibling tools such as add_nodes or insert_node, so the agent must infer when this is preferred.

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 openWorldHint=false, and the description adds value beyond them by disclosing the return shape: violations grouped by severity with node ids. This is genuinely useful since there is no output schema, though auth/rate-limit behavior is still unstated.

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 tightly packed sentence with zero waste: scope first, then checked categories, then return format. Nothing could be removed without losing signal.

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

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

For a read-only audit tool with full schema coverage and no output schema, the brief return description plus enumerated check categories is nearly sufficient. Only the missing 'when not to use this' guidance and any default-fallback nuance (page_home, AA) keep it from a 5.

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

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

Schema description coverage is 100%, so all four parameters (including the A/AA/AAA enum and the id-vs-templateSlug exclusion) are already documented. The description adds no format or default detail beyond the schema, which is the expected 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?

Names a specific verb+resource ('WCAG audit of a site or template page') and enumerates exactly what is checked (contrast, alt text, headings, ARIA, interactive elements), which clearly distinguishes it from the sibling audit_seo. An agent can pick 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?

Scope is implied through 'site or template page' and the schema's mutual exclusion of id/templateSlug, but the description never says when to choose this over audit_seo or what prerequisites exist. 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=true and openWorldHint=false, so the safety profile is covered. The description adds a useful return hint ('Returns fixes with node ids'), which matters since no output schema exists. It does not disclose permissions, limits, or whether the audit is exhaustive versus sampled.

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, zero filler. The scope enumeration comes before the return-shape note, so the most decision-relevant information is front-loaded.

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

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

For a read-only audit with three well-documented optional params, the definition covers what is checked and what comes back. The missing piece is invocation guidance (which of id vs templateSlug to pick, and when to prefer this over audit_accessibility), but nothing needed to call it correctly is absent.

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 id/pageId/templateSlug semantics and the default page_home are already documented in the schema. The description's phrase 'site or template page' only lightly reinforces the mutually exclusive input modes. 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 (score) and resource (site or template page), then enumerates the exact checks performed (meta, heading hierarchy, alt text, link text, content depth). This differentiates it from the sibling audit_accessibility by domain, though it never explicitly contrasts the two.

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

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

No statement of when to run this audit versus alternatives, no prerequisites, and no mention that the caller must pass either id or templateSlug. The mutual-exclusion rule lives only in the schema. The closest sibling, audit_accessibility, is never referenced.

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 and openWorldHint. The description adds real value beyond them: it confirms no mutation occurs ("Changes nothing") and describes what the check returns (free/attached/erroring plus required DNS records), which is genuine 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 dense sentence that front-loads the action and enumerates the result states. No filler, no repetition 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?

With no output schema, the description usefully enumerates the return states and the DNS records output. It is complete enough for an agent to call and interpret the result, though it doesn't cover rate limits or what happens for malformed domains.

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 in the schema. The description only obliquely references the apex+www treatment and adds no syntax or format guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb (preflight/check) and resource (a candidate domain, apex + www), and names the exact output: availability state plus needed DNS records. This clearly distinguishes it from set_domain and get_domain_status 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?

"Preflight" plus "Changes nothing" strongly implies this is the read-only step before an attach operation, steering the agent away from set_domain. It does not, however, explicitly name the alternative tool or state when not to use it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true. The description adds genuine value beyond these by disclosing the exact side effects: detaching both apex and www variants from Vercel and resetting redirectMode to none. It does not mention auth requirements, but the destructive scope is well disclosed.

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

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

Two sentences, no filler, and the primary action is front-loaded ahead of the side-effect detail. 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 single-param mutation with annotations covering the safety profile and no output schema, the description supplies what an agent needs: the target site, the exact artifacts removed, and the redirect reset. Only permissions/preconditions 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?

Only one parameter exists and schema description coverage is 100%, so the schema already explains 'id'. The description adds no parameter-level meaning, which is the expected baseline 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?

States a specific verb and resource ('Remove the custom domain from the active site'), which reads distinctly from the set_domain/set_domain_redirect_mode siblings. It stops short of explicitly naming which sibling to use instead, so it is clear but not sibling-differentiating by name.

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

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

No when-to-use or when-not-to-use guidance is given. The agent must infer that this is the inverse of set_domain, and there is no mention of prerequisites or alternatives such as set_domain_redirect_mode.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, so safety is covered. The description adds two genuinely useful facts not in the annotations: source defaults to 'manual' and the operation is plan-gated. It omits failure behavior (duplicate slug, quota errors), which matters for a creation 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?

Very tight, front-loaded with the verb first and the dense schema/type reference after. No filler sentences. The terse shorthand ('…') keeps it short 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?

For a 7-parameter, nested-object creation tool with no output schema and no annotation detail on side effects, the description covers the hardest part (field schema syntax) but says nothing about slug uniqueness, site_id scoping, or visibility semantics of isPublic. Adequate, not complete.

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

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

Schema coverage is 43%, so the description must compensate, and it does partially: the schema array's element shape and the full field-type enum are spelled out, which the schema itself only leaves as a bare object. But name, slug, site_id, isPublic and description get no explanation in the description, and 'schema' points back to the description in a small circular loop.

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?

Opens with a specific verb+resource ('Create a collection'), which is clearly distinct from the row-level siblings (create_collection_row, create_collection_rows) and from delete_collection. It does not explicitly name those siblings, so it stops 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as update_collection_schema (for later field changes) or import_collection_csv (for bulk data). 'Plan-gated' hints at a precondition but doesn't say what to do when the plan doesn't permit 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 the safety profile (not read-only, not idempotent, not destructive), so the bar is lower. The description adds two real behavioral facts not in the annotations: writes are validated against the collection schema, and the tool is plan-gated. It says nothing about what happens on validation failure, whether the row is immediately published, or quota 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?

Three terse fragments, front-loaded with the action, no filler. It is arguably under-specified rather than verbose, but nothing in the text 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 mutation tool taking a nested `data` object validated against a dynamic schema, with no output schema, the description omits key operational detail: the meaning of `slug`, whether `site_id` is needed when a site is already selected, and the result of a failed validation. Given the low schema coverage, more was required here.

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

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

Schema coverage is only 33% and the description only restates the `data` parameter ('field key → value, validated against the schema'). Neither `slug` (which collection? format?) nor the optional `site_id` is explained anywhere, so two of three parameters are effectively undocumented.

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

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

Specific verb + resource ('Create one row'), which implicitly distinguishes it from the bulk sibling create_collection_rows. However it never names that sibling or the collection it writes into, so the singular/plural distinction must be inferred 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?

No when-to-use guidance and no mention of the obvious alternative create_collection_rows (or import_collection_csv) for bulk inserts. 'Plan-gated' hints at a prerequisite but is not explained as a usage condition.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description is consistent with them. It adds valuable non-annotation context: all-or-nothing validation semantics, that errors name the failing rowIndex, the 500-row cap, and the plan 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?

Three terse clauses, front-loaded with the core action and size limit, then validation behavior, then gating and the alternative. 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 mutation tool with no output schema, the description covers batch limit, validation/error behavior, plan gating, and an alternative path. It omits what 'slug' refers to and the response shape, but the essentials for correct invocation are present.

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

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

Schema description coverage is only 33%, so the bar for the description is raised; it clarifies the 'rows' structure as field key → value and repeats the 500 cap. But 'slug' and 'site_id' (both required-relevant identifiers) receive no explanation of meaning or expected format from either schema or description, so it only partially compensates.

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 (Insert) and resource (collection rows) with batch scope (up to 500 in one call), and the field key → value shape makes the payload model concrete. It clearly distinguishes itself from create_collection_row (singular) by emphasizing the batch/all-or-nothing nature.

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 context (batched inserts) and explicitly routes large imports to import_collection_csv. It also flags 'Plan-gated.' However, it never explicitly contrasts with the sibling create_collection_row for small single-row inserts, leaving one inference to the agent.

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

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

Annotations already declare readOnlyHint=false, 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 and idempotentHint=true, so the description doesn't need to repeat that. It adds critical context: 'and all its rows' clarifies cascading deletion, and 'No undo' emphasizes irreversibility. This goes beyond annotations by specifying scope and irreversibility.

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, no waste. The critical warning 'No undo' is front-loaded and impossible to miss.

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

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

Given that annotations cover safety (destructive, idempotent) and no output schema exists, the description adequately covers purpose and irreversibility. However, with 0% parameter documentation and no guidance on alternatives, it's incomplete for a destructive tool where misuse carries high risk.

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

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

Schema coverage is 0% – neither 'slug' nor 'site_id' is described in the schema. The description doesn't mention any parameters or their purpose. For a 2-parameter tool with zero schema documentation, the description fails to compensate, leaving the agent to guess what 'slug' and 'site_id' represent.

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 verb+resource: 'Delete a collection' precisely states the operation. It also clarifies the cascading effect ('and all its rows'), distinguishing it from delete_collection_row. However, it doesn't explicitly name the sibling alternative.

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

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

The description implies when to use (to remove a collection entirely) and highlights the destructive nature, but offers no explicit guidance on alternatives like delete_collection_row for removing single rows. No when-not-to-use conditions are stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond them: no confirmation that the deletion is permanent, no note on failure behavior when row_id does not exist, and no indication of what site_id is needed for.

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 single sentence is front-loaded and wastes no words, but it is undersized for a three-parameter destructive operation. Brevity here reflects missing content rather than disciplined editing.

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?

A destructive, idempotent tool with no output schema and zero schema description coverage needs the description to carry scope, targeting, and side-effect information. Only the row-level scope is covered; collection identification, site scoping, and irreversibility are absent.

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

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

Schema description coverage is 0%, so the description is the only place parameter meaning could be conveyed. It mentions row_id only implicitly by naming it, and says nothing about the required 'slug' (which collection is targeted) or the optional 'site_id', leaving two of three parameters semantically unexplained.

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

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

States a specific verb and resource ('Delete one row from a collection') and scopes it to a single row via row_id, which cleanly separates it from delete_collection in the sibling list. It stops short of naming that sibling or the row-array counterpart explicitly, so differentiation is left partly 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?

There is no when-to-use guidance, no statement of prerequisites, and no mention of alternatives such as delete_collection or update_collection_row. The agent must infer the use case entirely from the tool 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 safety is covered. The description adds genuinely useful behavior the annotations can't convey: deletion cascades to the subtree, and four named root nodes are protected. It doesn't mention auth requirements or irreversibility, so it's 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?

Two short sentences, zero waste, with the primary action and cascade behavior front-loaded before 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 no output schema, the description plus annotations give an agent enough to call it correctly: what it does, that it cascades, and which nodes are protected. Missing only auth/permission caveats and confirmation-of-irreversibility notes.

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, nodeId) are already documented by the schema, including that nodeId comes from list_site_nodes/search_site_nodes. The description adds nothing about parameters, 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 precise verb+resource (delete a node) and adds scope that matters: the entire subtree goes with it. This clearly separates it from delete_page and delete_site, though it never names those siblings explicitly, so it stops 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?

No when-to-use guidance and no routing to alternatives like delete_page or move_node. The only usage rule given is the negative constraint that ROOT, page_home, hdr_root and ftr_root cannot be deleted, which is a constraint rather than selection 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. The description adds genuinely new behavioral context: content is deleted along with the page, the last page cannot be deleted, and deleting home promotes the next page — all side effects an agent would not learn from annotations alone.

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

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

Two short sentences, front-loaded with the core action and followed by the two real operational constraints. No filler or restatement of the tool name.

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

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

For a destructive, non-idempotent-looking operation there is no output schema, and annotations plus the description together cover scope and edge cases well. The only gap is that nothing is said about permission requirements or what the response returns, which is minor given the annotation coverage.

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 both 'id' (site id) and 'pageId' documented in the schema, so the baseline is 3. The description adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource ('Delete a page') plus the scope of deletion ('and its content'), which distinguishes it from delete_node, delete_collection, and delete_site. An agent can identify the target entity 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 by the name and the stated constraints, but there is no explicit when-to-use guidance or reference to alternatives like update_page or delete_node. The constraints ('last page can't be deleted') do help an agent avoid an invalid call, which lifts it above pure non-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 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 and openWorldHint=false, so the safe read profile is covered. The description adds real value by disclosing the output ref format and the brand-logo coverage caveat for Tabler, though it omits rate limits or result-ordering mechanics.

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, front-loaded with the core action and return shape, then a practical caveat. Every sentence earns its place, though the second sentence's ellipsis shorthand is slightly informal.

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, but the description compensates by explaining the return ref format. With annotations covering safety and the schema covering all parameters, an agent has enough to call this correctly; only edge behavior like empty results is 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 q, set, kind, and limit. The description reinforces that results span every set and mentions set shorthand (tb/fa/si) but adds no syntax or default details beyond what the schema provides.

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

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

The description states a specific verb (Search) and resource (every icon set) and even specifies the return format (`ref-icon:<set>/<Name>` refs for Icon nodes and Button/Link icon.value). This clearly distinguishes it from sibling lookups like find_image, find_video, and search_blocks.

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

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

It gives clear context for use and a useful routing hint: Tabler (tb) lacks many brand logos, so brands come from fa / si. It does not explicitly say when NOT to use it versus find_image, but the icon-specific framing is strong.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-network behavior are covered. The description adds real value by disclosing the source hierarchy ('local bank, then Unsplash/Pexels'), which explains where results come from, but says nothing about result limits, caching, or failure behavior when no image matches.

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

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

A single compact sentence with the resource and the most decision-relevant fact (verified URLs, source order) front-loaded. It is a fragment without a verb, which slightly weakens readability, but there is no wasted text.

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

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

With no output schema, the description usefully signals that results are URLs ready for use, and all five optional parameters are self-documenting via the schema. An agent has enough to invoke it correctly; only edge-case behavior (no results, provider outages) is 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 each of the five parameters carries its own description, including enum semantics for category, provider, and orientation. The prose 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?

The description names the concrete resource ('Stock photos') and quality guarantee ('verified, ready-to-use URLs'), so an agent can tell it apart from find_video and find_icon without opening a schema. It is a noun phrase rather than a verb+resource statement, but the intent is unmistakable.

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 reach for this tool versus find_video, find_icon, or upload_image, and no prerequisites or exclusions are given. The provider fallback order hints at sourcing behavior but is not framed as usage 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 and openWorldHint=true, covering the safety and reach profile. The description adds that results are direct MP4 URLs from Pexels, which is useful output context, but it does not disclose rate limits, auth requirements, or pagination 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?

The description is a single compact sentence fragment that is front-loaded with the resource and key output characteristic. Every word earns its place and there is no redundancy.

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

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

For a tool with 6 optional parameters and no output schema, the description is minimal. It covers the core output (MP4 URLs) and source, but does not describe the return shape (e.g., a list of videos with metadata) or clarify default behavior when filters are omitted, 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 every parameter is already documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, making the baseline of 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 names the resource (stock videos) and the key output trait (direct MP4 URLs from Pexels) and ties it to Video nodes, which distinguishes it from find_image and find_icon. It lacks an explicit verb, but the tool name supplies that, and the scope is specific enough for an agent to select it 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives. The phrase 'for Video nodes' implies the intended context, but the agent must infer that this is the right tool for fetching stock video rather than reading it from structured 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 and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the output shape (className plus activeModifiers) and that results are extensible, but it says nothing about determinism, default behavior interactions, or how modifiers are derived.

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, no filler, with the primary output front-loaded before the caveat. Every sentence earns its place.

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

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

With no output schema, the description correctly names the two returned values (className, activeModifiers) so the agent knows what to expect. For a tool with 8 optional parameters and a simple string output, this is largely sufficient, though the exact className/modifier format remains 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% with 8 well-documented parameters, so the schema carries parameter semantics. The description only restates variant/shape/size and adds no format or interaction 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 (Generate) and resource (Button className + activeModifiers) and names the intent inputs it derives from. It is clearly distinguishable from CRUD siblings. It does not, however, differentiate itself from the close sibling validate_button_classes, which likely operates on the same className concept.

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 this is a generation step whose output feeds further work, which lightly signals when to reach for it. But there is no explicit when-to-use vs. the near-identical validate_button_classes sibling, and no stated 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds a genuinely non-obvious behavioral fact — 'Counts as a use' — which is billing/quota information the agent cannot get from annotations. It also describes the payload as a 'full tree', though it does not detail depth or format.

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 billing note; the core action is front-loaded and every clause carries information (what it returns, the key, the downstream use, the quota cost). No filler.

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

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

For a no-output-schema, read-only lookup with a fully documented single parameter, the description covers purpose, key, return shape at a high level, and quota cost. It could be slightly more complete about the tree structure or how the result interops with add_nodes node identifiers.

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 there is only one parameter, so the schema already documents 'Block slug.' The description's 'by slug' adds no syntax or format detail beyond the schema, making 3 the appropriate 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?

Names a specific verb and resource ('Get a library block's full tree by slug'), which is clearly distinct from listing tools like list_blocks or search_blocks. It also ties the result to a downstream task (hand-building with add_nodes), though it does not explicitly contrast itself with list_block_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?

States the context in which to use it: as a reference for hand-building nodes with add_nodes. It gives a clear purpose-driven trigger but no explicit when-not guidance or named alternatives (e.g., when search_blocks or list_block_nodes is 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 and openWorldHint=false, so safety is covered. The description adds the useful detail of what the returned definition contains, but says nothing about auth requirements, error behavior for a missing slug, or scoping by site.

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 parenthetical lists the payload contents compactly and 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 with no output schema and annotations covering safety, the description adequately conveys what is returned. However, the undocumented optional site_id parameter leaves a real gap in how the caller should scope the lookup.

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

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

Schema coverage is only 50%: slug is documented in the schema, but site_id is undocumented in both the schema and the description. The description does not compensate for the coverage gap or clarify how a collection is scoped when site_id is omitted.

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 what the definition contains (schema fields, source, isPublic). An agent can distinguish it from list_collections and update_collection_schema, though it does not name a 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?

The word 'one' weakly implies single-item retrieval, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives like list_collections for enumerating collections. The agent must infer the 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 cover read-only and non-open-world safety, so the bar is lower. The description adds real behavioral context: the return shape (types, props, valid values), that a comma list scopes the response, and that responses become compact under parallel fill. It does not cover response size limits or pagination, but the added detail is substantive.

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 return payload. No filler. Minor deduction because 'In parallel fill' is unexplained jargon that costs the reader without adding clarity.

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 carry return-value meaning, and it does sketch the payload shape (types, props, valid values). For a single-parameter read tool this is nearly complete; the only gap is deeper detail on the returned structure and the compact-mode format.

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. The description goes further by stating that a comma list narrows the result and that `components` becomes required in the parallel-fill case — a conditional constraint the schema text ('Omit for all') does not convey. That is meaningful added 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 the specific resource and what it returns: 'Full prop schemas for components (types, props, valid values)'. This distinguishes it from neighbors like get_style_reference or list_presets by naming the artifact returned. It does not explicitly name a sibling alternative, 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?

Adds one conditional usage hint ('In parallel fill, responses are compact and `components` is required'), which is genuinely useful context. However, it gives no guidance on when to reach for this tool versus get_style_reference, list_presets, or get_block, and the 'parallel fill' scenario is left unexplained.

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 openWorldHint=true, so the safety profile is covered; the description adds that the 'check' path makes no changes, reinforcing the non-mutating nature beyond the annotations. It stops short of describing anything about freshness or failure behavior, which keeps it from a 5.

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

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

Two tight sentences, with the primary resource and returned data front-loaded and the secondary 'check' mode appended. Every clause carries information and nothing is redundant.

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

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

For a read-only, no-output-schema tool, the description adequately conveys what comes back (redirect mode, apex/www state, required DNS records), so an agent can act without opening the schema. It is not fully complete on how to interpret or act on those records.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema's terse 'Candidate domain to preflight' by clarifying that check performs a side-effect-free preflight, adding real semantic value for that parameter.

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

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

The description states a specific verb and resource ('Read the site's custom domain') and enumerates the payload fields (redirect mode, apex/www Vercel state, DNS records), so an agent immediately knows what it returns. It does not, however, distinguish itself from the sibling 'check_domain' or 'set_domain' tools, which keeps it below a 5.

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

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

Usage is only implied: the 'check' clause hints at a preflight use case for another domain, but there is no explicit when-to-use guidance, no when-not, and no routing to the similar 'check_domain' sibling. The agent must 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?

The readOnlyHint=true and openWorldHint=false annotations already tell the agent this is a safe, non-network read. The description adds that the returned config is the 'current' state for a site, but says nothing about whether a portal may be absent, error behavior, or what the configuration comprises.

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 zero filler. Slightly under-informative rather than verbose, but nothing in it is wasted.

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

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

For a simple one-parameter read tool with no output schema, the description covers the essentials but omits what a portal configuration actually contains and how absence is signaled. Adequate but with visible gaps given the lack of a return-value schema.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema ('Site id. Pass it on every call.'). The description adds no syntax, format, or default guidance 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 (Fetch) and resource (portal configuration) scoped to a site, which distinguishes it from the write-side siblings set_portal and remove_portal. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated in-text.

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

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

No statement of when to use this versus set_portal/remove_portal or other get_* readers. The read intent is only inferable from the verb 'Fetch' and the readOnlyHint annotation, leaving the agent to infer usage 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description still adds real domain context beyond the annotations: which node types are legal in an email and which classes are forbidden (btn/card/shadow/gradient/absolute). That constrains how consumers can use the returned data.

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

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

Two sentences, front-loaded with the return contents, with the constraints packed into the second sentence. Dense but every clause carries information; 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?

No output schema exists, so the description must convey return shape, and it does (subject, preheader, node tree). The read-only nature and closed-world scope come from annotations. Missing only explicit pagination/error behavior, which is minor for a single-resource getter.

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

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

Schema coverage is 100%, with both id and the enum-constrained kind already documented, so the baseline is 3. The description's mention of {{variables.*}} and EmailSlot nodes is about content shape rather than parameter meaning, so it does not add per-parameter value.

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 ('Read one site email') and enumerates the returned structure (subject, preheader, node tree, variables, EmailSlot nodes). 'One' implicitly separates it from the sibling list_site_emails, so an agent can distinguish the two 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?

Usage is only implied: reading a single email's structure is the natural prerequisite to preview_site_email or update_site_email, but neither is named and no when-not condition is given. The 'keep required slots exactly once' note hints at edit workflows but doesn't route the agent 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 declare readOnlyHint=true and openWorldHint=false. The description adds non-obvious behavioral context: propsPatch replaces string props whole, so the returned JSON is the current value to merge into. This is useful beyond the annotations, though it omits other traits like error handling or return structure.

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

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

Two sentences, front-loaded with the core action. The second sentence is slightly cryptic but earns its place by conveying merge semantics; no filler text.

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

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

Given a simple read tool with no output schema, the description could say more about what the raw JSON contains or clarify the relationship to patch_site_node. It covers safety via annotations and adds merge context, but leaves some gaps for an agent unfamiliar with the node model.

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 nodeId are fully documented in the schema. The description adds no parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Read one node's raw JSON.' This distinguishes it from siblings like list_site_nodes and patch_site_node, though it never explicitly names alternatives. The second sentence about propsPatch adds context but slightly muddles the core purpose.

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

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

The description implies a usage scenario (getting the current value to merge into propsPatch), but it does not explicitly state when to use this tool versus alternatives like list_site_nodes, search_site_nodes, or get_block. The guidance is embedded rather than 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral context by listing the specific content categories returned (palette variables, spatial scale, modifiers, interactive state, form-confirmation recipe), which helps an agent anticipate the reference material. It stops short of describing the output format or size.

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

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

Two sentences with no wasted words. The content categories are front-loaded, and the optional topic parameter is introduced immediately after. Every sentence earns its place.

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

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

For a reference-retrieval tool with one optional enum parameter and no output schema, the description provides enough to call it correctly and understand what content it returns. It does not specify the return format, but the enumerated content categories give sufficient context for an agent to decide to invoke it.

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

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

Schema description coverage is 100% and the schema already states that 'topic' returns one guide instead of the core reference. The tool description repeats this and provides a few example topics, but adds little beyond the schema’s enum and description. 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?

The description names the resource as a 'Styling reference' and enumerates the content categories (palette variables, styleGuide tokens, spatial scale, etc.), making the purpose clear. It does not explicitly differentiate itself from related sibling tools like suggest_palettes or suggest_font_pairings, but the reference nature is evident.

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

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

The description implies usage: call without topic for the core reference, and pass topic for a focused guide. However, it does not state when to choose this tool over alternatives (e.g., suggest_palettes for palette generation) or any exclusions. The guidance is present but minimal.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds value beyond that by spelling out exactly what replace destroys (existing rows), the ~8MB size cap, and that the tool is plan-gated. It omits behavior on partial/malformed rows, but the addition over the annotations is substantial.

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

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

A single dense paragraph that front-loads the core operation and then dispatches the mode semantics, size cap, and gating in short clauses. No sentence is wasted.

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

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

For a destructive, plan-gated bulk mutation with no output schema and 50% param coverage, the description covers the critical call decisions: merge mode, row-destruction semantics, size limit, and access gating. It does not describe failure handling for malformed rows, a minor gap given the remaining uncertainty about slug/site_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 coverage is only 50%, so the description must compensate. It usefully explains the csv parameter (header row matches field keys, unmatched ignored) and the mode enum semantics including the upsert key requirement, going well beyond the schema's terse 'Merge mode. Default append.' slug and site_id remain unexplained in both places, keeping this from a 5.

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

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

States a specific verb (import) and resource (collection CSV) and immediately clarifies the header-to-field-key mapping behavior, which distinguishes it from sibling row tools like create_collection_rows or update_collection_row. An agent can identify the operation without reading 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?

Provides clear context for choosing a merge mode (append default, replace deletes existing rows first, upsert keyed on externalId/id), which is the main decision an agent must make. It does not, however, route the agent away from sibling bulk tools or state when this tool is preferable to create_collection_rows.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds useful behavioral context beyond that: parent and linkedNodes are automatically set, and lists/tables require specific Container props, which helps an agent invoke the tool correctly.

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

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

The description is front-loaded with the core action, then compactly explains the node shape, automatic fields, and list/table special case. Every sentence contributes useful information without clutter.

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

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

Given the rich schema, annotations covering mutation semantics, and a nested node object, the description supplies the critical node shape and automation behavior. It is complete enough to call correctly, though it could mention sibling alternatives for fuller context.

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 all parameters. However, the description adds substantial meaning for the complex node parameter by sketching its expected shape and clarifying that parent and linkedNodes are managed automatically, going beyond the schema's terse 'Node definition' note.

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

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

The description clearly states the specific verb and resource: 'Insert one node under an existing parent.' It implies a single-node insertion, distinguishing it from a multi-node sibling like add_nodes, but it does not explicitly name or contrast with 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?

It provides context that the node is inserted under an existing parent, but it offers no explicit when-to-use guidance versus alternatives such as add_nodes, move_node, or patch_site_node, and no when-not 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 this is a non-read-only, non-idempotent, open-world write. The description adds value beyond that: the owner-only authorization requirement and the fact that re-inviting refreshes the invite link rather than failing. It does not cover whether an email is actually dispatched or what happens on invalid input.

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 the action, roles, and default front-loaded, followed by the permission constraint and the re-invite nuance. 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 simple three-parameter write tool with annotations covering the safety profile and no output schema, the description supplies the critical extras (owner-only, default role, re-invite semantics). Minor gaps remain around invitation delivery and failure modes, keeping it just below a 5.

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 id, role, and email are already documented, including the enum and the 'default editor' note. The description's role/default mention is essentially a restatement of schema content, 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 (invite) and resource (site member) by email, and enumerates the three roles with the default. This clearly distinguishes it from siblings like list_site_members and revoke_site_invite without needing their schemas.

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

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

Gives the key precondition ('Owner-only') and the re-invite behavior, which tells the agent it can call this on an existing member rather than erroring. It does not explicitly name the alternative tools (revoke_site_invite / list_site_members), so it falls short of a full when/when-not routing.

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

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

Annotations cover the read-only, closed-world safety profile, but the description adds a trait they do not: 'Counts as a use,' i.e. a metered/billing side effect. It also discloses the return shape (lib_* ids plus displayNames), which is valuable 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?

A single dense sentence that front-loads the resource, then the return shape, then the consuming use case, and closes with the metering note. 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 one-parameter list tool with no output schema, the description covers purpose, return values (ids and displayNames), the downstream consumer, and the usage-metering behavior. Only minor gaps remain, such as behavior on an invalid or non-library slug.

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 (slug) and schema description coverage is 100%, so the schema already carries the semantics; baseline is 3. The phrase 'a library block's' marginally narrows what the slug refers to (a block, not a page/site), but adds 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?

States a specific verb (list) and resource (a library block's node ids and displayNames), and it distinguishes itself from the nearby sibling list_blocks by scoping to nodes within one block. The cross-reference to apply_kit_block makes the boundary unambiguous.

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

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

It names the consuming tool (apply_kit_block's contentOverrides / propOverrides) and thus implicitly states when you need it: to look up valid keys before applying an override. No explicit when-not or sibling exclusions (e.g. vs. list_blocks) are given, 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the ~200 result cap and the category grouping of results. No auth or pagination details, but coverage is good for a read-only listing 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?

Two short sentences, front-loaded with purpose, scope and return shape before the sibling comparison. Slightly terse/telegraphic phrasing, 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?

For a read-only list tool with four fully-documented optional params and no output schema, the description supplies result cap, grouping and the key result fields, which is enough to call it correctly. Minor omission: it doesn't say what happens when no filters are supplied.

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

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

Schema description coverage is 100%, so the baseline is 3. The clause 'categories/styles arrays OR-match in one call' clarifies combination logic, but the schema already states 'OR-filter by several categories'; the description adds little 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 (List) and resource (library blocks), adds scope (~200 cap) and return shape (grouped by category: slug, name, tags), and explicitly positions itself against the search_blocks sibling. An agent can distinguish list vs. search 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?

Contrasts the two tools directly: this one is 'a broad menu' while search_blocks 'ranks and filters'. That gives both the when-to-use and the alternative to prefer for ranked/filtered results.

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 openWorldHint=false, covering safety. The description adds pagination semantics (cursor, hasMore, totalCount) and a default/max limit, which is useful beyond the annotations, but omits rate limits or ordering of results.

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 front-loading the return fields and paging behavior, then limits. No padding.

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?

A read-only list tool with no output schema; the description names returned fields (rows, nextCursor, hasMore, totalCount), which compensates for the missing output schema. But it leaves slug/site_id semantics and any filtering behavior unexplained, and gives no guidance on starting or ending paging.

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

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

Schema description coverage is only 25% (only cursor is documented in schema), so the description carries extra burden. It supplies the limit default (50) and cap (200), aiding the limit param, though slug and site_id remain undocumented.

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 a collection's rows) and clarifies it's a paged listing. Distinguishes from list_collections and from sibling writers like create_collection_rows/update_collection_row, though it doesn't name an alternative directly.

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 guidance. Nothing tells the agent when to page with this vs. get_collection or how to begin paging; the cursor param implies iteration but no instructions are given.

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 openWorldHint=false, so the safety profile is covered. The description adds meaningful value beyond them by disclosing the shape of the result set (the specific fields returned), which matters because there is no output schema. It stops short of describing filtering, ordering, or pagination 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 tight sentence with the action and scope front-loaded, followed by the field list. Every token carries information and there is no filler.

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

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

For a one-parameter, read-only list tool with no output schema, near-complete: the return fields are enumerated and the safety profile is covered by annotations. The only gap is the absence of any note on scope (single site vs all sites) or ordering of results.

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

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

Schema description coverage is 100% and the single site_id parameter is fully documented in the schema ('Site id. Pass it on every call.'). The description adds nothing further about the parameter, so the baseline 3 for a schema-documented parameter set is appropriate.

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

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

The description gives a specific verb ('List') and resource ('the site's collections'), and clarifies the domain as 'headless CMS' so the resource isn't confused with pages, nodes, or templates. It also enumerates the returned fields (id, name, slug, row and field counts, public flag), which further pins down what this tool is versus get_collection or list_collection_rows.

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 verb and resource — you call this to enumerate collections on a site — but there is no explicit statement of when to prefer it over get_collection (single item) or list_collection_rows (rows within a collection). No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety behavior is covered. The description adds useful return-field detail (node id, name, slug, home/404 flags), but does not discuss pagination, auth, 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?

Two tight sentences with zero waste. The output fields are front-loaded and the usage note follows immediately.

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

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

With no output schema, the description compensates by listing the key returned fields. It is complete enough for a one-parameter read-only list tool, though it omits any pagination or ordering details.

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 fully described in the schema as the site id that must be passed on every call. The description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the site's pages') and names the fields returned (node id, name, slug, home/404 flags). It is clearly not a mutation tool, but it does not explicitly distinguish itself from nearby siblings like list_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?

Gives a clear intended use: 'Use it to get page ids.' It does not state when not to use it or name alternatives, but the context is sufficient for a read-only listing tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds behavioral detail beyond that: the compact flag changes the returned shape to id + name only, and the result feeds set_theme. It omits pagination/ordering behavior, but for a small curated list that is minor.

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

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

Three short clauses, zero filler, front-loaded with what a preset is and followed by the two facts an agent needs: the compact output shape and the consuming tool.

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 states the return shape under compact, and it links the tool to its consumer set_theme. It does not explain the mood filter's semantics or whether presets are site-scoped, but the schema covers the filter and the tool is simple enough that little else is required.

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 mood, brief, and compact. The description restates the compact behavior ('id + name only') without adding syntax or format detail, so it neither compensates for nor exceeds 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 resource and its contents ('Curated theme presets (palette + fonts + tokens)'), which distinguishes it from siblings like list_templates and suggest_palettes. It is clear what the tool returns, though it never uses the verb 'list' explicitly in the description 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?

Names the downstream action explicitly ('set_theme({ preset }) applies one'), which tells the agent why to call this tool and what to do with the result. It does not, however, contrast itself with sibling discovery tools such as suggest_palettes or list_templates, so the routing is only partial.

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 openWorldHint=false, so the safety profile is covered without the description. The description does add value by disclosing the shape of the result (customized vs default, and whether each email sends), but says nothing about pagination, ordering, or whether a site id is truly required.

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

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

One dense sentence plus a two-word directive; nothing is wasted and the scope is front-loaded before the return-value detail. The trailing 'Start here' is slightly clipped but functional.

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-parameter listing tool with annotations covering safety and no output schema, the description conveys what is returned and that it is a starting point. It is nearly complete; only the missing hand-off to the singular/update siblings leaves a small gap.

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

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

Schema description coverage is 100% for the single 'id' parameter and cannot be improved on from the description. The description only implies a site scope via 'the site's,' while the schema notes 'Pass it on every call' even though the parameter is optional — the description does not resolve that tension. 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 ('List') plus a well-defined resource ('the site's transactional emails') with an enumeration of the covered types (receipt, welcome, gift card, sign-in link, downloads), so the agent knows exactly what comes back. It does not explicitly differentiate itself from the singular sibling get_site_email or from update_site_email, so it falls just short of 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?

'Start here' implies this is the discovery entry point before drilling into a specific email, which is useful implied guidance. However, it never states when to use get_site_email instead, or that update_site_email is the mutation counterpart, and gives no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the owner-only authorization requirement plus the fact that pending invites with ids are returned. It stops short of saying what happens on a non-owner call (error vs empty).

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-loading the scope and ending with the access constraint. No filler.

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

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

With no output schema, the description usefully sketches the return shape (members with roles, pending invites with ids) and access scope. Minor gaps: nothing about pagination/size of the list, and it doesn't address the oddity that id is not marked required despite "Pass it on every 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?

Only one parameter and schema description coverage is 100% ("Site id. Pass it on every call."), so the schema carries the meaning. The description adds nothing about the id parameter, matching the baseline 3 for high-coverage schemas.

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

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

States a specific verb (List) and resource (a site's members), and adds the distinguishing scope detail that the result also includes pending invites with their ids. An agent can separate this from invite_site_member and revoke_site_invite on content 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?

"Owner-only" gives a real precondition for when the tool can be called, but no alternatives or when-not conditions are named. Usage is implied rather than routed.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the exact field set returned, DFS ordering, and an approximate size (~2KB) that tells the agent the response is cheap to fetch. It does not mention pagination or depth limits, but the size hint is substantive.

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 payload shape front-loaded and the usage cue trailing. No filler, nothing repeated from the name or annotations.

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

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

With no output schema, the description does useful work by enumerating the returned fields and payload size, which is exactly what an agent needs to decide whether to call it. It falls short of fully complete only in not clarifying its relationship to the similarly named search_site_nodes/get_site_node siblings.

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 in the schema ('Site id. Pass it on every call.'). The description adds no additional meaning about the id, so the baseline 3 for schema-driven parameters 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 a specific verb and resource ('list' + node tree) and characterizes the payload precisely (fields returned, DFS order, ~2KB). It implies the relationship to siblings like search_site_nodes by describing the 'find ids and section order' use case, but never names or contrasts them 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?

'Use it to find ids and section order' gives implied usage context, which is more than nothing. However, it does not state when to prefer this over search_site_nodes, list_block_nodes, or get_site_node, so the agent must infer the boundary itself.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context by clarifying that results are scoped to the authenticated tenant and that the tenant is remote, but says nothing about pagination, ordering, or result size 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?

A single front-loaded sentence with the scope qualifier attached directly to the verb and resource. No filler, no redundancy with 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 parameterless read of a well-scoped resource with no output schema, the description covers the essentials: what is listed and whose sites they are. Minor gaps remain around result shape and whether an empty tenant yields an empty list, but nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies and the description cannot add parameter meaning that doesn't exist. Acceptable but not exceptional.

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 (sites) with an explicit scope: sites belonging to the authenticated tenant. This differentiates it from list_pages, list_collections, and other list_* siblings by resource. It does not, however, contrast itself with nearby tools like select_site or create_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?

No zero-parameter call is inherently discoverable, so implied usage is the ceiling here. The description gives no explicit when-to-use, when-not-to-use, or pointer to the related select_site sibling, leaving the agent to infer that this is the entry-point enumeration of tenants' sites.

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 openWorldHint=false, so the safety profile is covered. The description adds only that the templates are 'stock' (a built-in catalog), and says nothing about result size, pagination or ordering; with annotations carrying the load, this is adequate but thin.

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 core purpose is front-loaded ahead of the filter list. It is appropriately sized, though extremely terse for a tool with no other documentation.

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

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

The tool is simple (3 optional params, no nested objects), but with no output schema the description gives no sense of what a returned template looks like or how many come back. What is needed to invoke it is present; what is needed to use the results is not.

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

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

Schema description coverage is 100% and each parameter already documents itself with examples, so the schema does the heavy lifting. The description merely restates the three filter names and adds no syntax, combination or default semantics 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 and resource ('List stock templates'), and the word 'stock' scopes it to the built-in catalog rather than the user's own templates. It does not explicitly distinguish itself from siblings like pull_template or select_template, but the read-only listing 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?

'Filter by category, tag or q' describes available filters rather than when to use this tool versus alternatives. There is no guidance on when to reach for list_templates instead of select_template or pull_template, nor any note that filtering is optional.

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 non-read-only, non-idempotent, non-destructive, and the description adds real behavioral constraints beyond them: ROOT/page_home immovability and the subtree-cycle guard. It does not mention what happens to sibling ordering, whether position is honored on failure, or permissions required.

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

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

Two short sentences, front-loaded with the core action and then the restriction. No filler or redundant restatement of the title or 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?

No output schema exists, so return behavior is unstated, but the annotations carry the safety profile and the description supplies the key operational limits an agent needs before calling. For a 4-parameter mutation tool this is nearly complete, with only return/error behavior left implicit.

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

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

Schema description coverage is 100% and each parameter (id, nodeId, position, newParentId) is documented in the schema itself, so the description need not restate them. It adds no extra syntactic or ordering semantics beyond the schema, making the baseline 3 correct.

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 plus scope ('a node and its subtree') and the effect ('to a new parent'), which is more informative than the title. It distinguishes the move operation from sibling mutators like insert_node or delete_node implicitly via the verb, but never names an alternative 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?

Explicitly states when the tool cannot be used ('Can't move ROOT or page_home, or into its own subtree'), giving concrete negative conditions. It stops short of naming an alternative tool or describing prerequisites such as required permissions or a prior select_site 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false. The description adds value beyond them by disclosing atomicity, that patches are "applied in order to one fetched document," and the merge semantics (namespaced objects deep-merge, strings/arrays replace, Image src + content together, no children). It could be clearer that unsetProps/unsetClasses destroy data, but the behavioral surface is well covered.

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: purpose + rationale first, then the field enumeration and merge rules. Front-loaded and free of filler, though the second sentence is dense enough that it reads more like reference notes than 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?

For a bulk mutation tool with no output schema, the description covers the essentials an agent needs: atomicity, ordering, and the merge/replace rules that determine the write outcome. Combined with the fully documented schema and mutation annotations, nothing material 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 the baseline is 3. The description exceeds that by explaining the patch object shape and, more usefully, the semantics of each field (deep-merge vs replace, single-document ordering, "no children" constraint) that the schema only names. It adds real meaning over the field list.

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") and immediately distinguishes itself from the single-node sibling by contrasting its atomic bulk write with "parallel single patches [that] lose updates." An agent can tell this apart 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 over patch_site_node (atomicity; parallel single patches lose updates), which functions as an implicit when-to-use rule. It stops short of explicit when-not-to-use guidance, but the routing signal is strong and 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 flag destructiveHint=true and idempotentHint=false, and the description reinforces and enriches this: deep-merge vs. REPLACE semantics for strings/arrays, unsetProps branch dropping, the 'src shadows content' image pitfall, and the ROOT inject.head/footer caveat. This goes well beyond what annotations 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?

Front-loaded with the core scope and sibling differentiation, then packed with high-value semantics. It is dense and slightly run-on, but nearly every clause carries operational weight; only minor reordering into clearer sentences would help.

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 merge/replace behavior, deletion semantics, image pitfalls, and child-node exclusion. It omits error/rollback behavior and permission requirements, but nothing critical to invoking it correctly is missing.

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

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

Although schema coverage is 100%, the description adds real meaning the schema lacks: propsPatch deep-merges listed branches but strings/arrays replace, classNamePatch uses twMerge, typePatch swaps component type with isCanvas following, and it points to get_site_node to read current values before patching.

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

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

Names a specific verb+resource (patch one node) and immediately distinguishes scope from its sibling ('several: patch_site_bulk, one atomic write'). The classNamePatch/propsPatch/typePatch breakdown makes the operation concrete without opening the schema.

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

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

Explicitly routes multi-node edits to patch_site_bulk, states the when-not ('Children are not accepted'), and refers to get_style_reference({topic:'editing'}) for further guidance. Alternatives and constraints are named directly.

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

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

Annotations declare readOnlyHint so safety is covered, and the description adds valuable behavioral context beyond annotations: that an email with errors sends the default instead, and the list of returned sections. Good extra signal for a preview/render 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?

One tight sentence, front-loaded with the action and result. Minor parenthetical reference to the id parameter ('Pass it on every call.' is in schema, not description) keeps it efficient. 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 read-only preview with no output schema and fully documented parameters, the description covers what gets rendered and the error-path behavior. Adequate; an explicit when-to-use note against siblings would complete it.

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

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

Schema description coverage is 100%, so both parameters (id, kind enum) are already documented in the schema. The description adds no parameter-specific details 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 (Render) and resource (the saved email) with sample data, and names the specific outputs (subject, errors, warnings, plain text). This distinguishes it from get_site_email (fetch config) and update_site_email (mutate).

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?

Implied usage is preview/render before sending, but the description never explicitly says when to use it vs get_site_email or list_site_emails. No 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 destructiveHint=true and idempotentHint=true, so the agent knows this replaces live content and is repeat-safe. The description usefully adds the staging/commit model, but it doesn't warn that publishing overwrites the currently live site or note any authorization requirement, so it adds only moderate 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?

Two short sentences, zero filler, with the core action front-loaded and the staging constraint immediately after. Every sentence earns its place.

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

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

Covers the essential mechanics (commit point, optional static toggle) and there is no output schema to explain. However, for a destructive publish operation with no required parameters, it omits what happens to the existing live version and whether the id parameter is mandatory to target a site, leaving meaningful gaps.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds meaning: it explains the omit-to-leave-unchanged semantics for `static` ('omit to leave it'), which the schema does not state. The framing of `static` as delivery on/off also clarifies the renderer switch beyond the schema's terse wording.

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 clear verb+resource with scope: 'Publish the draft so it goes live.' The added note that 'Every write is staged until this runs' clarifies this is the commit point and implicitly distinguishes it from siblings like unpublish_site or update_page, though no sibling is named.

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 context in which this tool is required: staged writes only take effect once publish runs. That tells the agent when to invoke it, but it never names unpublish_site or any alternative, so exclusions are left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without the description's help. The description does add that the result is a 'decoded node tree' rather than raw template data, which is useful framing. It says nothing about size, pagination, or what happens for an invalid 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 front-loaded sentence with no filler or redundancy. 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?

For a one-parameter read-only tool with no output schema, naming the returned artifact (decoded node tree) is sufficient to call it correctly. The absence of guidance on slug sourcing or template discovery is the only meaningful 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% with a single documented 'slug' property, so the schema carries the burden. The description adds no format, source, or lookup semantics for the slug beyond what the schema already says. 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 concrete enough to distinguish it from list_templates and select_template. The phrase 'decoded node tree' is mildly jargon-y but conveys the payload. No sibling is named as an alternative.

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

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

The description gives no indication of when to use this tool versus list_templates, select_template, get_block, or list_site_nodes, all of which appear adjacent in the toolset. Nothing about prerequisites or exclusions 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavioral detail the annotations lack: what actually happens (portal set to null). However, it never resolves the 'remove vs disable' ambiguity it introduces, so it leaves a real question open.

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 waste. The only blemish is the ambiguous 'Remove/disable' pairing, which muddies rather than trims.

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 full annotations and no output schema, this is minimally sufficient. It still leaves open whether the operation is reversible and whether 'disable' differs from 'remove', which an agent might care about given the destructive flag.

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 coverage is 100%, so the schema already documents 'id' fully ('Site id. Pass it on every call.'). The description adds nothing about the parameter, which is the expected baseline here.

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

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

States a specific verb ('remove/disable') and resource ('the portal on a site') and even names the resulting state ('sets portal to null'). It is clearly distinguishable from siblings like set_portal or get_portal, though it doesn't explicitly name them.

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

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

No guidance on when to use this versus set_portal (to change) or get_portal (to inspect), and no prerequisites or warnings. The intended use can be inferred from the verb, but nothing is 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 destructive=true, idempotent=true and readOnly=false; the description adds two traits annotations cannot express: the owner-only permission requirement and the blast radius (existing members stay). It does not say whether revocation is reversible or what a success response looks like.

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 covering action, identifier, provenance, and permission with 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 two-parameter destructive tool with full schema coverage and no output schema, the description supplies everything an agent needs: the target, the id source, and the authorization constraint.

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, and the description earns above baseline by tying the invite_id to its source (list_site_members), clarifying which of the two ids is being revoked despite the terse 'by id' phrasing.

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 (revoke a pending invite) with scope (pending only, by id). An agent can distinguish it from invite_site_member and delete_site without opening either schema.

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

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

Tells the agent where the id comes from (list_site_members) and adds an eligibility condition (owner-only). It does not name an alternative tool or an explicit when-not-to-use case, 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 readOnlyHint=true and openWorldHint=true, so the lower bar applies; the description still adds real value by noting rendering happens in a 'real browser' and warning that fullPage can miss late paint. It does not describe the returned artifact (image/blob) or size limits, keeping it from a 5.

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

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

Two dense sentences, front-loaded with the core capability and then the practical capture advice. No filler or repetition of schema 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 6-param read-only tool with no output schema, the description covers the essential intent and the two most error-prone params (fullPage vs selector, width). It omits any note on the returned artifact or the id/path pairing requirement emphasized in the schema, so it is strong but not exhaustive.

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; the description goes beyond the schema by recommending selector-based section captures over fullPage and suggesting specific viewport widths (design width, 390), which is usable guidance the schema doesn't encode. It adds no format detail for id/path/height, so not a 5.

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

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

States a specific verb+resource ('Screenshot the DRAFT in a real browser') and immediately distinguishes itself from the audit siblings by explaining it is 'the only way to see compiled CSS, theme, state-driven UI and responsive layout'. An agent can tell this apart from audit_accessibility/audit_seo 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?

Gives concrete invocation guidance: 'Shoot sections with `selector`' and screenshot 'at the design width and at 390'. It also implies when not to use fullPage ('fullPage can miss late paint'). It stops short of naming an alternative sibling or stating prerequisites, so it is clear context rather than explicit when/when-not routing.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered. The description adds real behavioral value beyond that: it discloses the paginated return shape (one page of slugs), the degenerate-match behavior, and the fact that results include cloneable sections on this site.

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 return shape, then parameter notes, then the guide pointer — a sensible priority order. It is dense but almost every clause carries information; only the fallback explanation is slightly tucked away in the middle.

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 must describe returns — and it does (slugs, descriptions, tags, cloneable site sections). With 15 optional parameters and full schema coverage, the remaining gaps (sort defaults are in the schema, so fine) are minor; a mention of result-count/limits would push it to 5.

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 each of the 15 parameters. The description still adds meaning: it clarifies that q expects short layout phrases ('split hero'), that categories/styles are OR-filters, and that page paginates — useful signals not spelled out as filtering semantics in the schema.

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

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

States a specific verb+resource (search the block library) and instantly distinguishes itself from siblings by noting the return is 'one page of slugs with descriptions and tags (full structure: get_block).' An agent can tell it apart from get_block, list_blocks, and search_site_nodes 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?

Explicitly routes to alternatives: get_block for full structure and get_style_reference({topic:'blocks'}) as a guide. Also explains what the 'Fallback — not an exact match' case means. It stops short of stating when-not-to-use (e.g. browsing the whole library), so not a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one real behavioral fact — className filters return the full className rather than a truncated value — but omits pagination, result caps, ordering, and the fact the schema says id must be passed on every call. Adequate, 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?

Two sentences, zero filler, and the filter enumeration is front-loaded before the className-audit tip. Nothing repeats the title or wastes tokens.

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

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

For a read-only search tool with full schema coverage and no output schema, the description covers what can be matched and one concrete use case. Missing result-set behavior (limits, paging, whether multiple filters intersect) keeps it short of complete.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema (including the classRegex example 'py-(8|12)'). The description restates the filter mapping without adding syntax or precedence rules, so the baseline of 3 applies.

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

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

States a specific verb (find) plus resource (nodes) and enumerates the three filter dimensions (q, type, className), so the agent knows exactly what matching is supported. It doesn't explicitly contrast with list_site_nodes or get_site_node, so sibling 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?

One usage cue is given — className filters are 'for site-wide class audits' — which is genuinely actionable. There is no when-not guidance, no mention of the alternative list_site_nodes for unfiltered enumeration, and no note that filters combine (AND vs OR).

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false; the description adds the crucial non-obvious trait that the server does not retain the selection between calls, which directly affects how an agent must call it. It also notes the template-clearing side effect. It stops short of 5 because it doesn't explain what the 'active site' affects downstream or what the call 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?

Two short sentences, front-loaded with the primary action and followed by the critical calling constraint. Every clause earns its place with no filler.

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

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

For a one-parameter tool with no output schema and an annotation-covered safety profile, the description covers the essential behavior and the persistence caveat. The remaining gap is what 'active site' actually influences for subsequent calls, which is left implicit.

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

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

Schema description coverage is 100% for the single `id` parameter, so the schema already carries the semantics and baseline 3 applies. The description only reinforces that `id` must be supplied on every call, adding no format or value-level 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+resource ('Set the active site for this session') and adds scope ('session') plus a side effect ('clear any active template'), which implicitly separates it from select_template. It does not explicitly name a sibling for routing, so it falls just short of the top of the range.

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 one concrete usage rule ('still pass `id` on every call') because state is not persisted, which is genuinely useful. However, it never states when to use this versus select_template or other session-affecting tools, and gives no exclusions, so guidance is implied rather than explicit.

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

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

Adds meaningful context beyond the annotations: it discloses a side effect ('clears the active site') and the authorization requirement, neither of which appears in the structured fields. The readOnlyHint=true annotation is in mild tension with a session-state mutation, but since no persistent resource is modified, this is not a contradiction.

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 a semicolon-delimited structure: the action and session scope come first, the side effect second, and the permission constraint last. Nothing is wasted.

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

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

For a single-parameter, non-output tool, the description covers the action, its session-wide effect, the side effect on the prior site selection, and the access constraint. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the single 'slug' parameter is fully documented in the schema, so the baseline is 3. The description adds no format or validation detail beyond what the schema already provides.

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

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

States a specific verb and resource ('Make a template the edit target for this session') and immediately scopes the downstream effect ('editing tools then act on it'). It also distinguishes itself from the site-selection sibling by noting it 'clears the active site', so an agent can tell it apart from select_site without opening either schema.

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

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

Gives clear context for use (prior to editing tools that operate on a template) and states the permission gate (admin or tenant owner/editor). It stops short of naming the alternative (select_site) as an explicit either/or, so the routing decision is implied 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds non-redundant context: what remove:true does, that rows persist, the required stripe_connect auth, and the minor-units charging convention.

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 and front-loaded: the core action leads, followed by the mode-dependent charging rules. Telegraphic style packs real information per sentence, though the parenthetical and em-dash clauses make it slightly harder to parse on first read.

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, it covers prerequisites, the destructive/stop path, and the two primary charging modes. Minor gaps remain around variants_field and inventory_field, which are only defined in the schema, but overall it is complete enough to invoke 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 genuinely adds semantics beyond the schema — the minor-units convention (2500 = $25.00), the requirement that the collection carry that number field, and the either/or relationship between price and price_id_field.

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 ('Make a collection sellable through Stripe') and clarifies the remove:true inverse, which effectively distinguishes it from siblings like stripe_connect and create_collection. It doesn't explicitly name a sibling to avoid, but the scope is concrete enough to 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?

Gives a clear prerequisite ('Needs stripe_connect') and a concrete decision rule between the two pricing modes (price field in minor units vs. price_id_field). It lacks explicit when-not guidance and doesn't address variants_field/inventory_field, so it stops short of 5.

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

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

Annotations already declare destructiveHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds real context beyond that: attaching does not publish, the returned DNS values are project-specific, and it decodes the two failure modes (409 = variant on another Vercel project, 403 = plan domain limit). It doesn't cover replacement semantics if a different domain is attached later, which keeps it from a 5.

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

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

Three tightly packed sentences, front-loaded with the action and its outcome, then the lifecycle note, then error decoding, then a detail pointer. Every clause earns its place and nothing is redundant.

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

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

For a mutation tool with no output schema, the description covers the return (DNS records to create), the non-effect (not published), the detach path, and ambiguous error codes. An agent has everything needed to call it and interpret common failures.

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 redirectMode enum semantics and the apex/www registration behavior, so the schema already carries the parameter burden. The description reinforces the apex-or-www input form but adds no syntax or format detail beyond it. Baseline 3 is correct.

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 ('Attach a custom domain'), names the accepted shapes (apex+www pair, single subdomain), and distinguishes itself from the clear_domain sibling that detaches. An agent can identify the operation and its scope without opening the schema.

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

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

Explicit about when to use it (attach), the alternative to use instead for the inverse operation (clear_domain detaches), a key non-obvious condition ('attaching doesn't publish' — publishing is a separate sibling call), and a pointer to get_style_reference for deeper detail. Nothing is left to inference.

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