wp_pages_create

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

With no annotations provided, the description carries the full burden. It discloses two critical behaviors: default draft status (safe) and publish/future/private requiring a publish tier. This directly addresses the main risks of a create tool (unintended publication and permission requirements). It does not mention return values, error handling, or other side effects, but the disclosed safety and permission context is genuinely valuable and goes beyond a generic 'create' statement.

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

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

The description is two sentences, front-loaded with the primary purpose, and each subsequent clause conveys a distinct, essential piece of information. There is no fluff or repetition. For its length, it is efficiently structured and easy to parse.

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

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

Given the tool's complexity (12 parameters, no output schema, no annotations), this description is incomplete. It lacks information about the return value (e.g., the created page object), auth requirements for basic draft creation, error scenarios, and the meaning of most parameters. It covers only a few key points, leaving significant gaps for an agent trying to use the tool effectively.

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 there are 12 parameters, so the description must compensate. It adds meaning for only three parameters: status (default draft, publish tier requirement), parent (page id for hierarchy), and menu_order (ordering). The remaining nine parameters (date, meta, slug, title, content, author, excerpt, template, featured_media) are left entirely unexplained. With such low coverage, this is insufficient for an agent to correctly construct a request beyond those three fields.

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 states the tool's function: 'Create a new page.' It is specific about the resource (page) and the action (create), distinguishing it from sibling tools like wp_posts_create (posts) and wp_cpt_create (custom post types). The additional details about status, hierarchy, and ordering reinforce the specific purpose without ambiguity.

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 provides clear usage context by noting the default draft status (safe), support for hierarchy via parent, and ordering via menu_order. It also flags that publish/future/private statuses require a publish tier, which helps an agent understand permission boundaries. However, it does not explicitly mention alternatives (e.g., 'for posts use wp_posts_create') or state when NOT to use this tool, so it stops short of full guidance.

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