SwiftlyMCP : Wordpress MCP Server

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without the description. The description adds genuine value by enumerating the returned field attributes (name, type, label, required, choices), but says nothing about failure behavior for an invalid key or how the key/post-ID duality resolves.

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

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

A single tight sentence that front-loads the action and resource before the parenthetical detail. Nothing is padded or redundant.

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

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

For a read-only lookup with full annotation coverage and no output schema, the description adequately conveys what is retrieved and the shape of the returned field definitions. Minor gaps remain around invalid-key handling, but the essential information an agent needs to call it is present.

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

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

Schema description coverage is 100%, so both the 'key' format (group_abc123 or post ID) and the optional 'site_id' are already documented in the schema. The description adds no meaning beyond that, 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 and resource ('Get a specific ACF field group') and clarifies the payload ('all its field definitions'). The word 'specific' hints at single-item retrieval, but it does not name or contrast with the sibling acf_list_field_groups, so differentiation is left to inference.

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

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

Usage is only implied: the requirement of a 'key'-based lookup suggests retrieving one known group, and the sibling list tool is never mentioned. No explicit when-to-use or when-not-to-use guidance is given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the ACF Pro/options-page prerequisite, but says nothing about behavior when no options pages exist or how many values come back.

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

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

Two short sentences, front-loaded with the operation and followed by the only prerequisite. Nothing is wasted, though it is on the terse side.

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

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

For a single-optional-parameter read tool with no output schema, the description covers the operation, scope, and prerequisite. It could note what is returned when no options pages are registered, but otherwise an agent has enough to invoke it correctly.

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

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

Only one optional parameter (site_id) and schema description coverage is 100%, so the schema fully documents it including the single-site fallback. The description adds no syntax or behavioral detail beyond the schema, making 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 ('Get') and resource ('all ACF options page field values'), which is clearly distinct from sibling ACF tools like acf_get_field_group and acf_get_post_fields. The scope word 'all' signals it returns the full set rather than a filtered lookup.

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

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

The second sentence gives a real precondition (ACF Pro with options pages registered), which is more than nothing, but the description never says when to choose this over acf_get_field_group or acf_get_post_fields or what to do if the precondition fails.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds useful return-shape context (name => value pairs, repeaters, groups, relationships) that annotations do not provide, but says nothing about value formatting (raw vs. formatted) or permission requirements.

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

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

Two tight sentences with zero waste: the action and scope are front-loaded, then the return shape adds value. Every clause earns its place.

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

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

With no output schema, the description usefully characterizes the returned data (field name => value pairs, including repeaters/groups/relationships), and annotations cover the safety profile. Minor gaps remain around value formatting and multi-site behavior, but it is largely 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 description coverage is 100%, so both post_id and site_id are already documented in the schema. The description only restates the post/page targeting for post_id without adding syntax, format, or fallback behavior beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb ('Get') and resource ('ACF custom field values for a specific post/page'), and the scoping to a single post reasonably distinguishes it from acf_get_field_group (group config) and acf_get_options (options pages) by implication. The sibling differentiation is implicit rather than named, so it falls short of a 5.

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

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

No when-to-use, prerequisites, or alternatives are stated. The agent is not told when to prefer this over acf_get_field_group or acf_get_options, nor what 'ACF' context prerequisites exist. Usage is only faintly implied by 'for a specific post/page'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, covering the safety profile. The description adds genuinely new context by enumerating the returned fields (location rules, REST visibility, field count), which matters because there is no output schema. It does not mention pagination or scale 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 with zero filler: the first front-loads what is returned, the second supplies the use case. Nothing could be removed without losing information.

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

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

With no output schema, the return-field enumeration is what makes this definition callable and interpretable, and annotations cover safety. Only minor gaps remain (ordering, whether inactive groups are included, large-site 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?

One optional parameter with 100% schema description coverage, so the schema already documents site_id fully. The description adds no format, default, or multi-site behavior detail beyond the schema; baseline 3 applies.

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

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

States a specific verb (list) and resource (ACF field groups) and enumerates exactly what each entry contains: key, title, active status, location rules, field count, REST visibility. It distinguishes itself from acf_get_field_group by implication only (list-all vs. fetch-one), so it is clear but does not explicitly name the singular sibling.

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

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

"Use this to discover what custom fields are configured on the site" gives a clear context for invocation. It does not name alternatives or exclusions (e.g., use acf_get_field_group when you already know the key), so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them — the value conventions for image fields (attachment ID) and repeaters (array of rows) — but does not say whether unspecified fields are left untouched or what a bad field name does.

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

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

Three sentences, front-loaded with the operation before the workflow hint and the value-format list. No sentence is redundant and nothing is buried.

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

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

There is no output schema, so the description carries the return burden implicitly and annotations cover the safety profile. Field discovery and value formats are covered, but a mutation tool arguably should state merge semantics and whether missing field names are created or ignored.

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 post_id/fields/site_id are self-documenting, so the baseline of 3 would apply. The description exceeds it by explaining the free-form 'fields' object, which the schema can only describe as 'additionalProperties', and by giving per-type value formats.

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

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

Names a specific verb and resource: 'Update ACF custom field values for a specific post/page.' The 'ACF custom field' qualifier separates it from core-field writers like wp_update_post and from the read sibling acf_get_post_fields, though no sibling is named explicitly.

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

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

Gives a concrete workflow pointer: 'Use acf_get_field_group to discover valid field names and types.' That tells the agent how to prepare the call and routes it to a sibling tool. It stops short of stating when not to use this tool or what happens relative to the core wp_update_post path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context with no output schema present: the return format differs by Divi version ('divi4' shortcode in post_content vs 'divi5' JSON element tree). It stops short of covering failure cases such as a page with no Divi layout.

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

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

Three short sentences, front-loaded with the core action and then the version-dependent output formats. Every sentence carries distinct information and there is no filler.

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

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

With no output schema, the description correctly supplies the return shape (divi4 vs divi5), and annotations cover the read-only safety profile while the schema fully documents both parameters. Minor gaps remain around edge cases (page without Divi layout, multi-site ambiguity when site_id is omitted).

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

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

Schema description coverage is 100% with only two parameters, both documented in the schema (post_id and optional site_id), so the baseline of 3 applies. The description's 'specific page/post' phrasing loosely reinforces post_id but adds no syntax, constraints, or defaults 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 ('Get the Divi layout data for a specific page/post'), which cleanly separates it from sibling lookalikes like elementor_get_page_data and wp_get_page. It also names the two possible payload shapes (shortcode layout vs JSON element tree), so an agent knows exactly what kind of artifact it retrieves.

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

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

There is no when-to-use or when-not-to-use guidance and no routing against alternatives such as wp_get_page (generic page content) or elementor_get_page_data. The Divi 4 vs Divi 5 format notes describe what comes back, not when to pick this tool, so an agent must infer its applicability from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which is useful, but says nothing about pagination, result limits, or whether an empty library returns an empty list.

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

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

Two tight sentences with zero filler; the action is front-loaded and the return-value summary is compact. Nothing could be cut without losing information.

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

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

With no output schema, the description correctly compensates by enumerating returned fields. For a zero-required-param read tool with full schema coverage, this is nearly complete; only pagination/empty-result behavior is unaddressed.

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

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

Schema description coverage is 100% and the single site_id parameter is fully documented in the schema, so baseline 3 applies. The description adds no additional meaning about site_id's behavior or default.

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 all saved Divi layouts from the Divi Library'), which clearly separates it from page-oriented siblings like divi_list_pages and divi_get_page_data. It stops short of explicitly naming those alternatives, so sibling differentiation is implied rather than stated.

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

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

There is no guidance on when to call this versus divi_list_pages or divi_get_page_data, and no exclusions or prerequisites. Usage must be inferred entirely from the tool name and the phrase 'from the Divi Library'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the return field list but says nothing about pagination behavior, site scoping, or result ordering that goes beyond the structured data.

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

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

Two lean sentences: the first states scope, the second states the return shape, with zero filler. Information is front-loaded and every clause earns its place.

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

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

With no output schema, the description usefully enumerates returned fields and the read-only nature is covered by annotations. It is complete enough to call correctly, though pagination and multi-site targeting behavior are left to the 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 description coverage is 100%, so all four parameters are already documented in the schema with defaults and constraints. The description adds no parameter-level meaning (e.g., how post_type interacts with the 'Divi Builder' filter), 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 (List) and a clearly scoped resource (pages/posts built with Divi Builder), and enumerates what each result contains. The 'built with Divi Builder' qualifier differentiates it from the generic wp_list_pages sibling, though it never names that sibling explicitly.

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

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

Usage is implied by the name and description, but there is no explicit when-to-use, when-not, or comparison against close siblings like divi_get_page_data, divi_list_layouts, or wp_list_pages. An agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the return is the full JSON structure Elementor stores, which is useful context, but says nothing about size/pagination, permission requirements, or behavior when a page has no Elementor data.

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

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

Two short sentences, front-loaded with the verb and resource, no filler or boilerplate. The second sentence partly restates the first (JSON structure = element tree), so it is efficient but not maximally tight.

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

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

For a simple read tool with 100% schema coverage and read-only annotations, the description supplies the essential missing piece – what the response actually contains (raw Elementor JSON tree). No output schema exists, yet the return shape is described adequately; only edge-case behavior remains unexplained.

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

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

Schema description coverage is 100% and both parameters (post_id, site_id) are documented in the schema itself. The description's phrase 'a specific page/post' loosely mirrors post_id but adds no format, ID-source, or site-selection guidance, so it stays at the baseline for a fully documented 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?

Specific verb ('Get') plus resource ('Elementor element tree'), with concrete scope ('sections, columns, widgets') and target ('a specific page/post'). It is clearly distinct from generic siblings like wp_get_page, but it never names or contrasts with the closest alternatives (divi_get_page_data, elementor_list_pages, elementor_get_widget_schema).

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

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

Usage is only implied by 'for a specific page/post' – the agent can infer you call this when you need a page's Elementor structure. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., use wp_get_page_html for rendered markup or elementor_get_widget_schema for widget definitions).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine context beyond that: the return shape differs by widget generation (props+types vs controls with name/type/options/defaults), which is important since no output schema exists. It doesn't cover error behavior for an invalid slug.

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

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

Three short sentences, no filler, front-loaded with the core action and immediately followed by the two return variants and the discovery prerequisite. Every sentence carries information an agent needs.

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

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

With no output schema, the description correctly takes on the burden of describing what comes back in each widget generation, which is the key unknown for a schema-lookup tool. It is essentially complete for a read-only getter; only failure/not-found handling is unaddressed.

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

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

Schema description coverage is 100% and both parameters are documented there (slug with examples like 'heading'/'image'/'container', plus the optional site_id). The description only refers to the slug obliquely via the list_widgets prerequisite, adding no format or constraint 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 (get the control/prop schema for a specific widget/element) and splits the behavior into two clearly-named cases: v4 atomic widgets return props with types, classic widgets return controls. It also names elementor_list_widgets as the discovery sibling, so an agent can separate it from that tool without reading 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?

The description gives explicit sequencing guidance ('Use elementor_list_widgets first to find available widget slugs'), which routes the agent to the right sibling before calling this one. It does not state when NOT to use it or what to do with an unknown slug, so it falls just short of the top band.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without the description. The description adds the domain clarification that these are reusable library instances, but says nothing about result size, pagination, or ordering, which is a modest gap for a list operation.

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

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

A single tight sentence that front-loads the action and resource with zero filler. Nothing to trim and nothing buried.

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

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

For a simple zero-required-parameter read-only list tool, the definition is nearly sufficient, and annotations carry the safety profile. The only shortfall is the absence of any return-shape hint, which matters slightly more here since no output schema exists.

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

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

There is exactly one parameter (site_id) with 100% schema description coverage, so the schema fully documents the optional target-site behavior. The description adds nothing about site_id or its multi-site semantics, so the baseline of 3 applies.

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

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

States a specific verb+resource ('List all Elementor global widgets') and adds a clarifying parenthetical that defines global widgets as reusable instances from the Elementor Library. This partly distinguishes it from the sibling elementor_list_widgets, but the differentiation is implicit rather than explicit.

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

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

No when-to-use guidance is provided. The description gives no indication of when an agent should reach for this versus elementor_list_widgets, elementor_list_templates, or elementor_get_widget_schema, all of which sit in the same sibling family.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered upstream. The description adds the useful detail that the payload includes Elementor template type, but says nothing about pagination behavior beyond the schema, result caps, or whether unpublished/draft items appear.

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

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

Two tight sentences with zero filler. The scope constraint comes first and the return-field inventory second, which is exactly the order an agent needs for a list operation.

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

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

For a no-required-parameter list tool whose annotations carry the safety profile, the description covers what the tool returns and what it covers. It is slightly thin on routing versus the many sibling list tools, but nothing critical for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so page, site_id, per_page, and post_type are already documented in-schema; the baseline is 3. The description adds nothing about parameter semantics beyond listing output fields, so no credit above baseline is warranted.

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 a scoped resource (pages/posts built with Elementor), and enumerates the returned fields, which lets an agent distinguish it from the generic wp_list_pages at a glance. It never names the sibling, so differentiation is implied by the Elementor qualifier rather than stated 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?

There is no guidance on when to pick this over wp_list_pages, divi_list_pages, or elementor_list_templates, which all return page-like resources. The description never states prerequisites, exclusions, or the alternative to choose for non-Elementor content, so the agent must infer selection from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read profile is covered. The description adds the source scope (the Elementor Library) but says nothing about return volume, pagination, or filtering behavior. With annotations carrying the safety profile, this is adequate but not rich.

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

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

A single front-loaded sentence with no filler; the resource and its scope appear immediately. Nothing extraneous is included.

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

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

For a simple read-only list tool with annotations covering the safety profile and a fully documented single parameter, the description is nearly sufficient. A brief note on the multi-site targeting (site_id) would round it out, but no critical element 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?

There is only one optional parameter (site_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb (List) and resource (saved Elementor templates) and enumerates the covered template types (sections, pages, headers, footers), which anchors the scope clearly. It does not explicitly distinguish itself from siblings like elementor_list_pages or elementor_list_global_widgets, so an agent must infer the boundary, keeping it short of a 5.

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

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

The description only says what the tool returns; it gives no when-to-use context and names no alternatives, despite several close siblings (elementor_list_global_widgets, elementor_list_pages, divi_list_layouts) that could easily be confused with it. An agent gets no routing help.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value the annotations do not: the scope of what is listed (registered widgets plus structural elements) and the exact return fields, including the v4 atomic-props flag, which is particularly helpful since no output schema exists.

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

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

Two tight sentences with the scope front-loaded and no filler. The return-field enumeration in the second sentence is dense but earns its place given the absence of an output schema.

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

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

For a simple, side-effect-free list tool with one optional parameter and full annotation coverage, the description supplies what matters: scope and return shape. Minor gaps remain around whether results are paginated/filterable and what 'v4 atomic props' implies for the caller.

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

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

There is only one optional parameter (site_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no additional meaning about site_id or multi-site behavior, 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 ('List all registered Elementor widgets'), and even enumerates the structural elements included (container, section, column) plus the returned fields. It is clearly distinguishable from generic list tools, though it never contrasts itself with close siblings like elementor_list_global_widgets or elementor_get_widget_schema.

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

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

Usage is only implied: an agent can infer this is a discovery call made before building or inspecting an Elementor page. There is no explicit when-to-use, no when-not-to-use, and no named alternative such as elementor_get_widget_schema for per-widget detail.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond that: the tool degrades gracefully without an SEO plugin, skipping meta description and focus keyword checks. It does not mention rate limits, auth requirements, or what the recommendations payload looks like.

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

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

Three tight sentences: purpose first, then the checks, then the plugin-optional caveat. Every sentence carries information and nothing is 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?

For a read-only analysis tool with full schema coverage and no output schema, the description covers purpose, scope of checks and the plugin-conditional behavior. The only gap is that it promises 'actionable recommendations' without any hint of their shape or severity grading, which would help an agent know what to do with the result.

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

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

Schema description coverage is 100%, so post_id, site_id, post_type and focus_keyword are all documented in the schema itself, including the 'optional if you have only one connected site' and 'will use stored keyword if available' fallbacks. The description's mention of focus keyword checks adds only marginal meaning 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 and resource ('Analyze a post/page for SEO best practices') and enumerates the exact checks performed (title length, meta description, keyword usage, content length, headings). It is clearly distinct from the read-only sibling seo_get_post_meta, though it never names or contrasts that sibling explicitly.

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

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

The description implies usage by describing what gets checked and notes the plugin-optional behavior, but gives no explicit when-to-use/when-not guidance and never routes the agent between this tool and seo_get_post_meta or the wp_* content tools. Usage must be inferred from the enumerated checks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine value by disclosing auto-detection across Yoast, RankMath, and AIOSEO, but says nothing about what happens when no plugin is installed or whether output is cached/limited.

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

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

Two tight sentences: the capability and returned fields come first, the compatibility/auto-detection note second. Nothing is redundant with the title or schema, and there is no filler.

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

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

With no output schema, the description usefully enumerates the return values and explains multi-plugin support, which is the main ambiguity for this tool. It falls short only on edge cases (no SEO plugin installed, missing metadata) that an agent might reasonably need to know.

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 post_id, site_id, and the post_type enum are already documented in the schema. The description restates the post/page/product scope but adds no format, default, or constraint detail beyond the structured fields, 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 + resource ('Get SEO metadata for a post, page, or product') with the exact returned fields enumerated (title, meta description, focus keyword, canonical URL). This clearly separates it from sibling reads like wp_get_post or seo_analyze_content, which cover content rather than SEO metadata.

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

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

Usage is implied by the phrasing 'for a post, page, or product', and the plugin-compatibility sentence tells the agent it can call this regardless of which SEO plugin is active. However, there is no explicit when-to-use vs. when-not-to-use guidance and no named alternative (e.g., seo_analyze_content), so routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by enumerating the returned fields and the supported providers, which matters because there is no output schema. It does not mention auth requirements or rate limits, so it is good rather than exhaustive.

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

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

Three short sentences, front-loaded with the core action and returns, followed by provider scope and the follow-up tool. No filler, no restatement of the title, and each sentence introduces distinct information.

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

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

With no output schema and five parameters, the description helpfully compensates by describing return values and the downstream wp_upload_media step. The remaining gaps (pagination behavior, whether results are deduplicated across providers) are minor given the schema already documents per_page bounds and orientation filters.

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 (query, source, site_id, per_page, orientation) is already documented with examples, defaults, and enums. The description's only parameter-adjacent content is 'Supports Unsplash and Pexels,' which restates the source enum values rather than adding syntax or behavior. Baseline 3 is correct when the schema carries the burden.

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 ('Search for free stock photos') and enumerates what it returns (image URLs, preview links, photographer credits, download links). It also scopes the tool to two concrete providers (Unsplash, Pexels), so an agent can distinguish it from the nearby swiftly_photo_gallery sibling without opening any schema.

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

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

The description gives a clear follow-on workflow: 'Use wp_upload_media to add a photo to the WordPress media library after finding one you like,' which tells the agent how this tool fits into a sequence. It does not, however, give explicit when-not guidance or explain when to prefer one provider over another, so it stops short of full routing instructions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description then adds genuinely useful behavioral context by enumerating the possible states (approved, declined, not yet executed, executed with result), which the annotations do not convey.

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

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

Two tight sentences, with purpose front-loaded and the return-value clarification second. Nothing is redundant or 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 carries the burden of explaining returns and does so adequately for a simple one-parameter lookup, covering the meaningful state outcomes. It could add polling/timing guidance, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% and the single approval_id parameter is already tied to swiftly_request_approval in the schema. The description adds no format, source, or validation detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Check the status of a pending approval') and scopes it to pending approvals, which separates it from request_approval and execute_approved. It stops short of naming those siblings, so the differentiation is implicit rather than explicit.

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

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

Usage is only implied: an agent can infer this is the polling call after swiftly_request_approval, but the description never states when to call it versus swiftly_execute_approved or swiftly_decline_action. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results only materialize once the upload completes, but says nothing about what a still-pending response contains, whether polling is required, or any 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 short sentences, front-loaded with the core action and followed immediately by the return behavior. No filler or redundancy.

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

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

For a one-parameter read tool with annotations covering the safety profile and no output schema, the description is nearly sufficient, telling the agent what it gets back. It stops short of describing the pending-state response, which an agent polling this endpoint would benefit from knowing.

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

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

With a single parameter at 100% schema description coverage, the schema already explains that upload_id comes from swiftly_request_upload. The description adds no additional meaning about the identifier's format or lifecycle, 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 ('check the status of a pending upload') and clarifies the outcome ('returns uploaded file details once complete'). It does not explicitly distinguish itself from the closely related siblings swiftly_request_upload, swiftly_process_upload, or swiftly_check_approval, so it falls short of a 5.

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

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

Usage is only implied by the word 'pending' – an agent can infer this is a polling call after swiftly_request_upload, but the description never says when to call it, how often, or how it relates to swiftly_process_upload.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the aggregated cross-site scope and the specific contents returned, which tells the agent this is a broad read-and-recommend tool rather than a mutator. No rate-limit or freshness caveats, hence not a 5.

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

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

Three sentences, front-loaded with what the tool is, then its payload, then when to invoke it and what to do next. Every sentence carries distinct information with no repetition of annotations or schema.

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

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

With no output schema, the description carries the burden of describing returns and does so concretely (good/acceptable/critical health scores, version numbers for pending updates, core update status, detected features). Combined with the annotation-covered safety profile and zero parameters, nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. No input semantics are needed beyond the empty schema, and the description correctly spends no words on inputs.

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 ('Open the SwiftlyMCP Command Center') and immediately qualifies scope as 'an interactive dashboard for all connected WordPress sites', which distinguishes it from per-site siblings like wp_site_health. The enumerated return contents (health scores, pending updates, core status, detected features) make the resource unambiguous.

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

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

Explicitly says to use it proactively when the user asks about site status, updates, or health, and routes follow-up work to wp_update_plugin/wp_update_theme. It lacks an explicit 'when not to use this' alternative (e.g., for a single site's details use wp_site_health, for plugin inventory use wp_list_plugins), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and openWorldHint=true, but the description adds real value beyond them: it discloses the return value (a one-click authorization link) and the out-of-band flow where the user approves in WordPress admin. This is exactly the kind of behavioral context the structured fields can't convey, though it doesn't address re-connect behavior or link expiry.

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 front-loaded sentences with zero waste: the first states the action, the second explains the mechanism and the key benefit. Every clause earns its place.

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

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

For a one-parameter connect tool with no output schema, the description covers the action, the returned link, and the human-approval step, and annotations carry the safety profile. Minor gaps remain (what happens on re-connect, link lifetime) but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% for the single required site_url parameter, so the schema already documents format and example. The description adds nothing about parameter interpretation; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Connect) and resource (a WordPress site), so an agent can immediately tell it apart from the read-only siblings like swiftly_list_sites. It does not explicitly contrast with swiftly_disconnect_site, but the verb direction makes the distinction obvious.

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

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

Implies usage by describing the connect flow and noting 'No passwords needed', which hints at why this is preferred over a credentials-based approach. However, it never states when to use this versus siblings or any preconditions (e.g. must the site not already be connected), leaving selection to inference.

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

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

Annotations declare destructiveHint=false and readOnlyHint=false, which is consistent with declining (a state mutation that prevents rather than performs destruction). The description adds the useful qualifier that the target is a 'pending destructive action', clarifying eligibility, but says nothing about reversibility, whether the approval record is deleted, or error behavior on a stale ID. With annotations covering the safety profile, this is adequate but thin.

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

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

One short, front-loaded sentence with zero padding — appropriate for a single-parameter tool. It is efficient, though the terseness borders on under-specification rather than economy.

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

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

For a one-parameter mutation with no output schema, the description gives the minimum needed to call it, but omits what happens after a decline (does the action become permanently rejected, can it be re-requested?) and how it relates to the approval family of tools. Slightly incomplete for a workflow 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% with a single parameter whose meaning ('The approval ID to decline') is fully self-documenting. The description adds no syntax, format, or sourcing 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 (decline) and resource (a pending destructive action), and the word 'pending' correctly scopes it to actions awaiting approval. It does not distinguish itself from siblings like swiftly_execute_approved beyond the opposite verb, but an agent can still infer the intent.

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

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

There is no explicit guidance on when to use this versus the sibling swiftly_execute_approved, nor any statement of prerequisites (e.g., that the approval must still be pending, or that an approval_id must come from swiftly_request_approval). The agent must infer the workflow entirely from the sibling names.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context of its own — it doesn't say what is removed, whether credentials are revoked, whether site data is preserved, or any 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?

A single short sentence with no waste and the action front-loaded. It is appropriately sized for a one-parameter tool, though it is arguably too sparse for a destructive operation.

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

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

For a destructive, irreversible-sounding operation with no output schema, the description should clarify consequences (what happens to the site, its data, or stored credentials) and any preconditions. As written, an agent cannot tell what disconnecting actually does.

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 site_id parameter is already documented in the schema, including the pointer to swiftly_list_sites. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Disconnect') and resource ('a WordPress site from SwiftlyMCP'), which is unambiguous. It does not explicitly contrast with the sibling swiftly_connect_site or mention that it reverses the connection, but the name and verb are clear enough to distinguish it.

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

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

No guidance on when to use this versus alternatives, no prerequisites (e.g., whether the site must be currently connected), and no mention of related tools like swiftly_list_sites or swiftly_connect_site. The agent must infer all of this.

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

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

The description declares the executed action is 'destructive', while the annotations set destructiveHint=false, giving the agent a materially wrong safety signal before an irreversible operation. The only genuine addition, that this is invoked by the approval panel, is outweighed by the contradiction.

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

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

Three short sentences with no filler; the action and its trigger are front-loaded before the parameter instruction. Nothing could be cut without losing information.

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

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

For a destructive, no-output-schema tool, the description covers the trigger and parameter but omits failure modes (expired/consumed/unknown approval_id), what actually happens on success, and any permission expectations. The safety mismatch with annotations compounds the gap.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'The approval ID from swiftly_request_approval'. The description restates that provenance ('the approval_id that was returned') without adding format, expiry, or reuse constraints, so the schema carries the load.

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

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

States a specific verb (Execute) on a specific resource (a previously approved destructive action) and names the trigger context (called by the approval panel on Approve). This clearly separates it from siblings like swiftly_request_approval, swiftly_check_approval, and swiftly_decline_action.

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

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

Explains when it fires (approval panel on user clicking Approve) and what to pass, which is useful invocation context. It stops short of explicit when-not-to-use guidance, e.g. that an agent should not call it outside the approved flow or that the ID must be unconsumed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the session-scoping constraint; it says nothing about result shape, ordering, or whether the list can be empty.

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

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

A single front-loaded sentence with zero filler; the resource and scope come first and 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 no-parameter, read-only list tool with annotations covering safety, the definition is nearly sufficient. The one modest gap is that no output schema exists and the description does not indicate what a returned site entry contains (ID, URL, status), which an agent may need for follow-up calls.

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. There is nothing for the description to clarify beyond confirming that no filtering input is accepted.

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

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

States a specific verb (List) and resource (sites) with a scoping qualifier, 'connected to your SwiftlyMCP session', which separates it from site-mutating siblings like swiftly_connect_site and swiftly_disconnect_site. It never explicitly names a sibling, but the resource is unambiguous.

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

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

The purpose implies the usage (discover which sites are available before acting on them), but there is no explicit when-to-use statement, no exclusions, and no pointer to alternatives such as wp_get_site_info for details about a single connected site.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description usefully adds that this renders an interactive inline component where the user clicks to upload, which explains why it is not a read-only operation. It does not say whether the uploads go through the approval flow implied by the `swiftly_*` approval siblings, nor what the call itself 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 sentences, zero filler, with the interactive behavior front-loaded ahead of the usage trigger. Slightly more compact routing guidance could have displaced nothing, 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?

There is no output schema, so the description should carry the return behavior; it gestures at an inline gallery UI but not at what tool output the agent receives or how the subsequent upload is confirmed. With five parameters and a mutation-adjacent flow, the definition is adequate but leaves the post-browse sequence underspecified.

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 5 well-documented parameters including enums, so the schema carries the parameter burden. The description adds no syntax, default, or format detail beyond the schema — baseline 3 is appropriate.

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

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

The description states a specific verb and resource — 'Open a visual photo gallery inline in the chat' — plus the downstream effect of uploading favorites to WordPress. It is clear on its own, but it never distinguishes itself from the sibling `stock_photo_search`, which an agent could easily confuse with this tool.

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

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

'Use this when the user wants to visually browse and choose photos' gives an implied trigger condition for the browse-and-pick case. However, it names no alternatives and offers no exclusion criteria against `stock_photo_search`, `swiftly_request_upload`, or `wp_upload_media`, so the routing decision is left partly to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the payload contains plan details, tool availability, and upgrade options, but says nothing about freshness, auth requirements, or formatting.

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

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

A single front-loaded sentence with no filler; the informational payload is listed immediately and nothing is repeated from structured fields.

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

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

For a zero-parameter informational tool with annotations carrying the safety profile and no output schema, the description tells the agent what it will get back. Only minor context (e.g., when in a workflow to call it) 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?

The tool takes zero parameters, which is the baseline-4 case. There are no argument semantics to explain and the description introduces none.

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 ('Show') and concrete resources (current plan, available tools, upgrade options), so the agent knows exactly what it returns. It is the only plan-related tool among the siblings, though the description never explicitly contrasts itself with alternatives.

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

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

There is no statement of when to call this versus other swiftly_* tools, nor any prerequisites or exclusions. Usage is only weakly implied by the name and content.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, covering the safety profile. The description adds valuable context beyond that: the upload_id comes from swiftly_request_upload, and importantly that this tool is UI-called rather than model-called. This sourcing dependency is behaviorally meaningful.

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

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

Three tight sentences, front-loaded with the core purpose, then caller constraint, then the alternative. No redundancy.

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

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

For a 2-param tool with full schema coverage and no output schema, this covers purpose, caller, provenance of upload_id, and the sibling alternative. The one missing element is what happens on failure or what the return looks like, though no output schema exists to cover return structure.

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 clear descriptions for upload_id ('upload ID returned by swiftly_request_upload') and files. The description adds the provenance of upload_id, which the schema already states. Baseline 3 per high schema coverage.

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

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

States a specific verb and resource: 'Process files from the upload panel and add them to WordPress media library.' Distinguishes it from wp_upload_media by naming that sibling as the URL-based alternative.

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

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

Explicitly states who calls it ('Called by the upload UI (not by the model)') and names the alternative (wp_upload_media for URL-based uploads). This is unusually clear routing guidance, even telling the agent it should not invoke this tool.

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

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

Annotations cover the safety profile (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description adds context the annotations cannot: that it returns an approval panel with Approve/Decline, that an approval_url fallback exists, and that the caller must block until approval. It does not cover request expiry, auth requirements, or whether re-requesting is safe, so it falls 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?

Four short sentences, every one load-bearing, with the core purpose front-loaded and the procedural steps (share link, wait, poll) following in execution order. 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?

Covers the request/share/wait/poll loop thoroughly and explains the return value in the absence of an output schema. It references swiftly_check_approval but never mentions swiftly_execute_approved, leaving the final step of the workflow implicit.

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

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

Schema description coverage is 100%, so every parameter (site_id, tool_name, tool_params, preview_summary) is already documented in the schema, including the nested tool_params object. The description adds workflow context around tool_name but no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Request user approval before executing a destructive WordPress action') and immediately distinguishes itself from the sibling it hands off to ('Use swiftly_check_approval to poll'). An agent can tell exactly what this tool does and where it sits in the approval workflow.

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 how-to-use guidance: call before destructive actions, share the approval_url if no panel is visible, do NOT proceed until approved, and poll with swiftly_check_approval. The blocking constraint and the fallback path are both spelled out, 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavior beyond that: it opens an inline chat panel, relies on user drag-and-drop interaction, and sends files directly to the WordPress media library.

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

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

A single, front-loaded sentence that clearly conveys the tool's action and mechanism. No wasted words, and the key information is presented immediately.

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

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

For a one-parameter interactive tool with annotation coverage and no output schema, the description is mostly complete: it explains the panel behavior and destination. The main gap is routing guidance for when to use this versus related upload 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?

Schema description coverage is 100%, so the single site_id parameter is already documented in the schema. The description does not add meaning for site_id or explain what happens when it is omitted, 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?

The description states a specific action (open an upload panel inline in chat) and the outcome (drag-and-drop files to upload directly to WordPress media library). It distinguishes this from purely programmatic uploads by emphasizing the interactive user panel, though it does not explicitly name the alternative sibling tools such as swiftly_process_upload or wp_upload_media.

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

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

The description gives no explicit when-to-use, when-not-to-use, or alternative tools. It implies usage by describing the panel, but does not help the agent choose between this tool and siblings like swiftly_process_upload or wp_upload_media.

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

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

Annotations already establish the safety profile (non-readOnly, non-destructive, non-idempotent, open world), but the description adds real context the annotations don't carry: the private/admin-only vs customer-visible distinction and, critically, that customer notes are emailed. That undisclosed side effect is a genuine behavioral disclosure.

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

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

Two sentences, zero waste, and the core action is front-loaded before the privacy/visibility nuance. Nothing to trim.

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

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

For a simple mutation tool with no output schema and full schema coverage, the description covers the action and its key side effect (email). The only minor gap is the absence of any note about the response or permission requirements.

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

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

Schema description coverage is 100%, so all four parameters (including customer_note's default and semantics) are already documented in the schema. The description's privacy/email contrast mirrors the schema's own customer_note documentation, adding no syntax or meaning beyond it. Baseline 3 applies.

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

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

States a specific verb (add) and resource (note to a WooCommerce order), so an agent knows exactly what it does. It doesn't explicitly distinguish itself from the read-side sibling woo_list_order_notes, but the verb+resource is unambiguous.

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

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

No when-to-use guidance at all: it never says when to add a note versus listing existing ones (woo_list_order_notes), nor mentions prerequisites like which order states warrant a note. The email side effect is described, but that is behavior, not usage routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the mutation/write nature is covered. The description adds nothing beyond that: no mention of duplicate-code failure behavior, permission scoping, or side effects. Its second sentence merely restates the discount_type enum already present in the schema.

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

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

Two short, front-loaded sentences with no padding. The second sentence is somewhat redundant with the discount_type enum, which slightly dilutes the value of the length rather than wasting space.

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

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

For a 17-parameter mutation tool with no output schema, this is very thin. It never explains how the required trio (code, discount_type, amount) interact, that amount semantics change with discount_type, or which optional fields are commonly paired, leaving the agent to reconstruct behavior from the schema alone.

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% across all 17 parameters, so the schema already documents every field. The description adds no interpretation beyond the schema, which is the baseline 3 under these conditions.

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

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

The description states a specific verb and resource: "Create a new WooCommerce coupon." The word "new" implicitly separates it from woo_update_coupon, woo_get_coupon and woo_list_coupons, but no sibling is named explicitly, so it falls just short of the top band.

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

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

There is no when-to-use or when-not-to-use guidance, no prerequisites (e.g. that a code must be unique, or that site_id is optional for single-site installs), and no pointer to the update alternative for existin coupons. Usage is only inferable from the tool name.

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

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds one genuinely useful behavioral fact beyond annotations: products default to draft status, plus the supported type set. It omits whether the call is reversible, permission requirements, or what happens on duplicate SKU.

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, front-loaded sentences with no filler. The most decision-relevant fact (what it creates) leads, followed by supported types and the default status.

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 17-parameter mutation tool with no output schema, the description covers creation, supported types, and default status, but is silent on the required 'name' field, the site_id targeting parameter, and what the response returns (e.g., new product ID). Annotations carry the safety profile, so this is adequate but with clear gaps.

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

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

Schema description coverage is 100% across all 17 parameters, so the schema fully documents names, enums, and formats. The description adds only the draft-default and type-set context, which duplicates the enum descriptions rather than extending them; the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a new WooCommerce product') and enumerates the supported product types, which is concrete. It does not explicitly differentiate from siblings like woo_update_product or woo_create_product_category, but the verb+resource make the intent unambiguous.

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

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

The description gives no when-to-use guidance, no prerequisites, and does not name alternatives such as woo_update_product for existing products. Only the default draft status hints at usage, so the agent must infer when this tool applies.

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

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

Annotations already declare the safety profile (write, open-world, not idempotent, not destructive), so the description could have used its space for behavior it alone can convey. It adds nothing about duplicate handling, required permissions, or what happens when the same category name is submitted twice despite idempotentHint=false.

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

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

A single efficient sentence with the verb and resource front-loaded and no filler. It is arguably too terse for a 6-parameter mutation tool, but nothing in the sentence is wasted.

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

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

For a write tool with no output schema, the description omits what is returned, whether the created category can be re-fetched, and how site_id affects targeting. Neither the schema nor the annotations fill those gaps, so an agent is left guessing about post-call behavior.

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

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

Schema description coverage is 83%, so the schema already documents name, slug, image, parent, site_id, and description. The description supplies no additional parameter meaning, 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 (Create) and resource (WooCommerce product category), so the agent knows exactly what is created. It does not distinguish itself from the sibling wp_create_category, which creates WordPress core categories, leaving the agent to infer the WooCommerce-specific 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?

No guidance on when to use this versus wp_create_category or how it relates to woo_list_product_categories. There is no mention of prerequisites such as needing a connected site or whether the category must be unique.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered structurally. The description adds nothing beyond that — no note on what happens with an invalid or missing coupon ID, no auth/scope requirements, and no return-shape context.

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

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

A single front-loaded sentence with zero waste and the resource identified immediately. It is efficient, though arguably so terse that it leaves useful routing and behavioral information unstated.

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

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

For a simple single-record read with full schema coverage, no output schema, and annotations carrying the safety profile, the description is adequate — the agent has everything needed to invoke it. Only the absence of sibling routing keeps it from being fully complete.

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

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

Schema description coverage is 100%: 'id' is documented as 'Coupon ID' with an exclusiveMinimum constraint, and 'site_id' explains the multi-site targeting case. The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (WooCommerce coupon) with the qualifier 'specific' implying a single record. It is clear against woo_list_coupons by implication, but never names the sibling or explicitly contrasts single vs. list retrieval.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative (woo_list_coupons) or when this is preferred over it. The agent must infer the single-record use case entirely from the name and 'specific'.

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

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

The annotations already declare readOnlyHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral value by enumerating the returned fields (name, email, billing/shipping address, total orders, total spent, avatar URL), which is important given the absence of an output schema. It stops short of describing auth requirements or error behavior, so a 4 is appropriate.

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

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

Two tight sentences with zero filler. The core purpose is front-loaded, and the return fields are listed efficiently without redundancy.

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

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

For a simple two-parameter read operation with full schema coverage and rich annotations, the description is nearly complete. It compensates for the missing output schema by naming the returned fields, though it could mention error handling for invalid IDs to be fully complete.

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

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

Schema coverage is 100%, so both parameters (id and site_id) are fully documented in the schema. The description reinforces that lookup is by ID but adds no syntax, format, or constraint details beyond what the schema already provides, yielding the baseline 3.

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

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

The description states a specific verb and resource ('Get detailed WooCommerce customer info') and scopes it by ID, distinguishing it from the sibling list tool woo_list_customers. An agent can immediately tell this is a single-record lookup rather than a list operation.

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

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

The phrase 'by ID' implies the tool should be used when a specific customer ID is known, but the description does not explicitly state when to prefer this over woo_list_customers or what to do if the ID is unknown. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior context by disclosing the shape of the payload (line items, addresses, payment method, notes, totals, customer info), which matters because there is no output schema. It stops short of mentioning error behavior for invalid IDs.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the return inventory as a compact appendix. Every clause earns its place.

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

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

For a simple, two-parameter read tool with full annotation coverage, the description supplies everything needed to invoke it, and notably compensates for the absent output schema by listing returned fields. The only gap is the absence of any note about failure/not-found behavior.

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

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

Schema description coverage is 100%: 'id' (Order ID) and 'site_id' (with multi-site guidance) are fully documented in the schema. The description only reinforces the ID lookup, adding no syntax, range, or multi-site semantics beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb and resource ('Get full details of a WooCommerce order') with an explicit scope ('by ID') that separates it from woo_list_orders, and enumerates exactly what the payload contains. 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?

The 'by ID' scoping implies the tool is used when a specific order identifier is known, which implicitly contrasts with the listing tools, but there is no explicit when-to-use/when-not statement or named alternative (e.g. woo_list_orders for browsing). Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value by enumerating the returned fields, but says nothing about behavior on a nonexistent ID, pagination of variations, or how the open-world site targeting works.

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, purpose front-loaded and the return-value inventory following. The field list is long but each item is informative and there is no filler prose.

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

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

There is no output schema, but the description compensates by enumerating the returned product fields, and the annotations cover the safety profile. For a single-ID read tool this is largely sufficient, though the site_id targeting behavior is left unexplained.

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

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

Schema coverage is 100%, with both id and site_id fully documented in the schema, so the baseline is 3. The phrase 'by ID' only restates the schema and adds no syntax, format, or constraint detail beyond what is already structured.

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 (WooCommerce product) with the lookup key (by ID), which implicitly separates it from the browsing sibling woo_list_products. It does not explicitly name any sibling, so routing relies on inference rather than a stated contrast.

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

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

The description never says when to use this versus woo_list_products, woo_get_order, or woo_list_variations, nor does it state any prerequisite such as needing a valid product ID from a prior listing call. Usage context is entirely 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no pagination behavior, no result volume expectations, no note about how site_id affects targeting. With annotations carrying the burden, no added context earns only a low score.

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

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

A single efficient sentence with the core action front-loaded and no filler. It is well-sized, though the terseness leaves no room for the routing and pagination context that would help.

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

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

For a 4-param, zero-required list tool with full schema coverage and safety annotations, the minimum is met. Missing pieces are moderate: no indication that results are paginated across pages, no output/return shape, and no guidance on when to prefer it over woo_get_coupon.

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%: page, search, site_id and per_page are all documented in the schema with defaults and bounds. The description's generic 'optional filters' adds no syntax or semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('List WooCommerce coupons') that is clearly distinguishable from write siblings like woo_create_coupon and woo_update_coupon. However, it never contrasts itself with woo_get_coupon (single coupon retrieval), so sibling differentiation is only implicit.

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?

'with optional filters' hints at scope but gives no when-to-use guidance, no prerequisites, and never names alternatives such as woo_get_coupon for a single coupon or woo_create_coupon/woo_update_coupon for writes. The agent must infer routing from the name alone.

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 carry the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds useful behavioral context by enumerating the returned customer fields, but says nothing about pagination behavior, total-count semantics, or result limits for a listing tool.

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

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

Two short sentences with no filler; the operation is front-loaded and the return-value sentence earns its place given there is no output schema. Slightly under-detailed rather than verbose.

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

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

With no output schema, the description compensates by listing the key return fields, and the annotations cover safety. Gaps remain around pagination defaults (default 20 / max 100) and whether results are scoped to the targeted site_id, but the essentials for calling the tool are present.

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

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

Schema coverage is 71%, so most parameters are self-documented (page, per_page, search, role, site_id) while order and orderby are bare enums. The description's generic "with filters" adds essentially nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List WooCommerce customers") and names the domain, which separates it from the generic wp_list_users sibling. However it never explicitly contrasts itself with the singular woo_get_customer or with wp_list_users, so sibling differentiation is only implicit.

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?

"with filters" hints at bulk/query use but gives no when-to-use conditions, no exclusions, and no routing to alternatives such as woo_get_customer for a single customer or wp_list_users for non-WooCommerce users. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return content — that both private admin notes and customer-visible notes are included, along with author and date — which is important since there is no output schema.

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

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

Two tight sentences with zero filler; the core action is front-loaded and the return-content detail follows as supporting context.

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

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

For a simple read-only list tool with annotations covering safety and no output schema, the description supplies the essential return-content context. It omits pagination behavior and whether private notes require elevated capability, which would be the only meaningful additions.

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

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

Schema description coverage is 100% and both parameters (id, site_id) are documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("List all notes on a WooCommerce order"), which is unambiguous and immediately distinguishable from the sibling woo_add_order_note. An agent knows exactly what it retrieves without opening the schema.

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

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

Usage is implied by the name and description (fetch notes for a given order), but there is no explicit when-to-use guidance, no mention of alternatives such as woo_get_order or woo_add_order_note, and no stated prerequisites. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value by enumerating returned fields (status, total, customer details, line items, dates), which matters since there is no output schema. It says nothing about pagination behavior, default page size, or site targeting.

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

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

Two short sentences with zero waste, front-loading purpose before return content. Slightly terse for a 10-parameter tool, but nothing is 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?

The return-field list compensates somewhat for the missing output schema, but for a 10-parameter, zero-required tool there is no mention of default pagination (per_page 20, max 100), how the optional site_id selects among connected sites, or date-range semantics. Adequate but incomplete.

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

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

Schema description coverage is 80%, so the schema already documents most parameters. The description says only 'with filters' and adds no format, default, or interaction details beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List WooCommerce orders') plus a scope qualifier ('with filters'). It is clearly distinguishable from woo_get_order, though it does not explicitly name that sibling.

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

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

No guidance on when to use this listing tool versus woo_get_order, woo_list_refunds, or the report tools. The word 'filters' hints at usage but never says when filtering is appropriate or what the alternatives are.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds that hierarchy, count and images are returned, which is modest extra context, but says nothing about pagination defaults, ordering, 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?

A single front-loaded sentence with zero filler. Nothing is repeated from the title and no sentence fails to earn its place.

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

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

For a read-only list tool with rich annotations and no output schema, the description is adequate but thin: it omits pagination behavior, default ordering, and whether hierarchy is returned nested or flat, which matter for a category listing with a parent filter.

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 80%, so the schema documents page, parent, search and site_id itself; per_page is the only undocumented field. The description adds no parameter-level semantics 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 ('List WooCommerce product categories') and names the data returned (hierarchy, count, images). The 'product' qualifier distinguishes it from the core wp_list_categories and the verb distinguishes it from woo_create_product_category, though neither sibling is named explicitly.

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

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

There is no guidance on when to use this versus wp_list_categories or woo_create_product_category, and no mention of pagination or filtering workflows. The agent must infer usage entirely from the name.

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

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

With readOnlyHint/destructiveHint already covering the safety profile, the description adds real value: it names the returned fields (name, price, stock status, categories, images) and the important default that only published products are returned, implying other statuses need an explicit filter. It does not cover pagination limits or site-scoping behavior.

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

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

Two tight sentences with the operation and scope front-loaded and the return contents immediately following. No filler or redundancy.

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

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

For a 14-parameter read tool with no output schema, the description usefully substitutes for one by listing returned fields, and discloses the published-only default. It stops short of explaining pagination semantics or multi-site behavior, which for a filter-heavy listing tool would be the next useful detail.

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 86%, so the schema already documents nearly all 14 parameters (including defaults for per_page and status). The description adds no parameter syntax or format detail beyond restating that filters exist and that status defaults to publish, 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 ('List WooCommerce products with filters') and the scoping default ('Only published products by default'). It is clear what it does, but it does not differentiate itself from nearby siblings such as woo_list_variations or woo_get_product, which also deal with product data.

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

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

The description implies usage (list/filter products) and discloses the default status filter, which is helpful context. However, it never states when to prefer this over woo_get_product (single product), woo_list_variations, or woo_list_product_categories, so alternatives are left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds which fields come back (amounts, reasons, line items, dates), which substitutes for the missing output schema, but says nothing about pagination, ordering, or empty-result behavior.

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

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

Two tight sentences, zero filler, with the resource and scope front-loaded in the first sentence and the return contents in the second. Every clause earns its place.

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

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

For a simple two-parameter read tool with full schema coverage and annotations covering safety, the main gap is the absence of an output schema, which the description partly compensates for by enumerating returned fields. Missing only pagination/volume expectations.

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%: site_id and order_id are both documented in the schema, including the optionality of site_id and the exclusiveMinimum on order_id. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (refunds) scoped to a WooCommerce order, which distinguishes it from sibling woo_list_orders and woo_list_order_notes. It does not, however, explicitly contrast itself with those siblings, so an agent must infer the boundary.

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

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

No when-to-use or when-not-to-use guidance. The description never says whether to reach for this instead of woo_get_order (which may also expose refund data) or what preconditions exist beyond the required order_id.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description goes beyond that by disclosing the return payload contents (prices, stock, attributes per variation), which is meaningful since no output schema exists.

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

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

Two short sentences, zero filler, with the core action front-loaded and the return payload immediately after. Nothing needs trimming or reordering.

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

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

For a read-only two-parameter list tool with full schema coverage and safety annotations, the description is nearly sufficient, and the mention of returned fields compensates for the absent output schema. Pagination or result-size behavior is the only notable omission.

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

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

Schema description coverage is 100%, so both product_id and site_id are already documented in the schema. The description adds no format, constraint, or ID-sourcing detail beyond what the schema provides, which is the expected baseline.

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

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

Names a specific verb (List) and resource (variations of a variable product), which is narrower and more precise than the generic list siblings. It does not explicitly distinguish itself from woo_list_products or woo_get_product, so an agent must infer the boundary from the 'variable product' qualifier.

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

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

No when-to-use, prerequisites, or alternatives are given. The description never says to call this only for products with type=variable, nor does it point to woo_get_product or woo_list_products for the non-variation cases.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description is free to add result-shaping behavior: variation-level stock evaluation for variable products, and the exclusion of drafts because WooCommerce Analytics only covers published products. That is genuine context beyond the annotations, though pagination/return shape is still unmentioned.

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

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

Three tight sentences with no filler: purpose first, then the variation-level nuance, then the published-only caveat. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description still gives an agent enough to call it correctly and anticipate the result set (stock-status products, variation-aware, published only). It stops short of describing returned fields or ordering, a minor gap for a read-only listing tool.

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

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

Schema description coverage is 100%, so every parameter (type, site_id, per_page, stock_status) is already documented in the schema, including the deprecated stock_status alias and the 100-item cap. The description adds nothing parameter-specific, so baseline 3 applies.

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

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

States a specific verb and resource ('Get WooCommerce products') plus the exact narrowing condition ('low in stock, out of stock, or on backorder'), which cleanly separates it from generic siblings like woo_list_products or woo_sales_report. An agent can identify the tool's output set without opening the schema.

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

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

The description implies when to reach for it (when you need inventory-at-risk items) and the three status buckets map to the type enum, but it never states when NOT to use it or names an alternative such as woo_list_products for full catalogs. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value by enumerating the returned metrics, which matters because there is no output schema, but it says nothing about custom-range behavior or whether metrics are scoped to the site_id.

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

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

Two sentences, zero filler, and the purpose sentence is front-loaded ahead of the return-value enumeration. Every clause carries information an agent can act on.

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, enumerating the returned metrics is the right compensation, and the annotations carry the safety profile. The remaining gap is the unexplained interaction between the period enum and the custom date_min/date_max range, which the description never addresses.

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

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

Schema description coverage is 100%, so all four parameters (period enum, site_id, date_min, date_max) are already documented in the schema. The description's phrase 'for a given period' adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get WooCommerce sales summary') plus the scoping dimension ('for a given period'), which is enough to tell it apart from the only other report sibling, woo_low_stock_report. It does not explicitly name or contrast with that sibling, so it falls short of a 5.

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

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

There is no when-to-use guidance: nothing tells the agent when a sales summary is the right call versus woo_low_stock_report, nor how to choose between the period enum and a custom date_min/date_max range. The period default of 'month' is only disclosed in the schema, not the description.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered by structured data. The description adds the dry_run preview affordance, which is genuinely useful, but says nothing about reversibility, trashing vs permanent deletion, or permission requirements. Modest value above annotations.

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

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

Two short, front-loaded sentences with zero filler. Slightly terse for a destructive operation 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?

A destructive mutation tool with no output schema, no annotations covering reversibility, and no statement about what trashing actually does to the product (recoverable? hidden from storefront?). The description is too thin for the risk level.

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

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

Schema coverage is 100% and each parameter carries its own description, so the schema does the heavy lifting. The description's dry_run mention duplicates the schema's 'preview without trashing' without adding format or constraint detail. Baseline 3 is correct.

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

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

Specific verb (trash) plus specific resource (WooCommerce product), neatly distinguished from siblings like woo_update_product (edit) and wp_trash_post (different resource). An agent can pick this out immediately.

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

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

The dry_run preview hint gives a sliver of usage context, but there is no guidance on when to trash vs delete, or when dry_run is worth invoking. Implied usage only.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered by structured data. The description adds nothing beyond this - it doesn't explain partial-update semantics (that all fields except 'id' are optional and only supplied fields change), nor what happens on an unknown ID. With a mutation tool touching 13 fields, richer disclosure would be warranted.

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

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

The single sentence has zero waste and is front-loaded, which is good. But it is undersized relative to the tool's complexity (13 parameters, no output schema), so 'appropriately sized' is only partially met.

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 13 parameters and no output schema, the description omits essential context: whether this is a partial or full update, what the response contains, and how errors (e.g., invalid coupon ID) surface. Annotations cover only the safety profile, leaving meaningful gaps.

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

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

Schema description coverage is 100%, so every parameter is already documented in the input schema, including the ISO 8601 expiry format and the enum for discount_type. The description provides no additional parameter meaning, 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?

The description names a specific verb ('Update') and resource ('WooCommerce coupon'), which is immediately understandable. However, it does nothing to differentiate this tool from its close siblings woo_create_coupon, woo_get_coupon, and woo_list_coupons beyond the name itself.

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

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

There is no guidance on when to use this tool versus woo_create_coupon or woo_get_coupon, no mention of prerequisites (e.g., the coupon must already exist), and no exclusions. The agent must infer everything from the name.

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

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

Annotations already declare non-readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real behavioral value by enumerating valid state transitions, which tells the agent the legal state machine. It does not, however, restate the idempotency implication (re-applying the same status is a no-op) that the annotation implies.

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

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

Three tight sentences, front-loaded with the core action and immediately followed by the domain-specific transition guidance and the sibling routing note. No filler.

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

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

For a mutation tool with no output schema, the description plus annotations cover scope, valid transitions, and the alternative tool, which is sufficient to invoke correctly. The only minor gap is that it references a 'woo_update_order' tool that does not appear in the sibling list, a potential routing 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% so the baseline is 3, and the description goes beyond the schema's bare enum by specifying which status transitions are common, adding semantic guidance about the 'status' argument. It does not clarify the optional 'site_id' targeting, but the schema already documents 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+resource ('Update the status of a WooCommerce order') and explicitly carves out what it does not cover by routing to 'woo_update_order' for other fields. An agent can distinguish this status-only tool from a general order update 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 when-to-use context via the common transition list (pending→processing, processing→completed, any→on-hold, any→cancelled) and names the alternative tool for the out-of-scope case. Both the use case and the exclusion are 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the agent knows this is a safe, repeatable write. The description adds the partial-update contract (only send changed fields), but does not disclose side effects such as stock/price recalculation or what an omitted field leaves untouched.

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

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

Two short sentences, front-loaded with the core action and followed immediately by the key usage constraint. No filler or repetition of the title.

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

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

For a 14-parameter mutation tool with no output schema, the description covers the essential patch contract and safety is supplied by annotations. It is still thin on side effects and on the many undocumented parameters, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is only 43% across 14 parameters; fields like sku, status, featured, categories, manage_stock, stock_status and stock_quantity carry no schema description. The description adds nothing about these parameters (e.g. price formats, category ID resolution, stock interaction rules), so it fails to compensate for the coverage gap.

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

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

States a specific verb (Update) and resource (an existing WooCommerce product), which distinguishes it from the sibling woo_create_product. It does not, however, distinguish it from woo_update_variation or explain how it relates to product variations.

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

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

The sentence 'Only provide the fields you want to change' gives useful patch-style usage guidance for this tool, but there is no explicit when-to-use versus alternatives such as woo_update_variation, and no mention of prerequisites like required permissions or ID validity.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so idempotency and non-destructiveness are covered structurally. The description adds nothing beyond them: no statement of which fields are mutable, what happens to omitted fields, permission/auth needs, or rate limits for a 9-parameter mutation.

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

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

A single front-loaded sentence with no wasted words, but the brevity reflects under-specification rather than disciplined conciseness. It is appropriately sized only in the sense that it cannot be shortened further.

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 9 parameters, low schema coverage, and no output schema, the description is far too thin. It omits what can be updated, any constraints or side effects, and any routing to sibling variation/product tools, leaving substantial gaps.

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

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

Schema description coverage is only 44%, so the description is expected to compensate, but it names no parameters at all. Fields like sale_price, regular_price, stock_status, and status (two of them enums) are left entirely to the schema, and the description does not explain their interaction or intent.

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

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

States a specific verb (update) and a scoped resource (a specific variation of a variable product), which is clearer than the bare title. However, it does nothing to distinguish it from siblings like woo_update_product or woo_list_variations, so an agent must infer the boundary from context alone.

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

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

The description gives no indication of when to use this tool versus alternatives, no prerequisites (e.g., need for a parent product ID), and no mention of related sibling tools. Usage is only implied by the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true, so the risk profile is covered structurally. The description adds the useful dry_run preview route, but says nothing about the concrete consequence of activating (site front-end impact, possible fatal errors, effect on an already-active plugin), so it adds only modest context beyond annotations.

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

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

Three short sentences with zero filler: the action is front-loaded, followed by the prerequisite and the safe-preview hint. Nothing repeats itself or could be cut without losing information.

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

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

For a mutation tool with full annotation coverage, a fully described schema, and no output schema, the description supplies the action, the discovery prerequisite, and a dry-run escape hatch. The remaining gap is behavioral detail about side effects on the live site, which an agent would need before acting.

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 all three parameters are documented in the schema, so baseline is 3. The description's only parameter reference ('dry_run=true to preview') restates the schema's own wording for dry_run and adds no format, default, or constraint information for plugin or site_id.

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 ('Activate an installed WordPress plugin'), and the qualifier 'installed' implicitly separates it from wp_install_plugin. However, it never names the natural sibling pair (wp_deactivate_plugin) or restates the distinction, so sibling differentiation is by inference from the name rather than from the text.

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

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

Gives a concrete prerequisite workflow ('Use wp_list_plugins first to find the plugin slug') and a safe alternative path ('Use dry_run=true to preview'). It does not state when *not* to use the tool, e.g. that it should not be used on an already-active plugin, so it stops short of explicit when/when-not guidance.

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

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

The description adds rich behavioral context beyond the annotations: it explains the health-check mechanism (fetch the front page), the specific failure triggers (fatal error, white screen, HTTP 500), and the automatic rollback to the previous theme. This meaningfully elaborates on the destructiveHint=true annotation by showing the safety net that mitigates it.

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

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

Core action and safety behavior are front-loaded, followed by the preview recommendation, in four tight sentences. Slightly verbose with a rhetorical flourish ('never left broken'), but nearly every sentence carries actionable information.

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

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

For a destructive mutation tool with no output schema, the description is complete: it covers what happens on success and failure, the rollback guarantee, and the recommended preceding step. Nothing an agent needs to invoke 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 the site_id and stylesheet parameters are fully documented in the schema. The description adds no additional syntax or format detail beyond the schema, which is the expected baseline 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 (activate) and resource (WordPress theme) and immediately distinguishes itself from siblings like wp_install_theme and wp_update_theme by highlighting the automatic health check. An agent can tell exactly what this tool does and how it differs from installing or updating a theme.

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 recommends running wp_get_theme_preview_url first so the user can preview before activating, which gives a clear ordering/context. It lacks explicit when-not guidance or safety framing on when activation is inappropriate, so it falls just short of a 5.

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

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

Annotations already declare write (readOnlyHint=false), non-idempotent, non-destructive, and open-world behavior. The description adds which link types can be created, which is modest value, but says nothing about permissions, ordering side effects, or what happens on failure.

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

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

Two tight sentences with the action front-loaded and zero filler. Nothing redundant or padded for a tool whose parameters are fully described elsewhere.

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

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

No output schema exists, and the description does not explain what is returned (e.g., new item ID) or how the item interacts with menu_order/parent. With 10 parameters and mutation semantics, it leaves the agent to rely on schema and annotations alone.

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

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

Schema coverage is 100%, so all ten parameters including the two enums are already documented with descriptions. The description's mention of post/page/category/custom URLs broadly mirrors the "type" enum rather than adding syntax or constraints beyond it.

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

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

Specific verb ("Add") plus resource ("item to a WordPress navigation menu") make the operation immediately clear. It distinguishes itself reasonably from siblings like wp_update_menu and wp_list_menu_items, though it does not explicitly name a contrast.

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

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

No guidance on when to use this versus wp_update_menu, wp_list_menu_items, or how to obtain the menu_id it requires. The agent must infer prerequisites and preconditions entirely from the schema.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds nothing beyond that — no note on duplicate-name handling, slug auto-generation, or what the call returns, all of which matter for a non-idempotent create.

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

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

A single well-formed sentence with the action front-loaded and zero filler. It is efficient, though the shortness reflects under-specification rather than tight editing of richer content.

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

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

For a non-idempotent create with five params, full schema coverage and safety annotations, the definition is minimally adequate. Missing are sibling differentiation (wp_create_tag, woo_create_product_category) and any statement about the result of creation or side effects, which the absence of an output schema makes more relevant.

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

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

Schema description coverage is 100%, so all five parameters (name, slug, parent, site_id, description) are already documented, including the parent-ID nesting semantics. The description adds no extra meaning, so the baseline 3 applies.

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