Remove download

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

With no annotations, the description carries the full burden. It usefully discloses a real behavioral consequence beyond the name: the result entry is purged, and force interrupts checksum verification. However, it does not state whether the download must be inactive, whether downloaded files on disk are deleted, or what error occurs on an active GID.

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 short sentences, front-loaded with the primary action and its side effect, with the parameter tip appended last. No filler or redundant restatement of the title.

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 and no annotations, so the description must cover behavior; it covers the primary effect and the force semantics but omits the on-disk file outcome and any removal preconditions. Adequate for a two-parameter mutation tool, but there are clear gaps for a destructive operation.

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 genuine semantic meaning over the schema for force: the schema only says 'use aria2.forceRemove instead of aria2.remove', while the description explains the practical effect (interrupting checksum verification). gid is left entirely to the schema, but the schema documents it adequately.

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 a download') plus an additional effect ('purge its result entry'), which distinguishes it from read-oriented siblings like aria2_status or aria2_list. It stops short of naming pause/unpause as the non-destructive alternatives, so no explicit sibling routing.

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?

There is no guidance on when to remove versus pause or unpause a download, nor any precondition (e.g., whether the download must be stopped first). The only usage hint — 'Set force to interrupt checksum verification' — is parameter-level, not tool-selection guidance.

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