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

Annotations already flag a mutation (readOnlyHint=false, destructiveHint=true), so the safety bar is lower, but the description adds a genuinely important non-obvious trait: the change goes through Royally approval and 'nothing on the site changes until then.' That tells the agent the write is deferred/asynchronous and it must not expect immediate effect. It omits permissions and what happens to fields left unspecified.

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?

Front-loads purpose, then the SEO use case, then the critical approval caveat. The '(site: demo.royalplugins.com)' clause duplicates the site_id enum and is filler, but otherwise the sentences are efficient and the highest-value fact (approval) is included.

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?

For a destructive mutation with no output schema and sparse param docs, the description covers the most important behavioral fact (approval gating) but leaves gaps: no return value / pending status, no permission or failure conditions, and no note on partial updates. Adequate but not 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 coverage is only 17% (just site_id), so the description must compensate. It partially does by naming the four metadata fields that map to title/caption/alt_text/description, adding meaning beyond the empty schema entries. However the required 'id' has no explanation in schema or description, and it doesn't clarify whether other existing fields are preserved.

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 ('Update metadata') plus resource ('existing media attachment') and enumerates the affected fields (alt text, caption, title, description). It's clear what it does and that it targets existing media, though it never names the sibling to prefer for uploads (wp_upload_media) or reads (wp_get_media).

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 phrase 'images already in the library' implies the boundary against upload tools, and the SEO alt-text tip gives a concrete use case. But there is no explicit when-not, no prerequisites (e.g., must run wp_get_media first to get the id), and no named alternative.

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