Fabrement

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

No annotations are provided, so the description carries the full burden, and it does disclose real side-effect behavior: templateId 0 unbinds, and without a matching rule the slot falls back to the archive record's own blocks and is empty only where no record exists. It omits permissions/auth and reversibility, but the fallback semantics are 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?

Front-loads the core action, then the context enumeration, then the fallback and rules. It is dense and the parenthetical is heavy, but each clause carries operational information rather than 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?

An output schema exists, so return values need not be explained. For a two-param binding tool the description covers the format, the unbind convention, the fallback behavior, and the prerequisite doc; only permission/error behavior is left unstated, which is a minor gap.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema, including the 0-unbind convention and the context format. The description mostly restates those values; its only added value is pointing at list-archives as the source of the context value. 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: 'Bind a site template to an archive view.' This is clearly separable from the sibling fabrement-assign-template-pages (archive views vs. pages), so an agent can route correctly without opening the schema.

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

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

Gives concrete when-to-use context: the template's contentSource 'wants a rule for the same context (save-archive-page + save-template)', and explicitly directs reading the template-contract skill doc before the first call. It does not, however, explicitly contrast with the sibling assign-template-pages, so the alternative is only implicitly distinguished.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral trait: replace is destructive — it 'releases every other record that had it'. It also notes the tool works on any public type, not just template-default ones. It stops short of stating permission requirements or rate limits, but the destructive semantics are clearly surfaced.

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 the required-mode constraint, then the destructive replace warning, then scope and alternatives. Dense but every clause carries information; the trailing Rules line is a useful prerequisite rather than filler. Slightly heavy for its size but well-structured.

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

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

For a complex, high-stakes mutation tool with no annotations, the description covers purpose, destructive behavior of replace, scope, prerequisites, and the relevant siblings. An output schema exists, so return values need no explanation. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including the mode enum and the pageIds interpretation. The description reinforces the mode semantics but adds little beyond what the structured fields already say, 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 (assign/give/take away a template) acting on records, and immediately routes the agent to siblings by naming list-template-pages and set-default-template. An agent can distinguish this from set-default-template and list-template-pages without opening the schema.

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

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

Gives explicit when-to-use for replace ('use it when you know the whole set'), distinguishes add/remove vs replace, and names the alternative for the whole-type case ('use set-default-template instead'). It also states prerequisites: list-template-pages first and read the template-contract skill doc before the first 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?

With no annotations, the description carries the full burden and does so: it discloses that the created record is empty, that it renders nothing until submit-version, that a taken name is refused with the holding block named in the response, and that title/slug validation applies. It also prescribes the reporting format (title, not id). This is unusually rich behavioral context for a mutation 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?

Every sentence carries real information and the most critical constraint (empty record, search first) is front-loaded. However the density, non-standard '{search}' placeholder notation and heavy dash usage make it harder to parse than necessary.

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

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

An output schema exists so return values need not be explained, and the description still covers creation semantics, collision behavior, validation, prerequisite contract docs, and reporting format. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and both parameters already carry detailed descriptions including the slugify rules and enum meanings, so the description is largely restating what the schema provides ('type "header"/"footer" makes a site-template part'). It adds no syntax or format detail beyond the schema, 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 and resource ('Create an EMPTY block record and get its ids') and immediately clarifies scope: the record renders nothing until submit-version. It distinguishes the tool from siblings like list-blocks and submit-version by naming them, so an agent can tell Create from List from Submit 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?

Explicit routing: 'SEARCH FIRST, THEN DECIDE: list-blocks {search}', plus a nuanced rule for when a similar existing block is a 'question, not an answer'. It names the alternative (reuse vs. new), states when to defer to the person ('Ask the person when it is ambiguous'), and lists prerequisites (read the matching skill doc before the first 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?

No annotations exist, so the description carries the full burden and does so: it discloses the return shape, that duplicates are silently accepted, what is derived from the markup (mail body, Reply-To from the first required email tag, attachments), what is refused (query-var control names, unknown message keys), and a hard 40-control limit. These are non-obvious behaviors an agent cannot infer from the schema.

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

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

Dense and mostly purposeful, but the highest-stakes warning (duplicate titles are not refused) is buried after a lengthy markup lecture, and the markup/derivation explanation substantially repeats what the schema's `template` property already says. Front-loading the duplicate warning would let the reader act on it before skimming.

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?

Strong coverage for a mutation tool with no annotations and an output schema: prereqs, side effects, refusals, limits, and the follow-up call are all present. It stops short of stating permission/capability requirements or what failure looks like when CF7 is inactive, which an agent may still need.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a 4 by adding semantics the schema doesn't give — the returned form id is the default of a block's `form` attribute, and the markup drives derived mail/Reply-To/attachment behavior. It loses a point because much of the `template` guidance mirrors the schema's own long template description rather than adding to it.

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

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

States a specific verb and resource ('Create a Contact Form 7 form') plus the enabling precondition ('CF7 must be active'), and immediately distinguishes itself from update-cf7-form. An agent knows exactly what this does and which sibling handles the other case.

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 when-to-use and when-not-to: 'LIST-FORMS FIRST' with the concrete consequence spelled out (duplicate titles are not refused, leaving two identical forms), and it names both alternatives — reuse the existing one or call update-cf7-form. It also gates first use on get-skill-doc {id:"forms-contract"}.

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

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

With no annotations, the description carries the full burden and does well: it discloses a side effect (it selects the new design system for this site), a gating precondition, and a mandatory prerequisite read (get-skill-doc "design-system-contract" before the first call). It stops short of describing failure/conflict behavior or permissions, keeping it just below the top.

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

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

Front-loaded with the core action, then the precondition, follow-up tool, and exclusion in rapid order; every sentence carries routing or gating information. Slightly dense with em-dashes, but nothing is wasted.

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

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

For a creation tool with an output schema (so return values need no explanation), the description supplies the precondition, the mutation side effect, the follow-up tool, and the required contract doc. 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?

Schema description coverage is 100%, so both name and copyCurrentTokens are already documented in the schema; baseline is 3. The description adds workflow context but no additional meaning about the parameters themselves, so it does not exceed the baseline.

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

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

States a specific verb+resource ("Create a NEW design system in the project") with the emphasized scope that it is a new/only-one entity. It also distinguishes itself from the get-design-system and save-design-system siblings, so an agent can place it 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 an explicit precondition (only when get-design-system reports hasDesignSystem:false), names the follow-up tool (then fill it with save-design-system), and states a hard exclusion ("Never to 'start fresh' beside an existing one"). When-to-use and when-not-to-use are both 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?

With no annotations, the description carries the burden and does meaningful work: it discloses the uniqueness constraint on name, the 4-level nesting limit, and that items are persisted as custom links rather than references, plus the menuId binding contract. It omits auth/permission requirements and side effects, but the material behavioral facts an agent needs are present.

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

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

Front-loaded with the core action, then constraints, then the sibling pointer and the prerequisite rule. Dense but every clause carries information; the "Rules:" fragment is slightly telegraphic but not wasteful.

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

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

An output schema exists so return values need no explanation, and the schema documents both parameters. Combined with the binding semantics and prerequisite call, the definition is sufficient for correct invocation; only deeper behavioral notes (permissions, idempotency) 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 coverage is already 100%, so 3 is the floor, but the description earns above baseline by clarifying that name must be site-unique, that items are custom links nested up to 4 levels, and how menuId binding relates to the created menu.

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 (navigation menu) and adds differentiating detail: unique name, items nested to 4 levels, stored as custom links, and consumed by header/footer blocks via menuId. An agent can separate this from list-menus/update-menu/delete-menu without opening schemas.

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

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

Explicitly names an alternative and the condition that selects it ("list-menus first to reuse one") and adds a hard prerequisite (read the site-assets-contract skill doc before the first call). It stops short of full when/when-not framing but the routing guidance is concrete.

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

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

With no annotations, the description carries the behavioral burden, and it does disclose meaningful traits: the type is stored by Fabrement and re-registered on every request rather than relying on a plugin, plus the archive-URL side effect for public types with hasArchive. It stops short of stating permissions, idempotency on slug collision, or whether registration is reversible.

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 the key prerequisite, then the rules. Dense and mostly waste-free, though the telegraphic 'to dress with' phrasing and stacked arrow-style references cost a little readability.

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

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

For a 12-parameter creation tool (output schema present, so return values need no explanation), the description covers the storage model, the mandatory prerequisite doc, sibling routing, and a parameter-interaction side effect. Minor gaps remain around failure modes (duplicate/reserved slug) and reversibility, which the schema's uniqueness note only partly covers.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: that 'public' combined with 'hasArchive' produces an archive URL that must be dressed via other tools. That interplay is genuine semantic value beyond the per-field descriptions.

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

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

Names a specific verb ('Register a NEW custom post type') plus the resource, with concrete examples (Book, Project, Event). The emphasis on NEW cleanly distinguishes it from the sibling fabrement-update-post-type, and the storage/registration note differentiates it from any third-party plugin approach.

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

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

Explicit sequencing is given: 'list-post-types first' before creating, and 'get-skill-doc {id:"content-model-contract"} — read it before the first call.' It also routes the agent onward for the archive case via save-archive-page + assign-template-archive, so the ordering of related tools is unambiguous.

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

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

With no annotations, the description carries the full burden and delivers the most consequential trait: hierarchical is immutable after creation, and storage is first-party rather than plugin-backed. It does not cover permissions, rate limits, or failure behavior, but the irreversibility warning is the single fact an agent must know before calling.

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 purpose and the immutability warning come first, then the dedup and sequencing guidance. The trailing 'Rules:' fragment is slightly clipped but still earns its space by pointing at the governing doc.

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 9-parameter creation tool with an output schema (which removes any need to describe return values), the description covers purpose, prerequisites, ordering, and the one irreversible design decision. Only operational concerns such as required capability or conflict handling are untouched.

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 of the 9 parameters already carries a detailed description, including the same immutability note for hierarchical. The prose adds no parameter syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Register a NEW taxonomy') plus its scope ('attached to post types'), which cleanly separates it from update-taxonomy, create-term, and create-post-type. The NEW qualifier and the 'stored by Fabrement, no third-party plugin' clause pin down exactly what is made.

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 sequencing: run list-taxonomies FIRST with the rationale (duplicate taxonomies split content), then fill the taxonomy with create-term, and read get-skill-doc {content-model-contract} before the first call. This is when-to-use, prerequisite, and follow-up guidance in one place.

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

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

With no annotations, the description carries the full burden and does well: it discloses idempotency ('an existing name is returned with created:false'), the refusal of a non-existent parent, and a required doc prerequisite. It omits permission/auth requirements and whether creation is reversible, keeping it short of 5.

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

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

Three short sentences plus a one-line rule, with the core action front-loaded. The 'Rules:' line is slightly jarring in phrasing but earns its place by pointing at the prerequisite doc.

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?

An output schema exists, so return values needn't be explained, yet the description still clarifies the created:false outcome. It covers the mutation's key behavioral facts (idempotency, parent validation, prerequisite) and is complete enough to call correctly, though explicit permission requirements 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 100%, so every parameter is already documented; baseline 3 applies. The description adds the validation semantic for 'parent' (nonexistent parent is refused), but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Add a term') plus the scope ('any taxonomy, category and post_tag included'), which clearly separates it from create-taxonomy (which makes the taxonomy itself) and update-term/delete-term. An agent can identify the correct tool 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?

Provides concrete operating context: idempotent behavior on duplicate names, the prerequisite to read get-skill-doc {id:"content-model-contract"} before the first call, and the valid-parent condition. It does not explicitly contrast against update-term or set-post-terms, so 5 is not reached.

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

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

Beyond destructiveHint=true, it discloses irreversibility, the downstream consequence on views (an EMPTY slot), and the required prerequisite action, plus an ownership constraint. This is exactly the kind of context annotations cannot carry, so the description meaningfully extends the safety profile.

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

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

Front-loads the verb, resource, and irreversibility in one sentence, then states the downstream risk and the prerequisite. No filler; every clause carries operational meaning.

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

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

An output schema exists so return values need no explanation, and the destructive annotation is fully amplified by the description. Prerequisite, ownership scope, and consequence of forcing are all present, leaving nothing an agent needs to call this 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 both parameters are already documented, which sets the baseline at 3. The description adds a semantic layer by constraining the target to bundles 'you authored' and reinforcing the force-delete consequence (empty slot), giving slight value over 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 ('Delete an archive bundle') with an ownership scope ('you authored'), and the 'archive bundle' framing cleanly distinguishes it from the many sibling delete tools (delete-template, delete-content, delete-single-page). An agent can route to 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?

Gives a concrete prerequisite ('re-wire or unbind the template first') and mandates reading a contract doc via get-skill-doc before the first call. It stops short of explicitly contrasting itself with sibling delete tools, but the precondition is clear and actionable.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond by disclosing that deletion is irreversible, that the block source is destroyed and must be rewritten from nothing, that the operation is refused rather than forced when in use, and that the refusal response names the blocking pages/templates. This is exactly the context annotations cannot carry.

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

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

The irreversibility warning and the refusal condition are front-loaded and every sentence carries new information. Slightly dense with parentheticals, but nothing is 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?

For a one-parameter destructive tool with no output schema, the description covers the safety profile, the blocking condition, the non-recoverability, the confirmation requirement, and the prerequisite doc read. Nothing an agent needs to call it safely 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?

Single parameter with 100% schema description coverage (blockId, including its origin from list-blocks), so the schema already does the work. The description adds no additional syntax or format detail, making the baseline 3 appropriate.

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

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

States a specific verb (delete) and resource (block) with scope — backend, filesystem, and site — which cleanly separates it from siblings like fabrement-delete-content or fabrement-delete-synced-pattern. An agent can identify 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?

Explicit when-not conditions (refused while any page places it or a template uses it as header/footer), the remediation ('remove it there first'), the absence of any force override, and a required user confirmation before calling. It also names the prerequisite doc lookup, which is real routing guidance.

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

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

Annotations already declare destructiveHint=true, so the description's job is to add specifics beyond that flag. It does: explicit irreversibility plus the downstream consequence that blocks rendering the deleted form render empty, which is real context an agent can't get from the annotation. It stops short of covering failure behavior (nonexistent id, forms in use elsewhere) or required capabilities.

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 plus a one-line prerequisite rule, with the irreversible effect and the confirm-first caution both front-loaded before procedure. Nothing is 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?

For a one-parameter destructive tool with annotations and an output schema, this covers effect, irreversibility, confirmation, and the required skill doc. Only minor gaps remain, such as behavior when the id is unknown or the form is referenced elsewhere.

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?

Single parameter with 100% schema coverage; the schema already says 'Form id from list-forms', and the description adds no format, sourcing, or validation detail beyond that. Baseline 3 is appropriate when the schema fully carries the parameter.

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

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

States a specific verb and resource (delete a Contact Form 7 form) and immediately scopes the effect ('a block rendering it shows nothing afterwards'), which distinguishes it from update-cf7-form and the other delete-* siblings. An agent can tell what this does and what it touches without opening the schema.

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

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

Gives two concrete operating conditions: confirm with the user first, and read the forms-contract skill doc before the first call. It doesn't explicitly contrast with update-cf7-form, but the destructive-vs-modify distinction is self-evident from the name, so the missing alternative is low-cost.

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

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

Annotations declare destructiveHint=true, so the safety profile is known; the description still adds real value beyond that: the force:true gate, the consent requirement, the cascade scope note that child blocks survive, and the content-contract prerequisite. It does not describe the failure/error behavior for a non-forced call, which would have pushed this higher.

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 plus a rules line; the permanence/force constraint is front-loaded and the alternative is given in the same breath. 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 an output schema present, return values need no explanation; the description covers the destructive semantics, the alternative path, a side-effect caveat, and a prerequisite. Nothing an agent needs to invoke this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces force:true as a hard requirement tied to permanence and situates it against the trash alternative, adding contextual meaning beyond the schema's per-field text, though it largely restates what the schema already says.

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

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

States a specific verb (delete) and resource (page/post/custom record) plus the critical scope modifier 'PERMANENTLY'. It explicitly contrasts itself with set-content-status, so an agent can distinguish it from the nearest sibling without opening either schema.

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

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

Gives explicit preconditions ('only when the user said so'), names the alternative tool and the exact call shape to use for the recoverable case (set-content-status {status:"trash"}), and points to the prerequisite skill doc before the first 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 only declare destructiveHint=true, so the description carries real weight: it enumerates the exact dependency classes that block deletion, states that the answer names which one, and spells out the consequence of forcing ('every place naming it then renders nothing') plus the `usedBy` field that lists them. That is disclosure well beyond the annotation.

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

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

Front-loaded with the action, then the refusal rule, then the force consequence, then the doc prerequisite — a logical order with no filler. The em-dash-heavy middle sentence is dense and takes a second read, which keeps it just short of a 5.

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

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

For a destructive two-parameter tool with no output schema, the description covers the blocking conditions, the override, the aftermath, the confirmation requirement, and the pre-call doc — the only return field an agent needs (`usedBy`) is even named.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: `force` isn't just 'delete even while it is used' — it explains the downstream render failure and the `usedBy` report, and it conditions `force` on user confirmation.

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 with scope: 'Delete an icon from the site library and the project copy.' An agent can distinguish this from save-icon, get-icon and list-icons without opening any schema, and the description immediately names the effect on the project copy as well as the library.

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

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

Gives explicit when-not conditions (refused while an installed block, render bundle, icon field, options page choices, or live block version names it) and the escape hatch (force:true) with the caveat 'Confirm with the user before forcing.' It also imposes a prerequisite: read the icons-contract skill doc before the first 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?

Beyond destructiveHint=true, it discloses that deletion is permanent by default because media has no useful trash, that it succeeds even while referenced by a block attribute, featured image, or site icon, and that usedBy enumerates those references. This is exactly the behavioral context an agent needs before a destructive call.

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

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

Two sentences and a rules line, with the permanence caveat front-loaded ahead of the in-use warning. Dense and largely waste-free, though the trailing 'Rules:' fragment reads slightly clipped.

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?

An output schema exists (covering usedBy return data), annotations carry the destructive hint, and the schema fully documents both parameters. The description adds the domain contract reference and the user-notification duty, leaving nothing an agent needs in order to call this safely.

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%: force's default-true/trash semantics and mediaId's 'see list-media' pointer are already documented in the schema. The description's 'permanent by default' phrasing echoes the schema rather than adding new syntax or format detail, so the baseline 3 is appropriate.

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

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

The description states a precise verb+resource ("Delete a media item") and reinforces scope with the permanence-by-default parenthetical and the note that it fires even when the item is in use. An agent can distinguish it from the many other delete-* siblings (delete-icon, delete-block, delete-content) 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?

It supplies a clear precondition (read the site-assets-contract skill doc before the first call) and a downstream action (tell the user which places lose the image). It does not, however, compare when to reach for this tool versus adjacent alternatives such as uploading a replacement or trashing instead of forcing, so exclusions are absent.

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 the description reinforces it with '(irreversible)' while adding genuinely new behavior: the cascade to menu items and the fallback semantics for a block bound to the menu. That side-effect disclosure goes beyond the annotation, though permissions/authorization requirements are 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?

Front-loads the action and its irreversibility, then the cascade/fallback consequence, then the confirmation rule and prerequisite. Efficient and ordered by importance, though the trailing 'Rules:' fragment is terse and slightly abrupt.

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-parameter tool with an output schema already covering return values, the description supplies everything else an agent needs: reversibility, cascade behavior, binding fallback, user-confirmation trigger, and a required pre-read. 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 coverage is 100% and the single parameter's own description ('Menu id from list-menus') already tells the agent where the value comes from; the prose adds no syntax, format, or constraint beyond it. Baseline 3 is appropriate when the schema fully carries the parameter.

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

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

States a specific verb and resource ('Delete a navigation menu') plus the cascade scope ('and its items'), which distinguishes it cleanly from update-menu, create-menu, and the other delete-* siblings. An agent knows exactly what this tool targets without opening the schema.

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

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

Gives real conditional guidance ('Confirm with the user when it is in use') and a prerequisite workflow step (read the site-assets-contract skill doc before the first call). It stops short of naming alternatives such as update-menu for non-destructive edits, so it is clear context without explicit 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 only declare destructiveHint=true; the description goes far beyond that by spelling out irreversibility, cascading loss of values, fields and tabs in all languages, the empty-state outcome of recreating the same slug, and the downstream null-read effect on templates. This is exactly the recovery/implication context an agent needs before a destructive call.

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

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

Front-loaded with the destructive warning and cascading effects, then alternatives, then prerequisites. Dense but each sentence carries a distinct constraint; the trailing 'Rules:' line is slightly bolted-on rather than integrated, which keeps it off a 5.

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

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

For a destructive two-parameter tool with no output schema, the description covers irreversibility, blast radius, downstream effects, alternative tooling, and the mandatory skill-doc read. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so both slug and expectedRevision are already documented in the schema; the description adds no syntax or format detail beyond what is there. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('remove an options page'), then extends the scope precisely: every value stored on it, in every language, plus its menu entry, fields and tabs. It also distinguishes itself from the sibling save-options-page by contrasting what each does with field values.

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 when-not-to-use guidance ('To drop only some fields, save-options-page without them instead'), a pre-flight check ('check what reads it first', with the exact API call fabrement_get_option), a prerequisite skill doc rule, and a hard usage condition ('Ask the user and name the page before calling this' via expectedRevision).

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?

destructiveHint=true is already in annotations, but the description goes well beyond it: posts are orphaned rather than deleted (and recoverable only under the SAME slug), the archive page and fields file are deleted while field values persist, calling on an already-gone slug cleans up a leftover fields file, the archive template binding is dropped, and render bundles are surfaced via renderFiles with a warning that one bundle may serve several types. This is rich, non-obvious operational detail.

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 somewhat parenthetical, but nearly every sentence carries a distinct constraint (orphaning, refusal, force, renderFiles, slug-stability). Front-loaded with the core delete action, though the parenthetical asides make it harder to scan than it could be.

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

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

For a destructive, irreversible-feeling operation, the description covers consequences, refusal paths, recovery conditions, collateral artifacts (archive page, fields file, template binding, render bundles), and even lightly previews the response ('the answer names what was left in place'). An output schema exists, so return values need not be detailed, and nothing an agent needs to call this safely 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 reinforces force's semantics ('pass force:true if that is meant') and the slug's origin, but adds essentially no syntax or format detail beyond what the schema already states for both parameters.

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

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

States a specific verb and resource ('Unregister a custom post type Fabrement created and drop its definition') and explicitly distinguishes itself from siblings: it is 'NOT a way to rename one' and points to update-post-type for that. An agent can pick it apart from create-post-type, update-post-type, and the other delete-* tools 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?

Extensive routing: when to use (existing Fabrement slug), when not to (renaming → update-post-type with {rewrite}/{singular,plural}), refusal conditions (core/plugin types, posts still existing), the force:true escape hatch, and a pre-flight instruction to read the skill doc and confirm with the user. This is the strongest category for this definition.

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?

destructiveHint=true already flags the mutation, but the description adds value beyond it: the operation is irreversible, a referencing template degrades to the page's own content, and a contract document must be consulted first. It does not, however, cover auth/permission requirements or what the response returns.

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

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

Two compact sentences with the irreversible consequence and the cascade behavior front-loaded, followed by a clearly delimited 'Rules:' directive. No filler and nothing buried mid-sentence.

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

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

Covers the destructive nature, the cross-entity fallout, the required prerequisite doc, and the ownership restriction. With 100% schema coverage, annotations present, and an output schema declared, nothing material is left for the description to carry.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top by explaining the state that the 'force' flag interacts with (a template still pointing at the page), complementing the field-level text about the empty slot that results.

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

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

States a specific verb (Delete) and a precisely scoped resource (a single-page bundle you authored), which tells the agent exactly which entity class is affected among the many delete-* siblings. Ownership scope ('you authored') further narrows the target.

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 preconditions: check get-template first when a template points at the page, and read the single-page-contract skill doc before the first call. It stops short of naming a sibling alternative (e.g. delete-template vs delete-content) or stating when deletion is the wrong choice.

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

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

Annotations supply destructiveHint=true, so the safety profile is already declared; the description adds substantial context beyond that — permanence, the two distinct dependency-based refusal conditions, the consequence of force:true (places render nothing), and that inner blocks survive. It stops short of stating auth/permission requirements, but the dependency semantics are unusually 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?

Front-loads the destructive nature and the resource, then layers preconditions. Some sentences are dense (nested em-dash clauses around force:true), but nearly every clause carries distinct behavioral information rather than 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?

An output schema exists, so return-format detail is unnecessary, and the description still notes that refusal responses list the blocking placements. Combined with covered preconditions, force semantics, and the skill-doc prerequisite, an agent has everything needed to call this 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 50%; the force param is documented in the schema, but the description adds real meaning beyond it by explaining the conditional effect ('those places then render nothing') rather than just 'delete even while records place it'. patternId is undescribed in both places, though it is an unambiguous identifier, so the gap is minor.

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 global block (synced pattern) PERMANENTLY'), and the parenthetical alias plus the permanence qualifier distinguish it from generic sibling deleters like delete-block and delete-template. An agent can identify the target and the irreversibility without opening the schema.

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

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

Explicitly covers when-not-to-use: refused while a template's header/footer uses it (routed to save-template first) and refused while any record places it (routed to removing placements or force:true). It also names the prerequisite call, get-skill-doc, to run before the first invocation. This is about as prescriptive as usage guidance gets.

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 supply destructiveHint=true, so the description carries the disclosure burden and does well: terms persist in the DB and reappear on same-slug re-creation, different-slug re-creation leaves terms orphaned and the taxonomy empty, and bound archive templates get unbound and listed in the answer. It stops short of stating irreversibility or permission requirements, but the consequences of the mutation are clear.

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 consequence, and every sentence adds distinct information (refusal rule, term persistence, rename pitfall, template unbinding). It is dense but slightly long, with the rename discussion spanning several clauses that could be tightened.

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 one-param tool with an output schema already covering the returned unbinding list, the description supplies everything needed: what is refused, what survives, the rename pitfall, and a required pre-read doc. No material gap remains.

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% for the single slug param, so baseline is 3; the description earns above baseline by attaching critical semantics to slug values (same slug preserves terms, a changed slug orphans them). That is genuinely additive to the schema's terse 'from list-taxonomies' 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?

States a specific verb (unregister) and resource (taxonomy) with an explicit scope constraint: only taxonomies Fabrement created, core/plugin ones refused. It is immediately distinguishable from sibling delete-term and update-taxonomy 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?

Explicit when-not (core/plugin taxonomies are refused) and names the correct alternative for a different intent: keep the slug and use update-taxonomy {rewrite}/{singular,plural} to change URL or name. It also routes the agent to get-skill-doc before the first 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 only supply destructiveHint=true; the description goes well beyond that by disclosing exactly what is destroyed and what survives (pages fall back to post-type default, header/footer global blocks stay), the refusal behavior, and the force override. This is unusually rich for a delete tool.

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

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

Front-loads the destructive action and its consequences in one dense sentence, then the refusal/force semantics, then the prerequisite rule. Every clause carries information, though the skill-doc rule adds a second call the agent must remember.

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?

An output schema exists so return values needn't be detailed, and the description still notes the answer explains the refusal reason. Preconditions, irreversibility, and override are all covered for a destructive 2-param 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 coverage is 100% and the schema already documents both force and templateId, including the reference conditions force overrides. The description restates force's effect rather than adding new syntax or format detail, 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?

Opens with a specific verb+resource ("Delete a site template") and immediately flags irreversibility, which distinguishes it cleanly from the many other delete-* siblings by resource type.

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 precondition clearly (refused while anything still points at it) and the escape hatch (force:true to delete anyway), plus a prerequisite to read the template-contract skill doc first. It doesn't name a sibling alternative, but the when-to-use condition is 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?

destructiveHint=true is already declared, but the description goes well beyond it: what survives a delete (posts, children), the two distinct blockages and why each exists ('that binding would otherwise stay pointing at nothing'), and that force leaves a rule dangling. This is exactly the context annotations cannot convey.

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

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

Front-loaded with the effect, then the refusal cases in order of escalation. Dense but every clause carries information; only the trailing 'Rules: get-skill-doc' line reads as an appended afterthought rather than part of the flow.

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, refusal-prone tool this covers side effects, pre-flight checks, both failure modes with remedies, and escalation via force. An output schema exists, so no return-value explanation is needed.

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 would be 3, but the description adds decision-level meaning to `force`: it applies only to a content-source body rule and explicitly does NOT cover the frame binding, which must be released via assign-template-archive. That scoping nuance is worth more than the schema alone.

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 term) plus the exact consequences: posts lose the label, children re-parent upward. Those effects distinguish it from siblings like delete-taxonomy and delete-content without needing the schemas.

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

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

Gives explicit prerequisites (check `count` via list-terms, read get-skill-doc content-model-contract before the first call) and two named refusal conditions with prescribed remedies: unbind with assign-template-archive, or remove the content-source rule / pass force:true. An agent knows both when to call it and when it will be rejected.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the bundle is 'you authored' and lists returned components, which is useful context beyond annotations, though it omits auth requirements or rate limits.

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 followed by usage guidance. The internal field list is slightly verbose but remains purposeful and easy to scan.

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

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

With an output schema present, the description need not return values, and it covers purpose and usage well. It could be stronger by clarifying what 'edits' fragments are or any prerequisites, but it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, with the single 'path' parameter fully documented as 'Archive bundle reference from list-archive-pages.' The description adds no extra parameter semantics beyond what the schema provides, 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?

The description states a specific verb ('Read') and resource ('archive bundle you authored'), and enumerates the exact contents (php, css, js, hooks, listing, etc.). It distinguishes itself from siblings by naming save-archive-page as the write counterpart.

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

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

It explicitly says 'Read before save-archive-page' and 'copy edits fragments from here', providing clear context for when to use it. It names the alternative (save-archive-page) but does not state when not to use it or compare with other get-* siblings.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent, adding real context: the source is 'CURRENT', it includes a hash used for optimistic concurrency (expectedHash), and editing must keep data-ui-id stable. It does not cover auth/rate-limit concerns, but the read-only nature plus the workflow detail is solid beyond the annotation.

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

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

Front-loaded with the purpose and return payload, followed by the editing guidance and contract rules. Dense but every clause earns its place; slightly jargon-heavy with tokenisation/hash references but still efficient.

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

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

Since an output schema exists, return values need not be explained, yet the description helpfully summarizes them anyway. It also supplies the workflow (edit minimally, submit only changes) and the required contract read, leaving little for an agent to infer about how to call it correctly.

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

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

Schema description coverage is 100%, so uuid/blockId are already fully documented in the schema. The description mentions `edits` and expectedHash, but those belong to submit-version, not this tool's parameters, so it adds little parameter meaning. 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 precise verb+resource ('Read one block's CURRENT source') and enumerates exactly what is returned (tokenised file bodies, registered name, shorthand attributes, backgroundColor, skills, description, tags, hash). It also names a related tool (get-skill-doc) so an agent can separate the source-read from the contract-read. This is far more specific than a sibling like list-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?

Clear usage context: read the current source in order to update it, then edit minimally and submit-version only changes. It also directs the agent to read the relevant block-contract via get-skill-doc before the first call. No explicit 'when not to use', so 4 rather than 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?

readOnlyHint=true already covers the safety profile, but the description adds real context: the shortcode is page-content only and a block references the form via its `form` attribute, plus a mandatory skill-doc prerequisite. That is genuine behavioral value beyond the annotation.

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

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

Front-loaded with the verb and resource, then field details, then rules. Dense but every clause carries information; the parenthetical shortcode clarification is the only slightly awkward insertion.

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?

An output schema exists, so return values need not be explained, yet the description still names the returned fields and the mandatory skill-doc prerequisite. Complete enough for a single-parameter read 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% and the single parameter's description ('Form id from list-forms') already documents it. The description adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Read one Contact Form 7 form') and enumerates exactly what is returned (title, raw template, mail recipient/subject, message keys, shortcode). An agent can distinguish it from list-forms and get-content 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 sequencing: 'Read before update-cf7-form' and 'read get-skill-doc {id:"forms-contract"} before the first call.' Strong when-to-use guidance, though it does not state exclusions or when a different read tool 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?

With no annotations, the description carries the full burden and does real work: it discloses that blocks come back in save-content's own format ({name, attributes} or {markup}), that outline is block-name-per-index, and that hash drives optimistic concurrency via expectedHash. It stops short of stating auth requirements, permissions, or mutation side-effects, so it is not fully comprehensive, but it is well beyond a bare read statement.

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 read purpose, then the return payload, then the edit workflow, then the prerequisite rule. Dense but each clause (block format, hash, skill-doc) earns its place; the arrow-notation workflow compresses well.

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?

An output schema exists, so return values needn't be spelled out, yet the description usefully summarizes the payload and, critically, supplies the prerequisite contract doc and the downstream save-content linkage that structured fields cannot express. For a single-param read tool this is close to 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% and the single contentId parameter is fully documented ('Record id from list-content.'). The description adds no format or sourcing detail for contentId beyond the workflow mention, so the schema does the heavy lifting and the baseline 3 applies.

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

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

Specific verb (read) plus resource (ONE page/post/custom record) with an explicit scope contrast against list-content: it returns 'everything list-content reports plus slug, template, excerpt, featuredImage and blocks'. An agent can distinguish it from the sibling list tool 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?

States the when explicitly: 'The step before editing a page' with the exact chained call sequence get-content → save-content {contentId, mode:"edit", edits, expectedHash: hash}. It further names a prerequisite, get-skill-doc {id:"content-contract"}, to be read before the first call, leaving nothing 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?

With readOnlyHint=true already declaring the safety profile, the description adds real behavioral context: the hasDesignSystem:false empty case and the note that buttonCss is already emitted on the page and only needed to read appearance. It does not describe pagination or sizing, but for a read-only token fetch this is solid added value.

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

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

Three tightly packed sentences, front-loaded with what the tool returns before the usage rule. The "Rules:" clause is useful but slightly compresses a prerequisite and a how-to into the tail, leaving minor density.

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

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

For a zero-required-param, read-only getter with no output schema and a fully documented single parameter, the description covers return content, empty state, and consumption pattern. Only the absence of any check on when NOT to use it (e.g., before a design system exists) 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% and the schema already explains buttonStyles vs buttonCss in detail, so the description adds essentially nothing about the include parameter. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (get) and resource (the site's design system), then names the actual payload — colour tokens, typography, button variants with their CSS variable/class — plus the empty-state shape (hasDesignSystem:false). An agent can distinguish it from create-design-system/save-design-system 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?

"Call it before styling a block" gives clear when-to-use context, and it prescribes how to consume results (use var(--fabrement-*) and .fabrement-btn--<variant>). It adds a prerequisite (read the design-system-contract skill doc first). No explicit when-not or named alternatives, which keeps it at 4 rather than 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 only supply readOnlyHint, and the description adds real behavioural context: retired fields are flagged, revision 0 means no fields exist yet, and the "problem" state means the field file is broken so nothing can be saved until the user fixes or removes wp-content/fabrement/fields/<file>, with an explicit instruction not to recreate the fields. That error-state guidance is exactly what annotations cannot convey.

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

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

Front-loaded with the core purpose and the return contents, but it then stacks several concerns (workflow ordering, template read idiom, options-page redirect, problem-state handling) plus a trailing rules line about the skill doc. Dense but each sentence carries information; minor structural sprawl.

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

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

With no output schema, the description carries the full burden and does so: it enumerates the returned shape (names, meta keys, retired markers, layout, revision), documents the empty case and the broken-file case, and states the upstream/downstream workflow. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including the slug pattern example and the "post" owner kind. The description only lightly reinforces this (site-wide settings are not fields of a type), 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?

Specific verb+resource: it returns the custom fields defined for a post type, enumerating name, meta key (fab_<name>), retired flag, form layout and revision. It explicitly demarcates itself from the options-page tools ("Site-wide settings: get-options-page"), but it never mentions the near-neighbour fabrement-list-post-type-fields, leaving that ambiguity for the agent.

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 sequencing rules: call it before save-fields (because the caller needs the revision and existing fields) and before a template reads fields. It also names the read path for values (fabrement_get_field with an explicit record id, never get_post_meta) and mandates reading the fields-contract skill doc before the first call.

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

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

Annotations already declare readOnlyHint=true, but the description adds genuine behavioral context beyond that: the 'stored' flag semantics (false = showing default) and the '_row' identity that must be returned unchanged. That is useful non-obvious behavior an agent could not get from annotations or schema.

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

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

Purpose is front-loaded and the extra rule is kept short. The prose is a little dense and awkwardly worded, but no sentence is wasted.

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

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

With no output schema, the description carries the return-shape burden and does explain the keyed-by-field-name shape plus the 'stored' and '_row' fields. It also points to the fields-contract doc for deeper detail, leaving the definition reasonably complete for a read 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 coverage is 100%, so both parameters are already documented in the schema. The description reinforces 'one record or options page' but adds no format or selection syntax 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 clear verb+resource (get field values) and scopes it to 'one record or of an options page', tying directly to the postId/options parameters. It also names the sibling set-field-values to disambiguate, though the phrasing is slightly convoluted.

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 counterpart tool set-field-values and gives a rule to read the fields-contract skill doc before the first call, which is real usage guidance. But it never contrasts against near siblings like get-fields or list-post-type-fields, so the when-to-use vs alternatives is only partially covered.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial behavioral context beyond that — the {tooLarge, children} overflow response with instructions to read children one by one, the token requirement ('Needs a Figma token on the site'), image URL rendering, and the raw flag. This is exactly the extra operational detail annotations cannot carry.

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

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

Information is front-loaded with the primary return shape before the mode branches, and every sentence carries operational weight. It is dense and slightly run-on in the middle, but there is little waste.

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

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

For a complex tool with no output schema, the description compensates by describing the return tree, the overflow object, and the auth prerequisite. An agent has everything needed to make a correct first call without a dedicated output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: imageIds produces rendered URLs 'as upload-media sourceUrl for raster photos' and raw yields 'the unprocessed node,' which go beyond the terse schema text. The nodeId/fileKey semantics largely restate the schema, keeping it short of 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 outcome: 'A Figma node as build-ready data: a clean HTML/CSS-in-JSON tree (tags, text, inlined icon svg, computed styles, resolved flex/grid).' It also disambiguates two distinct behaviors (node read vs file outline), so an agent can tell exactly what it will get. No sibling competes for Figma reading, and the scope 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?

Explicitly routes between modes: 'Without nodeId: the file outline ... to pick the frame to read,' and names the prerequisite 'get-skill-doc {id:"site-assets-contract"} — read it before the first call.' It also explains when to use imageIds and raw, leaving little to inference.

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

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

readOnlyHint=true is already declared, so the safety profile is covered. The description adds genuinely useful context the annotations cannot carry: the hash output is an optimistic-concurrency token to be returned as expectedHash, and a contract doc must be consulted first. It stops short of stating pagination/caching or how 'exists:false' behaves.

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

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

Front-loads the action and the returned fields in one compact sentence, then adds the workflow rule. Every clause carries information, though the trailing 'Rules:' line is slightly fragmentary and could be folded into the preceding sentence for cleaner structure.

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 an output schema present, the field list in the description is confirmatory rather than necessary, and the description still supplies the workflow context (read-before-write, hash round-trip, required contract doc) an agent needs to call this correctly in sequence.

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

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

There are zero input parameters, so there is nothing for the description to clarify about inputs; the schema baseline of 4 applies. The mention of 'hash' and 'expectedHash' concerns the sibling tool's parameter, not this one's, so it does not raise or lower the input-semantics score.

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

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

States a specific verb+resource ('Read the site-wide stylesheet (global.css)') and even enumerates the returned fields (css, exists, bytes, url, hash). This clearly separates it from sibling fabrement-get-global-js and from the write counterpart fabrement-save-global-css 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?

Explicitly says 'Read before save-global-css; pass hash back there as expectedHash', naming the workflow dependency and the alternative it feeds. Adds a further prerequisite ('read get-skill-doc {id:"global-css-contract"} before the first call'), so when-to-use is fully specified with no inference needed.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the hash field is an optimistic-concurrency token consumed by save-global-js as expectedHash, and a contract doc governs first use. Output schema carries the return shape, so no further transparency is needed.

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 plus a one-line rule, all front-loaded: what it reads, what it returns, the sequencing constraint, and the doc prerequisite. 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?

An output schema exists, so return values are documented elsewhere; listing js/exists/bytes/url/hash in the description is mild duplication. Everything an agent needs to call and sequence the tool is present, and the contract doc pointer covers deeper contract 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?

Zero parameters, so the baseline is 4. The description goes slightly further by explaining the downstream meaning of the `hash` output value, though it does not (and need not) describe input syntax.

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 the site-wide global.js) and enumerates the returned fields (js, exists, bytes, url, hash). It is clearly distinguishable from its write sibling save-global-js and from get-global-css 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?

Explicit ordering guidance: read this before save-global-js and pass `hash` back there as expectedHash, plus a prerequisite to read the global-js-contract skill doc before the first call. It stops short of naming an explicit 'when-not' case, but for a zero-param getter the routing is unambiguous.

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

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

readOnlyHint=true already covers the safety profile, so the description's real addition is the return-behaviour detail that colours are pre-converted to currentColor for mono/duotone. That is genuinely useful, but it says nothing about error behaviour for an unknown id, whether removed icons 404, or caching. Adequate but thin beyond the annotation.

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

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

Purpose is front-loaded in the first clause and the whole thing is three short sentences. The mid-sentence aside about blocks calling fabrement_icon and the oddly formatted 'Rules:' line cost a little clarity, but there is 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?

With no output schema, the description does well to say an SVG comes back with currentColor applied, and it points at the contract doc for the rest. Still, it leaves the agent uninformed about failure modes and about the practical step of getting a valid id, which list-icons (a sibling) presumably provides.

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

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

Only the single id parameter exists and schema coverage is 100%, with the schema itself documenting '<group>/<slug>, from list-icons.' The description repeats the id shape via fabrement_icon('<id>') but adds no format or lookup detail beyond the schema. Baseline 3 applies when the schema carries the parameter documentation.

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

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

States a specific verb+resource: fetching one library icon together with its SVG, which cleanly separates it from the sibling list-icons (plural, enumeration) and the save-icon/delete-icon mutations. The 'as the site renders it' phrasing adds a rendering-pipeline qualifier that helps scope it, though the aside about a block calling fabrement_icon is about a different surface and slightly muddies the subject.

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

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

Gives an explicit prerequisite ('get-skill-doc {id:"icons-contract"} — read it before the first call') and an implicit when-not ('A block does not paste this: it calls fabrement_icon'). It never routes to list-icons for discovering ids or to delete-icon, but the context and prerequisite are clear enough to act on.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond, defining the revision sentinel (0 = no such page yet), the 'problem' state meaning the page file is broken, and the resulting constraint that nothing can be saved until the user fixes or removes the file — plus an explicit instruction not to recreate the fields.

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

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

Front-loads what the tool returns, then edge cases, then call-ordering rules; nearly every clause earns its place. The description is dense and somewhat run-on, packing return values, routing hints, and error semantics into a single block without clear separation.

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

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

No output schema exists, so the description carries the return-value burden — and it does, enumerating the page settings, fields, tabs, and revision. It also covers the 'problem' failure mode and the ordering relative to save-options-page, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single slug parameter is fully documented in the schema (pattern, examples, character rules). The description adds no additional syntax or format detail for the parameter, so the baseline 3 applies.

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

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

States a specific verb+resource (fetch one options page) and enumerates exactly what it returns: page settings (title, menu label, description, position, autoload), fields with names, tabs, and revision. It clearly distinguishes itself from list-options-pages, get-field-values, and save-options-page by scope.

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

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

Explicit sequencing: call before save-options-page because you need the revision and existing fields, and before render code reads the page. It also names the correct alternative for values (get-field-values) and the prerequisite skill doc (options-contract) to read before the first 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 only declare readOnlyHint=true; the description adds real behavioral context beyond that — the stored-vs-effective distinction, the FULL schema graph emitted, primaryTerms for breadcrumbs, and the site settings/knowledge graph fallback. The FIRST/AFTER-write guidance and skill-doc prerequisite further clarify operational 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 selector list is front-loaded and dense but every clause carries information; the Rules sentence is separated out. It is a long single sentence with em-dash chaining, slightly heavy, but not padded.

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?

Output schema exists, so return-shape detail is not required, and the description still covers per-selector behavior plus prerequisites. For a read-only inspection tool with a rich output schema, this is essentially 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?

With only 50% schema description coverage, the description compensates by explaining each selector's meaning — termId for a term archive, archive for a post type archive, postType for defaults/template, contentId for the record's Yoast fields, and 'neither' for site settings. This meaningfully exceeds what the schema documents.

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

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

The description states a specific verb (Read/Get) and resource (SEO state) and enumerates exactly what is returned for each selector (contentId, termId, archive, postType, neither). It reads distinctly from write-oriented siblings like set-seo/set-seo-defaults, though it 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?

It gives clear operational guidance: 'Call it FIRST (is Yoast active?) and AFTER a write to verify,' plus a prerequisite rule to read the seo-contract skill doc before the first call. It does not name a sibling to use instead in any case, so it stops short of explicit alternatives.

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

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

readOnlyHint=true already covers the safety profile, so the description's job is to add context. It does: it discloses the exact fields returned and the notable limitation that theme files cannot be read, which is behavior an agent cannot infer from the schema.

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

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

Front-loaded with verb+resource, then payload contents, then workflow cue, then limitation. Three tight sentences with no filler, though the field enumeration is dense and could be trimmed since an output schema exists.

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

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

An output schema exists so return values need no prose, and the description still covers purpose, workflow trigger, and a key limitation. For a single-parameter read tool this is essentially complete; only explicit sibling routing 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?

One parameter with 100% schema description coverage, where the schema already states 'Agent single-page reference from list-single-pages.' The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

Specific verb ('Read') plus resource ('single-page bundle you authored'), and it enumerates the returned payload (php, css, js, hooks, description, logic, contexts, requires, history, hash). It differentiates partly from siblings via the save-single-page relationship and the 'theme files are not readable' scope note, though it never contrasts against the other get-* readers.

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?

'Read before save-single-page; copy `edits` fragments from here' gives an explicit workflow trigger, and 'Theme files are not readable' is a clear exclusion. It lacks a direct naming of alternatives (e.g. get-template / get-archive-page), but the when-to-use context is strong.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely new behavior: the values are live/current ('as they are now'), and there is a mandatory first-call prerequisite (get-skill-doc site-settings-contract) that the agent cannot learn from the schema or annotations.

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

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

Front-loaded with the resource and its fields, then the sibling alternative, then the rule. The field enumeration is long but earns its place by defining the payload; only mild redundancy between 'site settings' phrasing and 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 readOnlyHint annotations, a 100%-covered schema, and an output schema that documents returns, the description only needs to add purpose, alternative routing, and the skill-doc prerequisite — all of which it supplies. Nothing needed to call it correctly is missing.

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

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

Zero input parameters, so the baseline is 4. To compensate, the description names the shape of the returned payload (the settings list), which orients the agent even though parameter semantics are trivially empty.

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?

Identifies the exact resource (site settings) and enumerates the concrete fields it exposes (siteTitle, frontPage, permalinkStructure, etc.), which pins down what the caller receives. The read verb is only implied by 'as they are now' rather than stated, and it differentiates from its sibling update-site-settings, 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?

Explicitly routes writes to update-site-settings ('Change them with update-site-settings'), which functions as the when-not condition, and adds a hard prerequisite ('read get-skill-doc before the first call'). Clear context and an alternative, but no explicit statement of the triggering scenario beyond that.

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 supply readOnlyHint=true, so the description carries most of the burden and does add real behavior: docs can be fetched several at a time as parallel calls, one id per call. It does not mention rate limits or failure modes, but the read-before-first-call protocol is a meaningful disclosure.

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

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

Purpose is front-loaded in the first sentence, and the rest is spent on actionable protocol guidance rather than filler. The final run-on sentence listing WHAT TO FETCH categories is dense and slightly awkward, but nothing is wasted.

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

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

With an output schema present, return-value detail is unnecessary, and the description correctly focuses on how to consume the doc system. A single-parameter read tool with an output schema needs little more; only the terse category phrasing leaves minor ambiguity.

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 id property already carries a pattern and concrete examples, so the schema does the heavy lifting. The description only adds 'one id each', which restates single-value semantics rather than enriching them – 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 ('Fetch one doc by id') and immediately frames the resource type as a rules/contract doc, which cleanly separates it from the many content-oriented get_* siblings (get-content, get-template, get-fields). An agent can identify the tool without opening the schema.

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

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

Gives a concrete trigger: read a tool's 'Rules:' contract doc before the first call, and explains the REQUIRED / PICK ONE / OPTIONAL / LATER grouping so the agent knows which docs to pull. No explicit when-not-to-use case, but no real alternative exists for this resource.

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 the description adds substantial behavioral context: it enumerates the meaningful return fields and explains that `usedBy` is 'every record placing it, i.e. everything an edit changes'. It doesn't cover pagination or error behavior, but this is rich detail for a read tool.

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

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

Front-loaded with the core action, then the return-field breakdown, then a rules line. Dense but every clause carries information; only the skill-doc pointer sits slightly apart from the main flow.

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?

An output schema exists, so return values are already structured, yet the description still frames the key fields and their edit implications. Combined with the contract-doc pointer, an agent has enough to call and interpret the tool correctly.

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

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

Schema description coverage is 0% and the single `patternId` parameter is never explained in the description text (format, where to source it). The parameter is a trivial positive integer, so the gap is minor, but the description does not compensate for the missing schema description.

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

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

States a specific verb and resource ('Get one global block (synced pattern) in full') and resolves the domain jargon by equating 'synced pattern' with 'global block'. This clearly distinguishes it from list-synced-patterns and save-synced-pattern 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?

Gives explicit usage context: 'Read it before changing the pattern' and the rule to consult the synced-pattern-contract skill doc before the first call. It stops short of naming a specific alternative tool, but the when-to-use condition is unambiguous.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that: header/footer entries are GLOBAL BLOCKS whose words change in every template placing them, a stale rule surfaces as `problem`, and save-template is destructive-replacement so this read is a prerequisite to a safe update. It doesn't cover auth or rate-limit behavior, but for a read tool this is well above the bar.

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 outcome ('One template in full:') followed by dense field enumeration, and the critical update warning is last, where it lands well. However the core is one long em-dash-chained run-on that requires re-reading to parse.

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

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

An output schema exists, so the return payload needn't be explained; the description instead spends its budget on the non-obvious parts — global-block coupling, the `problem` marker, and the read-before-write dependency. Complete enough for a single-parameter read tool, with little left that would cause a mis-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?

Single parameter with 100% schema description coverage ('Template id from list-templates'), so the schema already carries the semantics. The description adds nothing about templateId syntax or sourcing, which is the expected baseline-3 outcome when the schema does the lifting.

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

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

States a specific verb and resource ('One template in full') and enumerates the payload shape: parts, contentWidth, contentSource, beforeSlot/afterSlot, header/footer, archiveContexts. This is immediately distinguishable from fabrement-list-templates and from fabrement-get-synced-pattern, which it explicitly names for a different concern.

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

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

Gives a concrete trigger — 'Read it before an UPDATE that touches the slot or a zone' — with the reason ('save-template replaces what you pass'), and routes the reader to get-synced-pattern/save-synced-pattern for editing global block content. No explicit when-not or mention of list-templates for browsing, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses that installed blocks keep their WordPress ID, that files are rewritten without creating a backend version, and that the result is indistinguishable from a locally built block. It stops short of explicitly flagging that local file edits are overwritten (destructive potential) or any permission/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?

Purpose and input source are front-loaded, and each clause (retry case, ID retention, equivalence to local blocks) earns its place. It is dense and slightly long for a one-parameter tool, but there is little 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 an output schema present, return values need not be explained, and the description fully covers the operational context an agent needs: the correct input source, the retry scenario, and downstream behavior of the imported block. Nothing essential is missing.

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

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

Schema coverage is 100% and the schema already documents blockIds as uuid values from list-blocks, explicitly excluding the numeric WordPress id. The description reinforces this but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (install/reapply a project block on this site) and names the concrete input source (uuids from list-blocks as blockIds). It distinguishes itself from create-block and submit-version by describing what happens to already-installed blocks and by scoping to the 'current PROJECT version'.

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 gives the triggering situation: 'Use this to retry after submit-version saved in the backend but failed to write locally.' It also gives a preference rule ('Prefer this over building the same section again') and clarifies the tool is not for fresh authoring. Alternatives are named concretely.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses required capabilities (install/activate) and host preconditions (writable filesystem), failure behavior (a refusal names the reason), and an activation side effect. It does not address idempotency (what happens if already installed) or reversibility, which keeps it short of a 5.

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

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

The purpose is front-loaded and each clause (allow-list, per-slug conditions, capability requirements, WPML exclusion, doc rule) earns its place. However, the middle section is dense and run-on with parenthetical asides, making it harder to scan than necessary.

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

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

For a mutation tool with no annotations, the description supplies prerequisites, decision criteria, an explicit exclusion with a workaround, and a pre-call documentation rule. An output schema exists, so return values need not be described. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 0%, but the single parameter is an enum and the description richly explains the decision criterion for each value, going well beyond the bare allowed strings. It compensates for the coverage gap; only the absence of any note on invalid slugs keeps it from a 5.

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

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

The description states a specific verb pair (install and activate) and resource (plugin), immediately scoped as coming from a closed allow-list. It is unmistakable against siblings, none of which perform installs, and it enumerates the exact allowed slugs. An agent knows precisely what this tool does without opening the schema.

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

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

It gives explicit when-to-use conditions per slug (wordpress-seo when get-seo reports yoast.active:false and SEO is wanted; contact-form-7 when list-forms reports cf7.active:false and a form is needed). It also names an exclusion — WPML is NOT on the list — and routes the agent to the alternative action (ask the site owner to install/configure, then reconnect). Prerequisite doc reading is called out too.

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?

readOnlyHint=true already signals a safe read, so the bar is lower, and the description adds genuine interpretive context: it explains what usedBy means (the views actually rendering it) and the orphan inference when it is absent. It stops short of describing pagination or ordering behavior, but the added semantic depth is real.

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 key point — the archive bundles returned and their fields — is front-loaded in the first clause, followed by a useful clarification about usedBy. The phrasing is dense and the opening sentence is long, but no sentence is wasted.

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

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

Because an output schema exists, the description need not enumerate return values, and it appropriately focuses on field semantics (usedBy, orphan meaning) and a fallback route. It is nearly complete for a zero-parameter list tool, falling just short of stating when to prefer it over sibling list tools.

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 baseline is 4. With no inputs to document, there is nothing the description needs to compensate for.

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

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

The description conveys that this returns archive-page bundles the user authored, along with their fields (path, label, description, usedBy). However, the verb 'list' is only implied via the title rather than stated, and it does not explicitly contrast itself with close siblings like list-archives or list-archive-records. Purpose is clear but sibling differentiation is weak.

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 one indirect routing cue — 'If nothing fits, save-archive-page' — and explains an orphan-detection signal via the absence of usedBy. There is no explicit statement of when to reach for this versus the other list/get archive tools, leaving usage largely inferred.

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, so the description carries most of the behavioral burden — and it delivers non-obvious domain semantics: what hasContent means (a record carrying BLOCKS), that archive content is written via save-content {contentId: pageId}, and that the seo-contract skill doc must be read first. It stops short of covering pagination, ordering, or failure modes, but the output schema exists to carry return shape.

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

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

Dense and largely front-loaded: the resource definition and record shape come first, and the sibling disambiguation and prerequisite rule land at the end where they belong. It is written in clipped, jargon-heavy fragments ('the record its title, SEO and schema live on') and is longer than most definitions, costing a point on readability rather than waste.

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

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

With an output schema present, return values need not be explained, and the description covers the harder gaps: what a record represents, how it relates to set-archive-record / set-schema / save-content, the hasContent flag, and the mandatory skill-doc read. Missing only operational details like ordering or paging behavior.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description instead documents the returned field set and their downstream owners, which is where the value sits for this no-arg lister.

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

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

States a specific resource ('the PAGE that describes each post-type archive') and enumerates the exact record shape {postType, context, url, pageId, title, slug, status, hasContent}. It also explicitly separates itself from a similarly named sibling, list-archive-pages, so an agent can pick between them 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?

Provides explicit routing for follow-up work: title/slug edits go to set-archive-record, SEO to get-seo/set-seo {archive: postType}, schema to set-schema on the pageId. It names the conflicting sibling ('Not to be confused with list-archive-pages') and states a prerequisite ('get-skill-doc {id:"seo-contract"} — read it before the first 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?

readOnlyHint=true already declares the safe-read profile, and the description adds real behavioral context beyond it: the context string formats, that term views 'resolve most-specific-first', and that templateId is the binding at that level. It does not discuss ordering, pagination, or emptiness of the result, but the added semantics are 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?

Everything is packed into a single dense paragraph with inline quoted enums and arrow symbols, which makes it harder to scan than a short front-loaded statement plus a separate workflow note. The information is relevant, but the structure is cramped and the arrow chain is cryptic 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?

With an output schema present and no input parameters, the description only needs to frame what the tool is for and how it fits the workflow, which it does. The resolution-ordering note and the downstream chain cover the main ambiguities an agent would face.

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

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

The tool takes zero parameters, so the schema baseline is 4. The description's enumeration of context value shapes applies to returned data rather than inputs, so it adds nothing to parameter semantics, but there is no gap to compensate for.

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

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

The description identifies the resource precisely — the archive view contexts a template can be bound to — and enumerates the returned fields (context, label, url, templateId). It never states the verb 'list' explicitly, relying on the name and title, but the resource and scope are unambiguous and distinguishable from siblings like list-archive-pages and list-archive-records.

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 a concrete workflow position: 'Pick a context here → save-archive-page → contentSource rule → assign-template-archive', which tells the agent this is the entry point before save-archive-page. There is no explicit when-not guidance or named alternative, but the ordering context is clear.

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

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

Annotations only declare readOnlyHint, so the description carries real weight and delivers: default page size of 10, a hard cap of 25 on limit (capped, not refused), semantics of installed:false rows ('in the project but NOT on this site'), the always-false hasFiles on those rows, and that `refresh` is a no-op. This is substantial behavior disclosure beyond the annotation.

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

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

Front-loaded with the purpose and return shape, then constraints, then rules. Dense but every clause carries information; the one redundancy is restating that refresh has no effect, which the schema already says.

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?

An output schema exists so return values need not be explained, and the description still covers paging, filtering strategy, the installed vs. project distinction, tag vocabulary, and a pointer to the governing contract doc. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds operational meaning: `name` is the registered name other tools take, `hasFiles` is unreliable on uninstalled rows, and `tags` values must come from `availableTags` or they match nothing. It slightly repeats the schema's `refresh` no-op note, keeping it short of a 5.

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

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

States a specific verb and resource ('List/search this project's blocks') and immediately enumerates the returned fields (id, name, title, hasFiles, type). It carves out scope precisely: content blocks by default, template parts via type header/footer/all, which distinguishes it from siblings like list-content and list-templates.

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 routing: narrow with `search`/`tags` rather than scanning paged results; rows with installed:false should be installed with import-block rather than rebuilt; read `availableTags` before tagging; and read the block-discovery-contract skill doc before the first call. When-to-use, when-not-to, and the alternative tool are all named.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: the empty-result semantics ('Empty means nothing places it yet'), the consequence framing (a submitted version replaces it everywhere), and a skill-doc precondition. It does not discuss pagination behavior, but the output schema covers the return shape.

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

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

The purpose is front-loaded and the supporting sentences earn their place by explaining why to call it. Slightly dense with the trailing 'Rules:' line, but no wasted verbiage.

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 an output schema present and readOnly annotations provided, the description only needs to sell purpose and workflow. It covers scope, the empty case, and a precondition, leaving nothing important for the agent to infer before calling.

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

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

Schema coverage is 100% and both parameters are well documented in the schema itself, including the reason the limit is 'a real bound rather than a page size.' The description adds no parameter-level detail, 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 and resource with precise scope: 'Where a block is PLACED: the templates using it as a header or footer, and the pages, posts and template zones whose content holds it.' This clearly distinguishes it from siblings like list-blocks (returns all blocks) or get-block-source (returns source for one block).

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 trigger condition: 'Ask before editing a block — a submitted version replaces it everywhere.' The rules line further directs reading block-contract before the first call. It stops short of naming explicit alternative tools or when-not-to-use conditions, so a 4 rather than 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?

readOnlyHint=true already classifies the operation, and the description adds meaningful behavioral context: the return field set, the one-level semantics of `parent`, and the create-collision risk that motivates using it. Some of that (status/trash, orderby) duplicates the schema, so it does not reach the highest tier.

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

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

Front-loaded with purpose and the search-before-create rule, and each filter is dispatched in a short clause. The enumerated return fields are somewhat redundant given an output schema exists, which keeps it out of the top tier.

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 annotations, an output schema and 89% parameter coverage already present, the description supplies exactly the missing pieces: when to use it, how to choose filters, hierarchy semantics, and the failure mode it prevents. An agent can call it correctly without opening anything else.

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

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

With 89% schema coverage the baseline is 3, and the description earns a small upgrade by tying filters to intent ('`title` answers "does a page called X exist", `slug` is the exact lookup') rather than just restating field definitions. The remaining parameter sentences largely mirror 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 (content — pages, posts or any type) and immediately narrows intent to finding ids and surveying what exists, enumerating the returned fields. This clearly separates it from get-content, list-media, list-terms and other list-* 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?

Gives explicit workflow guidance ('Search BEFORE creating: a second "About" beside the existing one is the usual failure') and spells out which filter answers which question (title for existence, slug for exact lookup, search for broader scans, parent for one level). It doesn't explicitly name a sibling alternative such as get-content, so there is minor inference left.

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?

readOnlyHint=true already covers the safety profile, so the description's added value is the disclosure that results include real shipped weights and a siteFonts list of already-installed families (which cost nothing extra). It does not mention pagination or result-size behavior, but it does add meaningful return context beyond the annotations.

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

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

Front-loads the core purpose in the first sentence and keeps the routing advice tight. The trailing "Rules:" line is a slightly awkward tack-on but is short and actionable, so little is wasted.

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

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

With no output schema, the description does supply the key return shape (matching families, their weights, and a siteFonts set). For a read-only search tool with four optional parameters this is nearly complete; only the undocumented limit/category behavior 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 50%: q and cyrillicOnly are documented in the schema, while limit and category are not. The description adds no parameter-level meaning at all (no mention of paging, result caps, or category filtering), so it fails to compensate for the undocumented half.

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

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

States a specific verb (search) and resource (Google Fonts catalogue) plus a second scope (the fonts already installed on this site). It explicitly names the sibling save-design-system that consumes its output, so an agent can place it in the workflow without opening other 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 a concrete trigger ("Call it BEFORE naming a font in save-design-system") and a prerequisite (read get-skill-doc design-system-contract first). There is no explicit when-not-to-use guidance, but the sequencing instruction is clear enough to select the tool correctly.

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