Swap Media

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

Goes well beyond the annotations by disclosing that a background job is queued, that confirm=true is mandatory, the exact permission scopes required, expiring-token authorization semantics, and that the operation 'may share access, notify people or incur provider charges.' This is rich mutation context layered on top of destructiveHint/openWorldHint.

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 core operation and side-effect warning are front-loaded, and the auth block is clearly delineated in its own section. The permission prose is somewhat verbose and repetitive for a tool that mostly needs the when-to-use framing, but every part is relevant.

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 6-parameter, nested-object mutation with no output schema, the description covers the queued-job behavior, auth requirements, confirm gate, and side effects. It omits what happens on failure and whether the background job's progress can be tracked (e.g., via get_job_status), leaving a small gap.

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 schema already documents media_hashed_id, replacement_media_id, confirm, account, payload, and payload_file. The description adds little parameter-level detail beyond restating the confirm requirement and the same-media-type constraint, which the schema already states. Baseline 3 applies.

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 (swap one media with another), plus the key scoping fact that the original media's hashed ID and URLs are preserved. This distinguishes it clearly from siblings like copy_media, update_media, and upload_media, which do not retain the original identity.

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?

Gives concrete preconditions (confirm=true, required permission scopes, delegated/expiring token behavior) and describes the outcome (background replacement preserving identity). It does not explicitly contrast when to use this versus copy_media or upload_media, so the agent must infer the 'replace in place' scenario.

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