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

Beyond the readOnly/idempotent annotations it discloses substantial behavior: search_meta scans only the newest 3000 posts and caps meta_hits at 50 posts, protected "_" keys require manage_options plus an allowlist filter, and results come in WordPress's search order with no pagination. The edit_posts capability requirement is also stated, which the annotations do not cover.

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

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

Purpose and routing constraints are front-loaded and every clause carries information (limits, permissions, return shape). It is, however, a single long run-on with nested parentheticals that is harder to parse than a split into purpose / return / constraints sentences.

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

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

No output schema exists, yet the description fully enumerates the return shape (query, total, results fields, meta_hits structure) and the ordering. Combined with permission requirements and the sibling routing hints, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by noting per_page bounds the single returned page, that type=revision is refused, and that search_meta matches meta values as substrings while omitting values. It stops short of explaining query matching syntax beyond deferring to WordPress's own semantics.

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

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

States a specific verb and resource ("Full-text search of title and body over the posts the account may read") plus the scope constraint (any post type, revision refused). It explicitly distinguishes itself from siblings by naming wp_list_posts for browsing and wp_get_post_meta for meta values, so an agent can route without opening another schema.

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

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

Gives explicit when/when-not: use this with a search term, use wp_list_posts without one, use wp_get_post_meta to read a meta value. It also flags a refusal case (type revision) and the absence of a page parameter, leaving nothing to inference.

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