wordpress_list_posts

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

No annotations are provided, so the description carries the burden of disclosure. It explains the return shape ('List of posts with pagination info') and parameter options, but does not mention permissions, rate limits, or explicitly confirm read-only behavior. 'List' implies a safe read, but the lack of explicit safety or error-related context keeps it at a moderate level.

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 well-structured with an 'Args' section listing each parameter on its own line and a 'Returns' section. Every sentence provides necessary information without fluff, making it easy for an agent to scan and extract parameter semantics quickly.

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 has 8 optional parameters, no required fields, and an output schema (as indicated), the description is complete enough: it states the purpose, defines all parameters, and summarizes the return value. There are no significant gaps for an agent to invoke this tool correctly.

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

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

The input schema has 0% description coverage, so the description fully compensates by documenting all 8 parameters. It adds semantic value beyond the schema by enumerating allowed status values ('publish, draft, pending, private, future'), orderby fields, per_page max (100), and describes what each filter does (e.g., 'Filter by category IDs').

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 opens with 'List WordPress posts with filtering and pagination', which states the verb ('List'), the resource ('WordPress posts'), and key capabilities ('filtering and pagination'). This clearly differentiates from siblings like wordpress_get_post (single post) and wordpress_search_posts (search-focused).

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 makes the tool's purpose clear enough for an agent to infer when to use it: when listing multiple posts with optional filters. However, it does not explicitly mention when not to use it or name alternatives like wordpress_search_posts, which would fully satisfy the 'explicit exclusions' bar.

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