create_download

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

Annotations only say it is a non-read-only, non-destructive mutation, so the description carries real weight here: it discloses that credentials apply to URLs but not torrent files, that task IDs are returned only when DSM provides them and are withheld for credentialed URLs, and that long magnet links/URI lists are supported. It stops short of describing failure modes or partial-batch behavior when multiple URIs are passed.

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?

One dense paragraph, front-loaded with the action and then the mode selection; nearly every clause carries operational information. The nested non-manager/default-destination parenthetical is slightly heavy but is genuinely load-bearing for correct invocation.

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?

For a 5-param mutation tool with an output schema present, everything an agent needs is here: mutually exclusive input modes, destination semantics, credential applicability, and the return-value caveat. Return format itself is covered by the output schema, so the description is not obliged to explain it further.

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 baseline expectations are low, but the description compensates well: it defines `uri` as a comma-separated HTTP/FTP/magnet list, `torrent_file_path` as a local path, `destination` as a share-relative path with an omit-for-default rule, and explains when `username`/`password` are valid. Only `password` lacks any standalone explanation.

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 ('Create one or more download tasks') and immediately scopes it with the two mutually exclusive input modes (URI list vs .torrent/.nzb path). An agent can tell this apart from edit_download, pause_download, and the rest of the download family without opening a 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?

Gives clear run-time conditions: use `uri` for HTTP/FTP/magnet links, `torrent_file_path` for local .torrent/.nzb, and call `set_download_config` first if a non-manager has no default destination. It does not, however, distinguish this tool from the sibling `download_file`, which an agent could plausibly confuse with creating a download task.

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