review_unused_media

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

With zero annotations, the description carries the full burden and does much of it: it declares "without changing anything" (read-only preview), states that delivery/render folders and in-use files with proxies are never proposed, and discloses the side effect of writing a report to a fixed path. It stops short of stating permissions needed, scan cost on large jobs, or what the returned summary contains field-by-field.

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 trigger ("After delivery") and the core promise, then layered scope, exclusions, and hand-off in a logical order. The parenthetical folder lists and the ellipses are dense but each item removes a real ambiguity; the single-block paragraph is slightly hard to scan.

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?

No output schema exists, and the description compensates fully by saying it writes a report to a named directory and returns a summary for the user to check. Combined with explicit exclusion rules, defaults implied, and the clean_unused_media hand-off, an agent has 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 real semantics beyond it — keepSequences is explained as a job-definition switch where excluded sequences get listed for removal too, and the trash-scope of jobFolder is clarified by the always-kept delivery-folder rule. scanFolders and trashProxiesOfUsed are left to 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?

States a specific verb+resource with unusual precision: "find everything the job no longer uses, without changing anything," and enumerates the scope — project items not on any timeline, unused imported files on disk, their proxies, and never-used files in source folders. It never names the close siblings (get_unused_media, get_used_media_report), so the agent must infer the distinction from scope prose rather than an explicit contrast.

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?

"After delivery" gives a usable timing cue, and "Then clean_unused_media" explicitly hands off to the follow-up tool, which is genuine sequencing guidance. However there is no when-not guidance and no comparison against the several sibling tools that also report unused or used media, leaving the agent to guess which report tool to pick.

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