qui_torrents

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether operations are read-only or mutating, what side effects occur (e.g., adding peers, renaming torrents), any authentication or permission requirements, rate limits, or error behaviors. While endpoint methods (GET, POST, PUT, DELETE) hint at mutations, this is implicit and not explicitly disclosed.

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 efficiently structured with a clear introductory sentence followed by a bulleted list of operations. It is front-loaded with the key usage pattern and then lists endpoints concisely. It avoids fluff, but the list is long; however, this is necessary for the tool's scope.

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 tool has 24 operations, a generic arguments object, no annotations, and an output schema (not described), the description is moderately complete. It explains the general argument structure and lists all operations with endpoints, but it lacks per-operation detail (required vs optional params, expected outputs, specific constraints) which is crucial for an agent to correctly invoke this tool. The output schema existence suggests detailed return types, but the description doesn't reference it.

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 has only two parameters: 'operation' (an enum) and 'arguments' (a generic object). Schema description coverage is 0%, meaning the description must compensate. The description explains the structure of 'arguments' (path variables, query params, body) but does not detail the required fields for each operation, leaving the agent to rely on the operation names and endpoint patterns. This is adequate but not comprehensive given the complexity of 24 operations.

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 clearly identifies the tool as a handler for all torrent-related operations on the 'qui' system, enumerating 24 distinct operations with their HTTP endpoints. It distinguishes this tool from sibling tools by focusing exclusively on torrent operations (as opposed to system, instances, RSS, etc.), and the verb+resource pattern is explicit for each operation.

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 provides a general usage framework—requiring 'operation' and 'arguments' with path variables, query params, and body—but it does not offer specific guidance on when to choose one operation over another or when to use an alternative sibling tool. It implies usage through the operation list but lacks explicit context or exclusions.

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