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

Adds substantial context beyond the annotations: partial-update semantics ('Only the fields passed change'), an edit-permission requirement, the not-found error for non-media ids, the return shape {updated: true, id}, and the public-exposure warning. It does not address the fact that annotations flag destructiveHint=true and idempotentHint=false while the text implies a benign, set-style metadata edit, leaving a mild unresolved tension and no note on recoverability.

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-loaded with the core purpose, then behavior, then alternatives — good ordering with no filler. It is slightly dense at six sentences and the trailing connection-scope sentence could be trimmed, but each sentence carries information.

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 4-param mutation tool with no output schema, the description covers return value, error behavior, authorization, partial-update semantics, and data-exposure implications — everything needed to call it correctly and interpret the result.

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 100%, so the baseline is 3, but the description adds a real nugget absent from the schema: 'Alt text is stored as plain text.' It reinforces overwrite semantics ('Only the fields passed change'), which complements the per-parameter 'When omitted, it stays as it is' notes.

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 and resource scoped precisely: 'Change the title, caption or alt text of one file in the media library (attachment); the file itself stays as it is.' The added boundary (metadata changes only, file binary untouched) distinguishes it cleanly from wp_update_post (description/parent) and wp_delete_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?

Explicitly routes to alternatives: 'A new file is added with wp_upload_media; a file's description and parent are changed with wp_update_post.' Combined with the when-to-use statement, an agent can pick the right tool without reading sibling schemas.

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