wp_media_set_alt_text

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

No annotations are provided, so the description carries the full burden. It adds useful behavior details: alt_text is required, caption/description are optional, and empty alt_text is allowed to explicitly clear the value. However, it does not disclose auth requirements, whether unsupplied fields remain unchanged, or return/error behavior, leaving meaningful gaps for a mutation tool.

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 core action and fields. Every sentence adds value: the first defines scope, the second gives the SEO use case and the clearing edge case. No fluff or 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?

For a focused metadata update with no output schema and no annotations, the description sufficiently covers purpose, applicable fields, use case, and an important edge case. It lacks explicit success/return details and permission notes, but these are less critical for such a simple tool and do not prevent correct invocation.

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 0%, so the description must compensate. It identifies alt_text as required, caption/description as optional, and adds a key semantic that empty alt_text clears the value. It does not explicitly describe the 'id' parameter, but it is self-evident from the tool name and schema. This is adequate for the tool's simplicity.

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 uses a specific verb and resource: 'Update accessibility and descriptive metadata of a media item,' and enumerates the exact fields (alt_text required; caption and description optional). This clearly distinguishes it from the more general wp_media_update and other media siblings by focusing on SEO/accessibility metadata.

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?

It provides clear context for when to use the tool: 'Useful for bulk SEO improvements on existing media.' This implies it is for updating already-uploaded media, not for upload or general editing. It does not explicitly mention alternatives like wp_media_update or state when not to use it, so it misses the full 5.

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