Update a media item

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

Annotations already communicate that this is a mutating operation (readOnlyHint: false) and not idempotent or destructive. The description adds one useful behavioral detail—that the file is not re-uploaded—but it does not disclose side effects, whether fields are overwritten or merged, permission requirements, or what happens to existing values. It does not contradict the annotations.

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 a single concise sentence, front-loads the action and resource, and includes a relevant qualifier about not re-uploading. Every part earns its place, though the ambiguous 'or attachment' slightly reduces precision.

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 9-parameter mutation tool with no output schema, the description gives a reasonable high-level summary but omits any guidance on expected return values, error conditions, site_id selection behavior, or how 'attachment' updates relate to the 'post' parameter. The schema fills parameter details, but the description alone would not fully prepare an agent to invoke the tool correctly in edge cases.

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?

The input schema already documents all 9 parameters with 100% coverage, so the baseline is 3. The description adds general context by listing the updatable fields, but it introduces the vague term 'attachment' which does not directly map to any schema property (the closest is 'post', meaning re-attach to content ID). It does not meaningfully clarify parameter behavior beyond the schema.

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 identifies the verb ('update'), the resource ('a media item'), and the specific fields affected ('title, alt text, caption, description or attachment'). It also adds a distinguishing qualifier, 'without re-uploading the file', which helps separate it from creation workflows. However, it does not differentiate from the near-synonymous sibling 'edit_media', so it is not fully distinguishing.

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 'without re-uploading the file' implies this tool is for modifying an existing media item rather than creating/uploading new media, giving some usage context. But it does not explicitly state when to prefer update_media over edit_media, create_media, or delete_media, nor does it mention any exclusions or prerequisites. The usage guidance is mostly implied rather than stated.

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