dl_cleanup_preview

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that computation is dependency-based and non-mutating, but says nothing about what happens when budget_sec or max_provider_calls are exhausted, whether results may be partial, or that external provider calls are involved (despite openWorldHint and a max_provider_calls parameter).

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though for a four-parameter tool with no schema documentation it is arguably too compact to carry the required information.

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?

With 0% schema description coverage, no output schema, two required array parameters, and tunable budget/provider-call caps, the description should explain inputs and the shape of the computed plan. It covers only the high-level intent, leaving the agent without enough to call the tool correctly or interpret partial results.

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% across all four parameters, so the description must compensate and largely fails. It only loosely gestures at preserve_roots (preserve set) and candidates (delete set) without naming either parameter, and completely ignores budget_sec and max_provider_calls, which materially shape the result.

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 ('Compute') and resource ('dependency-based preserve and delete sets'), and the qualifier 'without deleting anything' functionally separates it from the sibling dl_cleanup_apply. It stops short of naming the sibling explicitly, but the operation is unambiguous.

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?

Usage is implied rather than stated: the tool is only sensible as a dry run before applying cleanup changes, and the description hints at that with 'without deleting anything.' It never names dl_cleanup_apply as the follow-up action, gives no prerequisites, and does not state when a preview is unnecessary.

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