prune_storage

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description adds real value on top by stating the default is a non-destructive dry run, precisely what would be removed, and what the response contains (paths, jobs, byte totals). The description is consistent with the annotations: it is a destructive tool that defaults to a safe preview.

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?

Two sentences, front-loaded with the report-vs-delete distinction and the selection criteria, with no redundant restatement of the name, schema defaults, or annotation flags.

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?

The tool is destructive with only two optional parameters and an output schema, so the description's job is criteria and safety profile, both of which are covered. An agent can decide whether to call it and predict the effect without further reading.

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 0%, so the description must carry the parameter meaning, and it does: `older_than_days` is defined as the age since job completion and since upload last-touch, and `dry_run` is characterized as report-only versus actually deleting. It does not restate defaults or unit bounds (0-36500) that the schema already encodes.

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 names a specific verb pair and resource scope: report-or-delete of old terminal jobs, unused uploads, and orphaned transfer files. The age/terminal-state criteria make it clearly a bulk cleanup tool, distinguishable from single-item siblings like delete_job and cancel_job without opening either schema.

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?

It gives clear selection conditions for what qualifies (jobs finished more than `older_than_days` ago; uploads untouched that long with no queued/running job referencing them) and states dry run is the default. It does not explicitly say when to prefer this over delete_job or cancel_job for individual items, but the context is unambiguous.

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