set_download_config

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

Goes well past the annotations (which only flag non-read-only, idempotent, destructive): it discloses partial-update behavior, KB/s units with 0=unlimited, that rate fields are refused for non-admin accounts because DSM silently ignores them, and that default_destination is applied per user and blocks non-manager tasks until set. This is exactly the operational detail an agent needs before mutating global config.

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 core action and the optional/partial-update rule, then layers permission caveats. Four dense sentences with little waste, though the last sentence packs two distinct facts about default_destination that could be split.

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?

An output schema exists so return values need not be described, and the description covers the mutation's permission and per-user side effects thoroughly. It stops short of describing failure behavior for an invalid destination share or the scope of the change (global vs per-user) for the rate fields.

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 all parameter meaning; it does explain the rate semantics (KB/s, 0=unlimited) and the special behavior and permission model of default_destination. It does not individually distinguish bt_* from emule_* params or give a destination path format, so a small gap remains.

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 ('Set') and resource ('Download Station global configuration'), which cleanly separates it from the read-side sibling get_download_config. An agent can identify the operation and its scope without opening the 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 concrete when-to-use conditions: all parameters optional, partial-update semantics, and which fields require a manager/admin account versus any user. It does not explicitly name sibling tools, but the usage context is unambiguous.

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