clean_unused_media

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

With no annotations, the description carries the full burden and does so: it discloses the ordering of side effects, that usage is re-verified at call time so stale reports are safe, that only Premiere project items are removed, that files go to the macOS Trash via Finder with Put Back available, that nothing is permanently deleted, and that Finder automation permission is needed the first time. This is exactly the reversibility and permission context an agent needs before a destructive call.

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 and dense with no filler, but it is one long run-on sentence with nested parentheticals, which makes the required 'confirm must be true' and permission notes harder to scan than they should be for a destructive tool.

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?

Covers preconditions, side-effect ordering, reversibility, and permissions thoroughly for a destructive 4-parameter tool. It stops short on return value and failure behavior (e.g. invalid or stale report path), which matters since there is no output schema.

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; the description goes further by framing the two optional booleans as distinguishable phases ('removes the unused items from the Premiere project (plus bins left empty by it)' and 'moves the unused files to the macOS Trash'), letting an agent infer that each phase can be toggled. It never names trashFiles or removeFromProject explicitly, so it does not fully close the loop.

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 multi-step action (save checkpoint, re-check usage, remove from project, move files to Trash) on a specific resource, and explicitly ties it to the review_unused_media report that precedes it, distinguishing it from that sibling. An agent can tell instantly that this is the destructive follow-up and not the analysis tool.

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 an explicit precondition ('after the user has read it'), an explicit gate ('confirm must be true'), and names the sibling that produces the required input. The alternative (review_unused_media, which only reports) is implicitly and effectively excluded by the phrasing.

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