cleanuparr_arr_download_clients

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

With no annotations, the description carries the full burden. It discloses important behavioral traits for some operations: purge_strikes is 'irreversible', update_general_config warns about resetting unspecified fields in a read-modify-write, and secret placeholders for apiKey/password are noted. However, many operations (e.g., create, delete, test) lack side-effect or permission details, so the disclosure is partial.

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 description is long but appropriately so for 15 operations. It is front-loaded with the usage pattern and then organized as a clean bulleted list of operations, each on a single line. There is no fluff or redundancy; every line adds operational detail. The structure is easily scannable for an agent needing to find a specific operation.

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?

Given the complexity (15 operations) and lack of annotations, the description provides substantial context: function signatures, DTO fields, and behavioral warnings. The presence of an output schema reduces the need to describe return values. Some operations are under-descripted (e.g., cleanuparr_get_arr_config has no explanatory text), but the names and signatures largely suffice. Overall, it is fairly complete for a multi-operation dispatch tool.

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?

The input schema only provides `operation` and a free-form `arguments` object with no internal structure. The description compensates fully by giving a function signature for each operation (e.g., cleanuparr_create_arr_instance(arr_type, instance)) and, for many, listing DTO fields (e.g., 'enabled, name, url, apiKey'). This directly tells the agent how to construct the arguments dict for any operation, adding critical meaning beyond the schema.

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 description states it covers 'cleanuparr arr download clients operations' and then enumerates 15 distinct operations with clear verbs (create, delete, list, test, update, purge) and resources (arr instances, download clients). This clearly communicates the tool's scope and differentiates it from sibling tools that cover other Cleanuparr domains, though it is a collection rather than a single specific verb+resource.

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 explains how to invoke the tool ('Pass `operation` and an `arguments` dict') but does not explicitly state when to use this tool versus alternatives. It lacks any 'when to use' guidance, exclusions, or references to sibling tools, leaving the selection decision to the agent's inference from the operation list.

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