wp_posts_update

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

Without annotations, the description discloses key behavioral traits: partial update semantics ('Only fields provided are changed') and permission requirements ('Status transitions to publish/future/private require the publish tier'). This adds value beyond the schema, though it does not cover return format or error handling.

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 concise sentences, front-loading the purpose and then adding behavioral nuance. Every sentence earns its place with 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?

Given the complexity (13 parameters) and absence of annotations or output schema, the description covers the critical partial-update behavior and status permission but omits other useful context such as expected response format, error cases for non-existent ids, and potential side effects. It is adequate but not comprehensive for a complex mutation 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?

With 0% schema description coverage, the description must compensate. It does by explaining that all fields are optional and partially updated, which is critical for understanding the parameter semantics. However, it does not describe any individual parameters or their formats (e.g., date, meta, categories), leaving the agent to rely on parameter names and types.

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 'Partially update an existing post by id', which specifies the verb (update), resource (post), and scope (by id, partial). It distinguishes this from sibling tools like wp_posts_create, wp_posts_publish, and wp_posts_schedule by focusing on updating an existing 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?

The description provides clear context: use for existing posts by id and only fields provided are changed. It also mentions the publish tier requirement for status transitions, which is a practical prerequisite. However, it does not explicitly name alternatives or state when not to use it, though this is largely implied by 'existing post by id'.

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