delete_download

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

Annotations only declare destructiveHint=true; the description goes far beyond by disclosing irreversibility, that the source URL is lost, that finished-task files are kept while partial data is discarded, that force_complete is unreliable, and the exact DSM error (405) on finished tasks. This is unusually rich behavioral disclosure consistent with the annotations.

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-loads the action and the critical irreversibility warning, then breaks down per-parameter caveats in logical order. Slightly dense with the extended force_complete caveat, but nearly every sentence earns its place given the destructive nature.

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 the mutation's consequences, per-parameter behavior, and edge cases thoroughly; an output schema exists so return values need not be described. An agent has everything needed to invoke this destructive tool safely.

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?

With 0% schema description coverage, the description carries the full burden and succeeds: it explains task_ids is a list and details force_complete's intent, its known unreliability, and the finished-task rejection. Both parameters get meaning well beyond the bare schema types.

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 ('Remove one or more download tasks') that clearly distinguishes it from siblings like delete_files, list_downloads, and edit_download. An agent knows immediately this targets download tasks, not files on disk.

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 clear operational context: name the tasks and confirm with the user before deleting, and leave force_complete false for finished tasks. It does not explicitly name alternative siblings (e.g., delete_files for on-disk files) or state when-not-to-use, so it falls short of a full 5.

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