wp_update_post

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation safety is covered. However, the description adds little beyond that: it does not disclose whether unspecified fields remain unchanged or are reset, nor does it explain the return value despite having no output schema. For a mutation tool, these are meaningful gaps.

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 one concise sentence that front-loads the action and resource. It lists the updatable fields efficiently without redundant words. Every phrase 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?

The tool is a straightforward update with 6 parameters, a required ID, and full schema descriptions. Annotations cover idempotence and non-destructiveness. However, the absence of an output schema means the description should ideally mention what the response looks like, but it does not. For its simplicity, the description is adequate but not fully complete.

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 input schema already documents each parameter. The description simply repeats the field names (title, content, status, categories, tags) without adding extra meaning, such as array formats or replacement semantics. Baseline 3 is appropriate.

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 'Update an existing WordPress post' with a specific verb (update), resource (WordPress post), and scope (existing). It lists the updatable fields (title, content, status, categories, tags), which distinguishes it from sibling tools like wp_create_post, wp_delete_post, and wp_get_post. The mention of 'post' implicitly excludes pages (wp_update_page).

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 when an existing post needs modification (via the qualifier 'existing'), but provides no explicit alternatives or exclusions. It does not say 'for new posts use wp_create_post' or 'for pages use wp_update_page.' This is implied usage rather than clear when-to-use guidance.

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