AI Engine for WordPress

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

Annotations already declare destructiveHint=true, but the description adds the crucial detail that when append is false, it 'replace[s] all terms of that taxonomy on the post' — a concrete disclosure of exactly what gets destroyed. This is genuinely useful beyond the annotations.

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

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

Two sentences, no waste, and the destructive replace behavior is front-loaded after the core action. Every sentence earns its place.

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

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

For a 4-parameter destructive mutation with no output schema, the description covers the key destructive behavior and append semantics well. But it omits the required-vs-optional distinction and any default for taxonomy, leaving gaps an agent must fill 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 coverage is 0%, so the description carries the burden. It fully explains the append parameter and implies taxonomy scoping, but leaves ID (post identifier) and terms (term IDs) unexplained in form or meaning. Minimum viable given the low 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: 'Attach terms to a post.' An agent can tell it is the write counterpart to wp_get_post_terms. However, it never names the sibling tools it replaces or complements, 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?

The description explains when to set append (add vs replace), which is conditional usage guidance. But it gives no guidance on when to choose this tool over wp_update_post or wp_get_post_terms, nor any prerequisites or scope conditions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the risk profile is covered. The description adds regex/flag/backreference capability, but omits critical behavior for a destructive operation: whether all matches or only the first are replaced, what happens when the search pattern matches nothing, and whether this bypasses revisions.

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

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

Two sentences with zero padding, and the core distinction (targeted field edit without resending content) is front-loaded ahead of the regex caveat. Nothing here 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, open-world mutation tool this covers the essentials: target field, regex mode, and replacement syntax. The remaining gap is the outcome semantics (replace-all vs. first occurrence, no-match behavior), which matters given the destructive annotation and the absence of an output schema.

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

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

Schema coverage is 100%, so all six parameters are documented in the schema itself. The description's regex/flag sentence largely restates the schema's own regex and flags descriptions without adding new meaning, so this sits at the baseline for a fully-annotated 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 (find and replace) applied to a specific resource (text inside one named field of a post), and adds the distinguishing scope 'without sending the whole content again', which separates it from the full-content siblings. It stops short of naming wp_update_post or wp_write_blocks explicitly, so differentiation must be inferred.

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 'without sending the whole content again' implies the intended use case (surgical edits vs. a full update), but the description never says when to prefer this over wp_update_post or wp_write_blocks, nor does it state any exclusions or prerequisites. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safe read-only profile is covered. The description adds the date-scoping context but says nothing about permissions required or the shape of the count result, which is the main remaining gap for a counting 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?

A single well-formed sentence with zero padding and the key scope ('Media Library') front-loaded. Its brevity edges toward under-specification, but nothing in it is wasted.

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

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

For a simple two-parameter read-only counter with no output schema, the description covers the core purpose but leaves the date parameter format and the returned count structure unexplained. Adequate but with clear gaps an agent would have to probe for.

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

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

Schema description coverage is 0%, so the description carries the burden for 'after' and 'before'; it does clarify that they form an optional date range, which is real added meaning. However, it omits the expected format (ISO 8601? relative?) and whether bounds are inclusive, leaving the agent to guess.

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

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

The description gives a specific verb and resource: 'Count the items in the Media Library', which clearly distinguishes it from wp_count_posts and wp_count_terms by resource. It doesn't explicitly name those siblings, but the resource noun is unambiguous enough that an agent can select it correctly.

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

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

The phrase 'optionally within a date range' implies when the parameters are relevant, but there is no explicit routing guidance such as 'use wp_get_media to retrieve the actual items' or any prerequisite/exclusion. Usage is implied 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=false, so the safety profile is covered. The description adds useful context by listing the statuses counted and the default post type, but it does not describe the return shape or whether counts are affected by permissions.

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

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

The description is two short sentences with no wasted wording. The key scoping constraint and default value are front-loaded and easy to scan.

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

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

For a simple read-only count tool whose annotations already cover safety, the description gives enough context to invoke it correctly: statuses counted, one post type, and the default. It could mention the return format, but no output schema is present and the omission is minor for this tool.

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

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

Schema coverage is 0% and post_type has no schema description, so the description carries the burden. It compensates well by explaining that the parameter scopes the count to one post type and defaults to 'post'; it does not enumerate valid post-type values, but that is a minor gap for a single open string parameter.

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

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

The description states a specific verb and resource (count posts), enumerates the supported statuses, and scopes the operation to one post type. This clearly separates it from siblings like wp_get_posts and wp_count_media/terms.

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 purpose: count posts grouped by status for a post type. However, the description does not explicitly say when to use this instead of wp_get_posts or the other count tools, nor does it state any prerequisites or exclusions.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. Beyond that the description adds nothing: it does not say whether counts include empty/hidden terms, whether the result is a single integer or per-status breakdown, or how it behaves for an unknown taxonomy.

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, which is the right shape for a simple counting tool. The brevity is appropriate to the operation, though it leaves little room for the missing value details.

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

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

For a one-parameter tool with no output schema and solid annotations, the safety story is complete but the input story is not: the agent still does not know what taxonomy identifiers are accepted or what the returned count represents. A short example or list of valid taxonomy values would close 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 0% and the single required parameter 'taxonomy' has no type detail, enum, or example. The phrase 'in a taxonomy' only restates the parameter name and does not tell the agent what values are valid (e.g., 'category', 'post_tag', custom taxonomy slugs).

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 (count) and resource (terms in a taxonomy), which cleanly separates it from siblings like wp_get_terms (listing) and wp_count_posts/wp_count_media (other counting targets). It does not explicitly name those alternatives, so it stops short of a 5.

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

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

There is no guidance on when to call this instead of wp_get_terms or wp_get_post_terms, nor any mention of preconditions such as the taxonomy being registered. The agent must infer the use case entirely from the verb 'count'.

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 write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description's burden is lower, but it adds nothing: no statement about what approval status values mean, whether an unapproved comment is publicly visible, or whether duplicate comments are blocked. For a write tool with an open-world hint, that is a meaningful gap.

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

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

Two tight sentences, front-loaded with the action. The second sentence spends its space on required/optional restatement rather than information the schema doesn't already contain.

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 6-parameter write tool with 0% schema coverage and no output schema needs the description to explain approval semantics, author-field defaults, and the return shape. None of that is present, so an agent would have to guess at the most consequential parameter.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only restates which two parameters are required (already declared in the schema's required array) and loosely labels the others; it never explains the valid values for comment_approved (a string, likely '0'/'1'/'hold') or format expectations for email/URL.

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

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

States a specific verb and resource ("Add a comment to a post"), which is unambiguous on its own. It does not differentiate from siblings like wp_update_comment or wp_get_comments, so the agent gets no help choosing among the comment-related tools.

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

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

No guidance on when to use this versus wp_update_comment (for editing existing comments) or wp_create_note. No prerequisites are stated, such as needing an existing post_id or whether the comment will be held for moderation.

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-but-non-destructive, closed-world profile, so the bar is lower. The description adds real value beyond them: the WordPress 6.9+ requirement, thread reply semantics via parent_id, and the resolution rule that the first block containing anchor_text wins.

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 create action and version gate front-loaded before the block-location and threading options. Every clause maps to something 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?

Coverage is good for a five-parameter create tool with rich schema and annotations, and no output schema exists so return values need not be explained. The one gap is that it never says whether the new note's identifier comes back, which an agent needs to chain a reply via parent_id.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description mostly restates schema text ('short exact snippet', 'reply to an existing note with parent_id') without adding format, length, or disambiguation rules beyond what is already there; a 3 baseline is correct.

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

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

States a specific verb and resource ('Add an editor note to a block of a post') plus a version constraint and a concrete UI analogue ('editor's Notes panel'). An agent can tell this creates a block-level annotation rather than a comment or a post edit, even though the nearest sibling wp_update_note is not named.

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

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

Gives clear invocation context: use anchor_text or block_index to target a block, or use parent_id to reply to an existing thread. It does not route between siblings (e.g., wp_update_note for edits, wp_create_comment for reader comments), so the boundary with alternatives 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 a non-read-only, non-destructive, open-world write operation, so the description does not need to restate safety. It adds useful default behavior — draft status unless overridden — but omits permissions/capabilities, duplicate-slug behavior, and what is returned after creation.

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?

Five short sentences, front-loaded with the operation, then required arguments, content format, defaults, and meta behavior. Every sentence carries actionable information with no filler.

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

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

For a 7-parameter mutation tool with no output schema and very low schema description coverage, the description is only partially complete. It covers the core creation behavior and defaults, but does not address the created post's return value, permissions, or the two undocumented parameters, 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 only 14%, so the description must compensate. It does explain post_title is required, post_content accepts HTML/blocks/Markdown, the draft and post defaults, and meta_input's role, but it leaves post_name and post_excerpt undocumented and does not enumerate accepted post_status values.

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

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

States a specific verb and resource ('Create a post, page or item of another post type'), which clearly separates it from update, alter, get and delete siblings. An agent can identify the correct operation 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 create intent is implied by the verb and by the defaults for status and type, but the description never states when to use this versus wp_update_post, wp_alter_post or wp_write_blocks. No explicit exclusions or alternative-routing guidance are provided.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the taxonomy context and which fields are optional; it says nothing about duplicate-name behavior, permission requirements, or whether the taxonomy must already exist.

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

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

A single front-loaded sentence with no filler. It is efficient, though the brevity comes at the cost of the missing semantics noted above.

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 5-parameter mutation tool with 0% schema coverage and no output schema needs the description to explain the parent ID relationship, duplicate handling, and at least that a term ID is returned for follow-up calls. None of that 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 0%, so the description must carry the parameter meaning, and it only names three fields (slug, description, parent) and labels them optional. Critically, it never explains that 'parent' is the integer ID of an existing term in the same taxonomy, nor what slug format is expected.

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 term) plus the domain (taxonomy, category/tag), which is enough to distinguish it from wp_update_term or wp_get_terms. It does not explicitly distinguish itself from the near-neighbor wp_add_post_terms, which assigns existing terms rather than creating them.

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

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

The 'such as a new category or tag' phrasing hints at use, but there is no statement of when to choose this over wp_add_post_terms (attach existing term) or wp_update_term (modify existing term). 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?

With destructiveHint=true already declared, the description adds the crucial nuance that this is a reversible soft delete ('It can be restored from the trash'), which materially changes how an agent should weigh the risk. It doesn't mention permission requirements or behavior on an already-trashed or invalid ID, keeping it from a 5.

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

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

Two short sentences, zero waste; the scope (post types covered) comes first and the reversibility note second, which is the right order for an agent assessing risk.

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

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

For a one-parameter tool with destructive annotations and no output schema, the description covers scope and reversibility, which is most of what an agent needs. Missing only auth/permission expectations and failure 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 coverage is 0% for the single ID parameter, and the description only says 'by ID', which implies the post identifier but adds no format, type, or validity constraints. It partially compensates for the coverage gap but a 3 is the fair ceiling.

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 ('Move a post, page or item of another post type to the trash') and clarifies the soft-delete semantics, which distinguishes it meaningfully from wp_update_post despite the 'delete' name. It stops short of naming a sibling tool, so it lands at 4 rather than 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 implies the use case (removing content from the site) but gives no explicit guidance on when to prefer this over wp_update_post with a status change, or over wp_alter_post. Usage is inferable but never 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=false, so safety needs no restating. The description still adds non-obvious behavior: a silent default page size of 10 when limit is omitted, and that approval status 1 means a note thread is resolved — a semantic quirk an agent could not guess. It stops short of describing ordering or what happens when offset/paged combine.

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, no filler, each adding distinct information: returned shape, filter set with the default limit, then the note-specific edge case. The most surprising fact (note/approval semantics) is placed last where it reads naturally after the filter list.

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

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

For a 9-parameter read tool with no output schema and thin schema coverage, the description is largely sufficient: it covers result shape, filtering, default paging and the note mode. The gaps are pagination semantics for paged/offset and valid status values, which the schema also leaves as a bare string.

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

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

Schema description coverage is only 33%, so the description must carry the load, and it names six of the nine filters (post_id, status, search, user_id, author_email, type) plus the limit default. It leaves paged and offset unexplained, so an agent must guess their interaction with limit.

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 ('List comments') and immediately enumerates the returned fields (post, author, content, date, approval status), so an agent knows exactly what it gets. The explicit note-type branch ('type set to "note" lists editor notes on posts') separates it from the sibling write tools wp_create_note/wp_update_note and from wp_get_posts.

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 enumerates the filter dimensions, which implies when the tool is useful, and the note-type sentence gives one concrete usage scenario. However, it never states when NOT to use it or names an alternative (e.g. wp_get_posts for posts, wp_update_comment for changing a comment), 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=false, so the safety profile is fully covered by structured data. The description adds one genuinely useful behavioral fact – a default page size of 10 – but says nothing about what after/before do (pagination cursor vs date string) or how results are ordered.

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 what the tool returns, then the available filters, then the default size. Every sentence carries information the agent needs and there is zero 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 read-only list tool with no output schema, the description supplies the returned fields and the default page size, which is most of what an agent needs to call it. The remaining gap is the semantics of after/before for paging, which neither the schema nor description explains.

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

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

With only 33% schema description coverage, four parameters (after, limit, search, before) are undocumented in the schema, and the description only partially compensates: it maps search/uploader/date range to the filters and clarifies limit's default of 10. The formats for after and before remain unspecified in both places.

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 items in the Media Library') and the fields returned (ID, title, URL), which cleanly separates it from mutation siblings like wp_update_media and wp_upload_media. It doesn't explicitly name a sibling it is not, so the differentiation is implicit 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?

The description implies usage through its filter list (search text, uploader, date range), so an agent can infer this is the tool for browsing media by those criteria. However, it never says when to use this versus wp_get_posts or wp_count_media, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value beyond that by disclosing what the response contains (title, content, status, dates, permalink) and how content_format alters the content, which matters since there is no output schema. It omits failure behavior for an invalid or non-existent 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 short sentences, front-loaded with the core action and returned fields, with the option described second. No filler or repetition.

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

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

For a two-parameter read tool with annotations covering safety, the description supplies the main missing piece: the returned fields, since no output schema exists. It could go slightly further on error/empty-ID behavior and on whether pages and other post types are all addressable.

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

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

Schema coverage is 50%: content_format is fully documented in the schema (enum plus behavior), so the description's mention of it is redundant. The undocumented 'ID' parameter gets only the phrase 'post or page by ID', which does not clarify whether it accepts any post-type ID or only posts/pages. Baseline 3 fits.

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

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

States a specific verb and resource ('Get one post or page by ID') and enumerates the returned fields, which is clear and actionable. It does not explicitly distinguish itself from sibling wp_get_posts or wp_get_post_snapshot, so an agent must infer the singular-vs-list split from the name alone.

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

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

'by ID' implies the retrieval-by-identifier case, but there is no explicit statement of when to use this over wp_get_posts (listing) or wp_get_post_snapshot (versioned state). Usage is implied rather than guided.

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 confirms the retrieval operation but relies on annotations for safety profile (readOnlyHint: true). It adds minimal additional behavioral detail beyond what the structured data already provides, making it solid but not exceptionally 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?

The definition is brief and highly efficient. The two sentences cover purpose and parameter behavior without redundancy, placing the most important logical constraint (the 'key' usage) prominently.

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 clear semantic explanation of parameters and strong safety annotations, the definition provides everything necessary for an agent to select and correctly invoke the tool based on the task.

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?

Given the 0% schema description coverage, this description is vital. It thoroughly explains the operational logic of the 'key' parameter—how it changes the behavior from a full list retrieval to a specific field lookup—adding crucial semantic meaning.

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

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

The description clearly identifies the action (Get), the resource (custom fields of a post), and the primary method (by ID). It successfully distinguishes itself from other sibling tools like `wp_get_post` or `wp_get_posts`.

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

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

It provides explicit usage rules for the optional 'key' parameter: provide it to target a single field, or leave it out to return all fields. This directs the agent's intent perfectly.

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

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

Annotations already declare readOnly and non-destructive, so the bar is lower; the description adds valuable behavior: newest-first ordering, excluded full content, default result count of 10, and offset/paged paging semantics. It stops short of noting rate limits or auth requirements but covers the operation's shape well.

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

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

Three tight sentences, front-loaded with the core action and scope, followed by filtering and pagination details. No filler; each sentence carries unique, useful 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?

No output schema exists, so describing the returned fields is necessary and done. Combined with default-limit and pagination disclosure, an agent has enough to call it correctly; minor gaps (author__not_in, ordering param) remain.

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

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

With only 27% schema coverage across 11 params, the description compensates well: it explains post_type, post_status, search, author (ID or slug), date-range (after/before), limit, offset and paged. Only author__not_in and the author_name-ignored-if-author-set nuance are left to the schema, otherwise coverage is strong.

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

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

Specific verb (List) and resource (posts/pages/custom post types) with scope ('newest first') and explicit return fields ('ID, title, status, excerpt and link, without the full content'). This distinguishes it clearly from siblings like wp_get_post (singular) and wp_count_posts.

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 how to filter (post_type, post_status, search, author, date range) and how to paginate, giving clear usage context. It does not explicitly name alternative tools or when-not to use this one, keeping it just shy of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scoping constraint that sections can be trimmed to avoid huge payloads, which is genuinely useful context, but says nothing about response shape or size beyond that.

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 capability and followed by the one actionable knob. Nothing is redundant or 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?

With 100% schema coverage, no output schema, and annotations covering safety, the description supplies enough for correct invocation. The only minor gap is that it never distinguishes this snapshot tool from wp_get_post/wp_get_post_meta for an agent choosing among 30 siblings.

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

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

Schema description coverage is 100%, so all four parameters including the content_format enum are already documented in the schema. The description's 'Use include or exclude to limit the sections returned' only restates the pair's purpose, adding no syntax or edge-case detail beyond what the schema provides. 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 ('Get everything about one post by ID') and enumerates the section scope: fields, custom fields, terms, featured image, author. That aggregate framing distinguishes it from the narrower siblings wp_get_post_meta and wp_get_post_terms, though it never names an alternative explicitly.

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

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

Usage is implied (call it when you need a complete post payload) and the second sentence gives operational advice on include/exclude, but there is no explicit when-to-use vs when-not, and no routing against wp_get_post which returns overlapping data.

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=false, so the safety profile is covered. The description adds that taxonomy filtering is optional but says nothing about return shape, ordering, or behavior when the post has no terms.

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 optional-filter qualifier front-loaded; no wasted words.

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

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

For a simple read tool with annotations covering safety and no output schema, the description is minimally adequate. It lacks detail on returned term fields, ordering, and empty-result behavior, which would help an agent use the result correctly.

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

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

Schema coverage is 0%, so the description must compensate. It does clarify that taxonomy is an optional filter and that ID refers to a post, but doesn't specify format (term ID vs slug for taxonomy) or defaults.

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 (terms attached to a post), which distinguishes it from wp_add_post_terms and wp_get_terms. It's clear what the tool returns, though it doesn't explicitly contrast with the site-wide wp_get_terms 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?

The mention of "optionally for one taxonomy only" implies the usage pattern (pass taxonomy to narrow results) but doesn't state when to prefer wp_get_terms or how missing terms are handled. Usage is inferable but not explicit.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that only public post types are returned and that each entry includes a key and label, which is useful context beyond the annotations, but it does not describe ordering, completeness, or edge cases.

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

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

It is a single front-loaded sentence with no wasted words. The core operation and return shape are stated immediately, and the examples are compact and helpful.

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

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

For a zero-parameter, no-output-schema discovery tool, the description gives enough detail: it returns public post types with key and label. It could be slightly more complete by clarifying whether built-in and custom public types are both included, but no critical information is missing for correct invocation.

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

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

The tool has zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description appropriately avoids inventing parameter behavior and instead focuses on what the zero-argument call returns.

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: list public post types with their key and label. It also gives examples (post, page, product) that clarify this is schema discovery, not fetching posts, and distinguishes it from siblings such as wp_get_posts and wp_get_taxonomies.

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 'List the public post types...' and an agent can infer this is for discovering available post type identifiers before calling wp_get_posts. However, the description does not explicitly say when to use this versus wp_get_taxonomies or wp_count_posts, nor does it mention any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds no behavioral context beyond the returned field list — no auth requirements, caching, or error behavior. It does at least signal what data comes back, which is useful with no output schema.

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

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

A single front-loaded sentence with the returned fields listed immediately. No filler, no redundancy.

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

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

For a zero-parameter, read-only tool with no output schema, listing the returned fields is exactly the missing piece the description supplies. The only shortfall is that it doesn't mention that other site settings may also be returned or how the response is shaped.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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) plus the exact resource (site information) and enumerates the fields returned: name, tagline, address, time zone. That clearly distinguishes it from the sibling tools, which are all post/media/term/comment operations. No explicit sibling callout, but none is needed here.

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 tool for site-level metadata rather than content operations, but the description never states when to call it or what it is not for. There are no real alternatives, which keeps this from being a serious gap.

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 this is a read-only and non-destructive operation, so they cover the main behavioral constraints. The description adds minor context by mentioning concrete examples (categories and tags), which is helpful but not critical behavioral disclosure.

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

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

The description is a single, efficient sentence that is front-loaded with the most essential information. It achieves high clarity with minimal word count.

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

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

Given the tool's simplicity (single input parameter, read-only annotations), the description is reasonably complete. It tells the agent exactly what result to expect from the function's purpose.

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?

Since schema coverage is 0%, the description is vital. It clarifies that the input parameter 'post_type' must be a valid WordPress post type, adding necessary semantic constraints beyond the simple 'string' type provided in the schema.

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

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

The description clearly identifies the action (List) and the resource (taxonomies) related to the key input (post type). It effectively distinguishes the function's purpose, though it doesn't explicitly compare it to other list functions.

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 is purely descriptive of the tool's function and scope. It offers no guidance on when this tool should be used versus alternatives (like listing terms within a taxonomy or getting post types themselves).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered and the description's burden is lighter. The description adds taxonomy scoping but says nothing about default page size, ordering, or whether an omitted 'limit' silently truncates results — meaningful 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?

A single front-loaded sentence with the core action first and the optional filters trailing. The parenthetical example earns its place by making 'terms' concrete; 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?

With 0% schema description coverage, no output schema, and four parameters, the description leaves the agent guessing about the return shape and the effect of an unspecified 'limit'. The read-only annotations cover safety, but for a paginated listing tool the missing default-limit and result-shape information is a real operational gap.

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

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

Schema description coverage is 0%, so the description has to carry the load, and it does explain three of the four parameters conceptually: taxonomy, search text, and parent term. It never mentions 'limit', nor whether 'parent' takes a term ID versus slug, nor whether search is a substring or prefix match.

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

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

States a specific verb and resource ('List the terms of a taxonomy') and adds a concrete example ('every category') so the resource is unambiguous. It does not explicitly distinguish itself from wp_get_post_terms, wp_count_terms, or wp_get_taxonomies, so an agent must infer the boundary rather than be told.

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

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

There is no guidance on when to choose this over the closely related siblings (wp_get_post_terms for a post's terms, wp_count_terms for counting, wp_get_taxonomies for the taxonomy list itself). The 'optionally filtered' phrasing describes parameter behavior, not usage conditions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context beyond them: the sources patterns come from, and the cost warning that include_content markup "can be large". It doesn't cover pagination behavior or result ordering.

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

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

Three short sentences: what it returns, how to filter, and the opt-in expensive flag last. Every sentence carries information an agent needs; nothing is padding.

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

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

With no output schema, the description enumerates the returned fields (name, title, categories, description) and the extra payload when opted in. Combined with full schema coverage and read-only annotations, an agent has everything needed to call it correctly and interpret the response.

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 describes all four parameters with defaults, so baseline is 3. The description earns a bump by explaining the purpose of include_content (raw block markup that can be planted into a post) rather than just restating its type, though it adds nothing for limit or the category slug format beyond the schema.

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

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

States a specific verb and resource ("List the block patterns available on the site") and explains what a pattern is ("ready-made layouts from WordPress, the theme and plugins"), plus the fields returned. It also distinguishes itself from the post-mutation siblings by noting the markup is consumed by Update post or Edit post text, so an agent knows this is the read/discovery side.

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

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

Gives clear conditional guidance: filter by search text or category, and set include_content only when the block markup is actually needed. It names the downstream tools for the retrieved markup, which is a strong routing hint. It stops short of explicit when-not-to-use guidance (e.g. versus wp_write_blocks).

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 destructiveHint=true, so the description does not need to carry the full safety burden. It adds value by clarifying that an empty media_id removes the featured image, but it does not explain that setting a new image replaces the existing one or detail permissions/reversibility.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states the primary action and then the conditional removal behavior.

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

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

For a two-parameter mutation with annotations covering safety, the description is adequate but not complete. It omits that setting a featured image overwrites any existing one and gives no handling details for invalid media IDs, though no output schema exists to explain return values.

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

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

Schema description coverage is 0%, so the description must compensate. It identifies post_id as the post whose featured image is set and explains media_id as a Media Library item with the special empty-value removal behavior, but it does not fully document the parameters beyond these points.

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 ('Set') and resource ('featured image of a post'), plus the removal case when media_id is empty. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like wp_update_post or wp_alter_post.

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

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

It implies the operation and gives a useful condition for removal when media_id is empty, but it does not state when to use this versus alternatives such as wp_update_post, nor does it mention prerequisites.

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

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

The annotations already declare destructiveHint=true and openWorldHint=true, so the description does not need to restate safety. It adds useful behavioral context by naming the approval values and the fields being changed, but it does not mention permissions, reversibility, or the effect of marking a comment as spam.

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

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

The description is a single front-loaded sentence with no wasted words. The core action and affected fields are stated 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?

Given the destructive, open-world mutation and the nested fields object with no schema descriptions, the description is adequate but not complete. It states what can be updated, but leaves nested parameter structure and mutation side effects largely to the annotations and 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 0%, so the description must compensate. It clarifies that comment_ID identifies the comment and that content or approval status can be updated, including the values approve, hold, and spam. It does not explain the nested 'fields' wrapper or the fact that comment_approved is a string despite acting like an enum.

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

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

The description names a specific verb and resource ('Update a comment by ID') and states the two editable aspects: content and approval status. It is clear what the tool does, though it does not explicitly contrast itself with siblings such as wp_create_comment or wp_get_comments.

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 update-by-ID phrasing, and the allowed approval statuses are listed. However, it gives no explicit when-to-use guidance, prerequisites, or alternatives, so the agent must infer the appropriate context.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=true, so the description adds nothing about what makes this destructive (e.g., whether omitted fields are cleared or preserved), what permissions are required, or whether changes are reversible. For a mutation tool with a destructive hint, this is a notable gap.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity contributes to the gaps in other dimensions.

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

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

For a destructive mutation with no annotations explaining behavior, no output schema, and 0% schema coverage on five parameters, the description is too thin. It omits the required ID, the effect of omitted fields, and any error or permission context.

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

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

Schema description coverage is 0%, so the description must compensate; it names four of the five parameters (title, caption, description, alt) but never mentions the required ID parameter or explains omission semantics. Field mapping is useful but leaves critical semantics undocumented.

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

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

States a specific verb (update) and resource (Media Library item) plus the exact fields affected, so it is distinguishable from wp_upload_media and wp_update_post. It stops short of differentiating the intended item scope more explicitly, but the purpose 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?

Naming 'Media Library item' implies this operates on existing attachments rather than new uploads, which implicitly separates it from wp_upload_media. However, there is no explicit when-to-use guidance, no mention of prerequisites, and no named alternative for non-media post updates.

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 the mutating nature is known. The description adds no behavioral context beyond that: it does not say that supplying 'content' overwrites the existing text irreversibly, that resolving a thread is effectively a state change others will see, or that status only applies to top-level notes (that constraint lives only 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?

A single well-formed sentence with the verb and the two modes front-loaded and no filler. It is arguably too terse for a destructive tool rather than too long, which is a completeness issue rather than a conciseness one.

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, out-of-band-free write tool with no output schema and an undocumented required note_id, the description is thin: it does not cover what happens on success, whether partial updates are allowed, or the overwrite/resolve consequences. An agent could call it but would not know the side effects it is signing up for.

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 67%, with 'content' and 'status' documented in the schema; the description redundantly restates both operations but adds no format or constraint detail. The required 'note_id' parameter carries no description anywhere, so the gap is not compensated by the prose.

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 ('Edit the text of an editor note') and enumerates the two operating modes: content editing and thread status change. It is clearly distinguishable from read-side siblings like wp_get_comments, though it never names an alternative (e.g., wp_create_note or wp_update_comment).

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 two modes of use are implied by the sentence, but there is no explicit when-to-use guidance, no prerequisites, and no routing to a sibling such as wp_create_note for new notes or wp_update_comment for comment threads. The agent must infer the boundary itself.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds real value on top by disclosing a specific destructive side effect: 'Passing post_category replaces all of the post's categories.' It also notes the underscore-key refusal rule for meta_input. It stops short of covering reversibility, revisions, or error 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?

Four tight sentences, front-loaded with the verb and resource, with the destructive caveat placed last where it is still salient. The field list slightly duplicates the schema but serves as a quick capability summary.

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

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

For a destructive mutation with nested objects and no output schema, the description covers partial-update semantics, custom-field restrictions, and scheduling behavior adequately. It is thin only on return shape and what happens to unspecified fields, which the schema only implies.

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 75% schema coverage the schema does most of the work, but the description adds meaning beyond it: partial-update semantics (only pass the fields to change), the fields/meta_input split, and the category-replacement consequence. It also mentions 'slug, date' which are not enumerated in the fields schema, helping the agent use additionalProperties.

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 ('Update an existing post by ID') plus the set of updatable fields, so the agent knows exactly what is being modified. It does not differentiate from plausible siblings such as wp_alter_post or wp_write_blocks, which an agent could easily confuse with this one.

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 explains mechanics ('Pass the fields to change in fields'), which implies usage for partial updates, but it never states when to choose this over wp_alter_post, wp_create_post, or wp_write_blocks, nor any exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds no behavioral context beyond the field list — nothing about what happens to omitted fields, whether changing a slug breaks existing links, or what the destructive aspect entails. It also fails to warn that this overwrites existing values.

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

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

A single compact sentence with no filler and the updatable fields front-loaded. Its fault is under-specification, not verbosity.

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

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

For a destructive mutation with six undocumented parameters and no output schema, the description should clarify required identifiers, the taxonomy scope, and the consequences of partial updates. None of that 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?

With 0% schema description coverage, the description carries the full burden, yet it only names four optional fields without explaining them and omits the two required parameters (term_id, taxonomy) entirely. An agent must infer that term_id identifies the term and taxonomy scopes 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 ('Update') plus resource ('an existing term') and an enumeration of the mutable fields. It is distinguishable from siblings like wp_update_post or wp_update_comment by the 'term' resource, though it never explicitly juxtaposes itself with wp_create_term or wp_get_terms.

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_term (create), wp_get_terms (read), or wp_add_post_terms (assign). 'Existing term' weakly implies the term must already exist but nothing about prerequisites, taxonomy requirements, or when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds genuinely useful context by saying WordPress itself downloads the URL (a server-side fetch), but omits permission requirements, allowed file types, size limits, and whether an existing filename is overwritten.

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 action and the two modes. The trailing clause listing optional metadata is slightly redundant with the schema but does convey optionality at a glance.

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 six-parameter mutation tool with no output schema and no required parameters, the description leaves important gaps: what identifier is returned (an agent needs the media ID for follow-ups like wp_set_featured_image), and what happens when both or neither source is supplied.

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

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

With only 50% schema description coverage, the description compensates by stating that url and base64/filename are mutually exclusive alternatives and that title, description and alt are optional metadata. It still doesn't say whether one of the two sources is mandatory, which matters given zero required parameters.

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

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

States a specific verb and resource ('Add a file to the Media Library') and enumerates the two supported ingestion modes. It implicitly distinguishes itself from wp_update_media and wp_get_media by framing the action as adding a new file, though no sibling is named.

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

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

The description clarifies the choice between the URL mode and the base64+filename mode, which is real usage guidance. However, it never says when to use this tool versus wp_update_media, nor any preconditions such as required capabilities or that exactly one source must be supplied.

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

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

Annotations already flag destructiveHint=true and write access; the description adds the concrete consequence by stating the default mode is replace, i.e. existing post_content is overwritten. That is exactly the context an agent needs before a destructive call. It stops short of covering validation failures or whether other post fields are left 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?

Purpose is front-loaded in the first sentence, followed by a dense but necessary block-type catalogue and the mode note. Almost every clause earns its place; the type list is compressed but readable.

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, three-parameter mutation tool with no output schema, the description covers purpose, overwrite semantics, and the block payload vocabulary. Remaining gaps are error/validation behavior and what the call returns, which are secondary but not negligible given the destructive hint.

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

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

Schema coverage is 100% for top-level params, but the blocks array items are declared as arbitrary objects with the schema explicitly deferring to the description. The description therefore carries the real payload contract by naming 13 block types and their fields. It omits per-type required fields and item formats (e.g. list items as strings, nested group/columns shape), so it is not fully self-sufficient.

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: "Write block editor content to an existing post from a list of block specs." The block-type enumeration makes it obvious this is block-level content authoring, not a generic post field update. It does not name the nearest sibling (wp_update_post) as the raw-content alternative, so it falls short of full sibling differentiation.

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

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

The description implies usage through "existing post" and the block spec list, and the schema adds "create it first with wp_create_post." But it never says when to prefer this over wp_update_post or wp_alter_post, nor what conditions (post type support for blocks, Gutenberg vs classic editor) make it inappropriate.

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