set_torrent

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

Annotations already mark this as readOnly=false and destructive=false; the description consistently says 'Change' and adds useful behavioral details—for example that location only records a path, labels are replaced, tracker_list is the whole list, and deprecated tracker_* fields are superseded by tracker_list. No contradiction 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?

The text is long only because there are 26 parameters to document. The opening one-liner states the purpose, and the Arg list is compact with no filler. Deprecation notes are inline where they matter.

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 complex 26-parameter mutation tool, the description covers every accepted argument, highlights cross-tool behavior via move_torrent_data, and an output schema exists so return-value documentation is not needed. The main remaining value-add, explicitly stating that unspecified settings are left unchanged, is minor because the schema shows only ids as required.

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 carries full responsibility for 26 parameters. It delivers: every parameter gets a unit, allowed mode, or format (e.g., '-1 low, 0 normal, 1 high', 'kB/s', 'URLs separated by newlines, tiers by blank line'), which the bare schema completely lacks.

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?

The first sentence says 'Change any per-torrent setting,' which is a specific verb, resource, and scope. It clearly separates this tool from siblings like set_session and set_bandwidth_group (session- or group-level mutations) and from action-oriented siblings like start_torrents or move_torrent_data.

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?

The description gives explicit routing for one common overlap: changing location only records the path and instructs to 'use move_torrent_data to move the files.' It does not systematically enumerate when to prefer start/stop/remove/queue siblings, but the scope 'per-torrent setting' plus the sibling names make the main boundary clear.

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