Transmission MCP server

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

The description goes beyond the annotations by specifying useful behaviors: torrent_file is 'read and encoded for you', download_dir 'Defaults to the session setting', and paused means 'Add without starting.' This gives the agent practical expectations about side effects and defaults beyond the idempotentHint annotation.

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?

A one-sentence purpose summary is front-loaded, followed by a compact and clearly formatted Args list. Every line adds needed information, especially given the lack of schema-level parameter descriptions.

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 high parameter count, an output schema, and annotations already available, the description covers all necessary input semantics and default behaviors. Nothing essential for calling the tool correctly is missing.

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 the full burden of explaining parameters. It does so thoroughly, covering every one of the 15 parameters with meaningful semantics like 'cookies: Cookies to send when fetching a .torrent URL' and 'bandwidth_priority: -1 low, 0 normal, 1 high.'

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 states a specific action and resource: 'Add a torrent from a magnet link, a URL, a local file or raw metainfo.' This clearly distinguishes it from sibling tools like set_torrent, remove_torrent, or start_torrents, so an agent can identify its purpose immediately.

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 makes the use case clear: adding a new torrent through several input methods. It does not explicitly name alternative tools or exclusion conditions, but the context is unambiguous and no misleading guidance is present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the optional group filtering behavior, but does not disclose response, error, or edge-case behavior. No contradiction with 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 description is extremely concise and front-loaded with the core purpose. The optional parameter note is brief and useful, with no filler or unnecessary repetition.

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 rich annotations, an output schema, and a single optional parameter, the description is mostly complete for invoking the tool correctly. It could be slightly stronger by explicitly contrasting with set_bandwidth_group or noting error behavior, but this is not a major gap.

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 schema has no parameter descriptions, but the description clarifies that 'group' accepts one group name and that omitting it returns all groups. This adds meaningful semantic context beyond the raw 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 uses a specific verb 'Get' with a clear resource ('bandwidth groups') and specifies the returned content ('their speed limits'). It is clearly distinguishable from sibling tools like set_bandwidth_group, which suggests a write 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?

No guidance is given about when to use this tool versus alternatives such as set_bandwidth_group. The only usage instruction is parameter-level ('Omit for every group'), not tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about the daemon-side path, but does not disclose any additional behavioral traits such as error conditions or filesystem resolution rules.

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 extremely efficient: one clear opening sentence plus a focused parameter explanation. No wasted words, and the most important scoping detail is front-loaded.

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 single-parameter, read-only, idempotent tool with an output schema, this description is complete. It tells the agent what the tool does, where the path must reside, and the annotations plus output schema cover safety and return shape.

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 coverage is 0%, so the description carries full responsibility for parameter meaning. It does this well: 'path' is explained as a directory path on the machine running Transmission, not on this one, which adds critical semantic information the schema does not provide.

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 uses a specific verb-resource pair: 'Get free space in a directory.' It also clarifies the directory is one 'the daemon can see,' which meaningfully distinguishes the operation from any local filesystem query and aligns with the tool name.

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 clearly states the relevant context: the path must be on the machine running Transmission, not the client machine. None of the sibling tools relate to disk-space queries, so this tool's usage is effectively unambiguous even though no explicit alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns both session settings and the daemon's version, which provides useful scope beyond the annotations. No contradictions are present.

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 a single, front-loaded sentence with no redundancy. Every word adds meaning, and it is appropriately concise for a tool with no parameters and a straightforward purpose.

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 zero-parameter read-only tool with an output schema present, the description is complete. It states what the tool returns without needing to explain return format (handled by schema) and the annotations cover safety behavior. Nothing essential is missing for an agent to call this correctly.

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?

There are zero parameters, so schema coverage is trivially 100%. Per guidelines, a baseline of 4 is appropriate when there are no parameters, and the description does not need to elaborate on parameter meaning. It correctly focuses on the return value instead.

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 states the verb 'Get' and the resource 'every session setting and the daemon's version', which is specific and distinct from sibling tools that operate on torrents, blocklists, or bandwidth groups. It distinguishes this as a session-level read tool without ambiguity.

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 implies usage for retrieving session configuration and version info, and the contrast with set_session and other mutating siblings is apparent. However, it does not explicitly mention when not to use it or compare with the close sibling get_session_stats, which could add clarity. The context is clear enough for a simple getter.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the specific data points returned (transfer totals, active torrent counts, speeds), which is useful behavioral context beyond the annotations. However, it doesn't disclose details like whether the stats are cumulative since session start, whether speeds are averaged or instantaneous, or any rate-limiting behavior. With annotations covering safety, a 3 is appropriate.

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?

A single, compact sentence that front-loads the verb and resource, then lists the three key data categories. Every word earns its place; there is no fluff or repetition of schema/annotation information.

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 zero-parameter, read-only tool with a rich output schema, the description is nearly complete. It tells the agent what data it will receive (transfer totals, active torrent counts, speeds). The only minor gap is not specifying whether these are session-wide aggregates or something else, but the tool name and sibling context (get_session) make that clear. The output schema likely details the return structure, so the description doesn't need to.

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 tool has zero parameters, so the schema provides no parameter documentation. The description doesn't need to explain parameters, but it does clarify what the tool returns, which is the only semantic content an agent needs. With 0 params, the baseline is 4, and the description meets that baseline by clearly stating the output scope.

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 states the tool's function: retrieving transfer totals, active torrent counts, and current speeds. It uses a specific verb ('Get') and names the resource ('session stats'), which distinguishes it from sibling tools like get_session (which likely returns configuration settings) and list_torrents (which returns per-torrent data). However, it doesn't explicitly name a sibling to differentiate from, so it doesn't earn a 5.

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 implies usage context: it's for getting aggregate session-level statistics rather than per-torrent or configuration data. However, it doesn't explicitly state when to use this tool versus alternatives like get_session or list_torrents, nor does it mention any exclusions or prerequisites. The context is clear enough for an agent to infer, but not explicitly guided.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail about the breadth of the response (files, peers, trackers), but does not disclose potential error cases or behavior for invalid IDs. With annotations lowering the bar, this is adequate.

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 short and front-loaded with the core purpose, followed by a clear parameter explanation. No wasted words; every sentence contributes value.

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 simple single-parameter read operation with annotations covering safety and an output schema available, the description provides enough context for an agent to call the tool correctly. The parameter semantics are specified, and the output shape is handled by the schema.

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 coverage is 0%, but the description compensates by explaining that the id is 'a torrent id or hash string,' which adds domain meaning beyond the raw anyOf integer/string schema. It clarifies the identifier's role without being overly verbose.

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 a specific verb ('Get') and resource ('one torrent'), and clarifies the scope with 'every field, including files, peers and trackers.' This clearly distinguishes it from siblings like list_torrents (multiple torrents) and list_torrent_fields (field names only).

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 clear context: use this when you need the full data for a single torrent. It does not explicitly name alternatives or state when not to use it, but the scope is evident from the wording.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds minimal behavioral context beyond that, but it does clarify the tool's relationship to list_torrents. There is no contradiction, and the description does not add significant behavioral traits, so a 3 is appropriate.

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 a single, concise sentence that is front-loaded with the key information. It has no fluff and is perfectly sized; every word carries meaning. It is an excellent example of brevity combined with clarity.

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 zero-parameter tool with a simple purpose, the description is complete. It tells the agent exactly what the tool returns (list of fields for list_torrents) and the annotations cover the safety profile. There is no missing information that an agent would need to use it correctly, especially given the output schema exists.

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 tool has zero parameters, and the schema is empty with 100% coverage (trivially). The description correctly indicates that no parameters are needed and that the output is a list of fields for list_torrents. With 0 parameters, the baseline is 4, and the description fulfills this by helping the agent understand the output's purpose.

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 states that the tool lists all fields that list_torrents can request, using a specific verb and resource. It is unambiguous and tells the agent exactly what to expect: a list of available fields. This distinguishes it from siblings like list_torrents, which it supports.

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 implies that this tool is used to discover the valid fields for list_torrents, which provides clear context for when to use it. It does not explicitly mention when not to use it or name alternatives, but the purpose is obvious, so the score is 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the base safety profile is covered. The description adds valuable behavioral nuance, especially the 'recently-active' semantics tied to the last such call, which is not inferable from annotations or schema.

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 compact, front-loaded with the core purpose, and uses a clear Args structure. Each sentence adds useful information with no filler or repetition.

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?

With two optional parameters, rich annotations, and an output schema present, the description covers all needed operational details: how to select torrents, how to control response size, and the special recently-active behavior. Nothing essential is missing.

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%, but the description fully compensates by explaining both parameters in plain language: what ids accept, the special 'recently-active' literal, the meaning of omission, and the purpose of fields. This is exactly the semantic information the schema 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 opening sentence, 'List torrents with their state, progress and speeds,' uses a specific verb and resource and clearly indicates a plural listing operation. This distinguishes it from sibling tools like get_torrent and list_torrent_fields without ambiguity.

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 clear context: omit ids for all torrents, supply specific ids or hashes for a subset, and use 'recently-active' for changed items. It also advises limiting fields for large libraries. It does not explicitly name alternatives or exclusions, but the usage context is clear enough.

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

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

Annotations already indicate idempotence and non-read-only behavior. The description adds useful behavioral detail by distinguishing between physically moving files and only updating the recorded path. It does not cover edge cases like destination conflicts or permissions, but that is acceptable given the annotation coverage.

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 compact and well-structured: a two-sentence overview followed by a focused Args list. Every sentence adds value, and there is no filler or repetition of schema fields.

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?

With annotations, an output schema, and a parameter-by-parameter description, the essential information for invoking the tool correctly is present. Minor gaps like destination-directory creation or cross-filesystem behavior are not mentioned, but they are not required for basic correct use.

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 schema has 0% description coverage, but the description compensates fully by explaining all three parameters: ids as torrent IDs or hash strings, location as the target directory, and move with its true/false semantics. This is exactly the kind of parameter-level clarity agents need.

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 action ('Move') and the resource ('a torrent's data'), and it explains the dual behavior: physically moving files or updating the recorded path. It does not explicitly differentiate from sibling tools like rename_torrent_path, so it is clear but not fully sibling-aware.

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 practical guidance for both modes: move=True moves existing files, while move=False is for data the user already moved. It does not explicitly mention when to prefer this tool over alternatives, but the mode-level usage context is strong.

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

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

Annotations already cover idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false), and the description does not contradict them. However, the description adds no behavioral detail beyond the operation itself—such as order preservation, behavior when torrents are already at the bottom, or side effects on other queued items. This is adequate given the annotation coverage, but not rich.

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 compact and front-loaded with the core action, followed by a focused parameter explanation. There is no redundant or filler text; every sentence contributes usable information.

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 single-parameter, non-destructive, idempotent queue operation with an output schema, the description is largely complete. The main gap is the lack of usage guidance relative to sibling queue-move tools, but the operational essentials are present.

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 schema only defines 'ids' as a loosely typed anyOf, with no property description. The description compensates by stating that ids are 'Torrent ids or hash strings', which meaningfully helps an agent construct valid input even though it does not elaborate on array-vs-scalar semantics.

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 a specific action ('Move torrents') and the exact destination ('back of the queue'), which cleanly distinguishes this from sibling queue-moving tools (queue_move_top, queue_move_up, queue_move_down). The verb and resource are explicit and unambiguous.

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?

There is no guidance on when to use this tool versus its queue-related siblings. While 'move to the back' implies a use case, the description does not explicitly state when to prefer queue_move_bottom over queue_move_top, queue_move_up, or queue_move_down, nor are any exclusions or alternative conditions provided.

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

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

The description states 'Move torrents one place down,' implying each invocation changes the queue position. This contradicts the annotation idempotentHint: true, which suggests repeated calls have no additional effect. No other behavioral context (e.g., what happens at the bottom) is provided, and the description carries the full burden since annotations are limited. This is an annotation contradiction.

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 extremely concise: two sentences, with the action front-loaded and the parameter explanation given in a compact 'Args' section. No wasted words.

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 simple tool with one parameter and an output schema present, the description covers the essential information needed to invoke it: what it does and what the parameter means. It lacks edge-case details (e.g., behavior at queue bounds), but these are rarely critical for a single-step move. Overall, it is complete enough for most agent use cases.

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%, but the description explicitly explains that 'ids' are 'Torrent ids or hash strings.' This adds meaning beyond the bare schema definition (array/string/integer) and is essential for correct usage. It does not, however, clarify format or constraints (e.g., whether duplicates are allowed), but it is a solid compensation for the lack of schema metadata.

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 states the action ('Move torrents') and scope ('one place down the queue'), which distinguishes it from sibling tools like queue_move_top, queue_move_up, and queue_move_bottom. No ambiguity.

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?

There is no explicit guidance on when to use this tool vs alternatives. The name and description imply a single step downward, but the description does not mention that jumping to top/bottom requires other tools, nor does it address how to perform multiple moves. This leaves the agent to infer usage from the tool name alone.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive operation. The description adds context by framing the action as a queue reordering, but it discloses little beyond that. There is 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 description is very short, front-loaded, and contains no filler. The one-sentence action plus a single Args line is appropriately sized for such a simple tool, though it could have used one sentence to mention the queue_move_up sibling.

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 simple one-parameter tool with an output schema and annotations, the description is nearly complete for making a correct call. The main gap is not explaining how this tool differs from queue_move_up, but that affects tool selection rather than invocation correctness.

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 schema only names the parameter 'Ids' with no description coverage, so the description's clarification that ids can be torrent IDs or hash strings is valuable. It meaningfully explains what kind of values to pass, even without examples or multi-value syntax.

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 says the tool moves torrents to the front of the queue, giving a specific verb, resource, and destination. It is understandable on its own, though it does not explicitly distinguish itself from sibling tools like queue_move_up or queue_move_bottom.

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 no guidance on when to use this tool versus the closely related queue_move_up, queue_move_down, or queue_move_bottom tools. The intended action is implied by 'front of the queue,' but no exclusions or alternative routing are provided.

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

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

Annotation Contradiction: idempotentHint=true conflicts with the description's 'one place up' semantics, since calling it twice moves a torrent from position n to n-2, not the same as one call. No additional behavior (e.g., effect when already at top, or ordering of multiple ids) is 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?

Two concise, front-loaded sentences; the action is stated first and the parameter note is separated into a simple Args block. No filler or redundant schema repetition.

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?

With an output schema present and only one required parameter, the mechanics are mostly covered. However, the idempotency contradiction and lack of edge-case guidance make it incomplete for safe repeated use.

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 coverage is 0%, but the description compensates by stating 'ids: Torrent ids or hash strings,' clarifying the accepted parameter beyond the generic anyOf array/string/integer. It does not detail how multiple ids are ordered, but for a one-param tool this is adequate.

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 precise verb and resource: 'Move torrents one place up the queue.' The qualifier 'one place up' distinguishes it from queue_move_top, queue_move_down, and queue_move_bottom without needing those schemas.

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?

No explicit when-to-use or alternative routing is given. The operation is clear enough to infer it is for one-step queue promotion, but it does not mention queue_move_top for 'send to top' or how to choose among the four queue commands.

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

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

Annotations indicate idempotentHint=true and readOnlyHint=false, but destructiveHint=false. The description does not contradict these. The description adds that the action contacts trackers, implying network requests, but does not mention that it does not stop or alter torrents. Given annotations cover idempotency and non-destructiveness, the description adds moderate context by stating the purpose.

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 extremely concise, with one sentence plus a two-line parameter explanation. The main purpose is front-loaded. There is no filler; each part earns its place. The only minor issue is that 'now' might be redundant, but it doesn't detract much.

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 is simple (one optional parameter) and has an output schema (not detailed here), the description is adequate. It explains what the tool does and how to specify targets. However, it lacks context about the output (e.g., whether it returns results or just confirms) and potential limitations (e.g., only works on active torrents). Since no annotations indicate additional constraints, a score of 3 is fair.

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 define the 'ids' parameter. It states 'Torrent ids or hash strings. Omit for every torrent.' This is clear and useful, explaining the accepted types and default behavior. However, it does not elaborate on the format of IDs (e.g., integer IDs vs. hashes) beyond that. Baseline is 3 due to low coverage, and the description meets that by providing essential semantics.

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 uses a specific verb ('ask the trackers for more peers now') and clearly identifies the resource (torrents). It distinguishes this action from sibling tools like stop_torrents or verify_torrents by focusing on peer re-announcement. However, the phrase 'now' could be seen as implying immediacy, which is a bit vague but still clear enough.

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 states that omitting 'ids' applies to every torrent, which serves as basic guidance on when to use it without specifying certain torrents. It does not explicitly say when NOT to use it or mention any prerequisites (e.g., torrents must be active). It implies usage: for re-announcing torrents to trackers, but does not compare with similar actions like start_torrents_now.

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

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

The annotations already establish destructiveHint, and the description adds concrete behavioral context: delete_local_data erases files from disk, cannot be undone, and ids never default to all torrents. This clarifies the conditional destructiveness rather than merely restating the annotation.

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 compact and front-loaded with the core action, followed by two focused parameter notes. Every line carries necessary information with no filler.

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 two-parameter destructive tool with an output schema and annotations, the description covers the essential behavior, parameter semantics, and irreversible file-deletion risk. It does not spell out side effects on seeding state, but that is minor given the combination of schema, annotations, and sibling context.

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%, and the description fully compensates by documenting both parameters: ids accepts torrent ids or hash strings and is required, while delete_local_data controls file deletion and is irreversible. This is meaningful semantic content well beyond the raw 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 opening line uses a specific verb and resource ('Remove torrents') and immediately qualifies the optional destructive scope ('optionally deleting their downloaded files'). This clearly differentiates the tool from siblings like start_torrents/stop_torrents and 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?

Usage is only implied by the action ('Remove torrents...'); the description does not explicitly say when to use remove_torrent instead of stop_torrents or other alternatives. It does provide a pertinent safety usage note ('Required -- this tool never defaults to every torrent'), but no when-not or alternative routing.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false, so the description does not need to restate those. It adds useful constraints about scope (one torrent at a time, current path relative to root, rename applies only to one path segment). It does not detail edge behavior such as failure if the target name already exists, but the annotation coverage lowers the bar.

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 a short, front-loaded purpose statement followed by a clean Args block. Each line contributes meaningful information, and it is appropriately sized for a simple three-parameter tool. Minor redundancy exists (renaming is one torrent at a time), but nothing is wasted.

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 simple mutation tool with an output schema and all annotations supplied, the description covers all required parameters and the key operational constraints (one torrent at a time, relative path, single segment). It is complete enough for correct invocation; only broader edge-case behavior or comparative guidance is left unaddressed.

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 is the only source of parameter meaning. The Args block provides precise, non-obvious semantics for all three parameters: id is a single torrent id or hash, path is relative to the torrent's own root, and name applies to only one path segment. This fully compensates for the schema's lack of descriptions.

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 line, 'Rename a file or directory inside one torrent,' states a specific verb, resource, and scope. It is clearly distinct from sibling tools like move_torrent_data, but it does not explicitly name any alternative or draw a contrast, so it misses the higher bar for explicit sibling differentiation.

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 implies when to use the tool (when you want to rename a file/directory in a torrent) and sets constraints (one torrent at a time, path relative to root). However, it does not explicitly say when to prefer this over alternatives such as move_torrent_data or set_torrent, so usage guidance is implied rather than stated.

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

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

Annotations already establish idempotency and non-destructiveness, and the description adds the key behavioral nuance that an unknown name is created rather than rejected. It also explains that the tool can both create and modify groups, going slightly beyond the schema and 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 one-line purpose is front-loaded, followed by a compact, uniform list of parameter descriptions. Every sentence earns its place; there is no filler or repetition of schema type information.

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 six-parameter upsert tool with an output schema, the description covers purpose and all parameter meanings. It leaves minor gaps such as the effect on existing groups when optional fields are omitted, but overall it is sufficient for correct invocation.

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%, but the Args section documents all six parameters with meaningful descriptions, including units (kB/s), enabling semantics, and the meaning of honors_session_limits. This fully compensates for the bare 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 opens with a specific verb-resource pair, 'Create or change a bandwidth group,' which clearly identifies the action and target. This differentiates it from read-only siblings like get_bandwidth_groups and from other setter tools that target sessions or torrents.

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?

'Create or change' provides clear context for when to invoke the tool, and the note that a name that does not exist yet is created clarifies the create-vs-update behavior. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to route correctly.

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

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

Annotations already convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation profile is covered. The description adds meaningful behavioral context: setting names must match what get_session reports, and valid names depend on the Transmission version. This goes beyond the structured 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 description is compact and front-loaded with the core action. The parameter explanation is concise, example-driven, and directly useful, with no filler or redundant restatement of the schema.

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 settings-mutation tool with an open-ended object parameter, the description provides the essential discovery mechanism: consult get_session. Output schema and annotations cover return and safety expectations. A minor gap is not stating what happens with invalid or partially specified settings, but the guidance to read get_session first largely mitigates that.

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 coverage is 0%, so the description carries the full burden for the settings parameter. It explains that settings is a mapping from get_session-reported names to new values, provides two concrete examples, and instructs the agent to read get_session first. This is exactly the semantic guidance needed for this open-world object parameter.

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 begins with a precise verb and resource: 'Change session settings.' It clearly distinguishes this tool from siblings like set_torrent and set_bandwidth_group by targeting the session-level settings object, and the examples reinforce the exact scope.

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 clear, actionable usage guidance: read get_session first, use setting names exactly as get_session reports them, and be aware that names differ between Transmission 3 and 4. It does not explicitly discuss alternatives or when not to use this tool, but the session-vs-torrent distinction is clear enough.

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

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.

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

Annotations already provide idempotentHint=true and destructiveHint=true, but the description adds meaningful behavioral context: 'Every torrent stops and the daemon exits. Nothing here can start it again.' This clearly communicates the full destructive scope and irreversibility within the toolset.

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 two short sentences with no filler. The first sentence states the action directly, and the second sentence adds the key consequences and caution. Every sentence earns its place.

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?

With zero parameters, an existing output schema, and annotations covering idempotency and destructiveness, the description supplies the missing behavioral context: all torrents stop, the daemon exits, and nothing in this toolset can restart it. The agent has everything needed to decide whether to call this 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 tool has zero parameters and the input schema is empty, so the baseline of 4 applies. The description correctly focuses on behavior rather than parameter details, and no parameter explanation is needed.

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 uses a specific verb and resource: 'Shut the Transmission daemon down.' It also clarifies the effect by stating 'the daemon exits,' which distinguishes it from sibling tools like stop_torrents that only stop torrents without shutting down the daemon.

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 intended use is implied by the action and consequence: this is the tool for completely ending the Transmission daemon. However, it never explicitly states when to use this over alternatives, nor does it mention stop_torrents or other less destructive options, so the usage guidance is only implied.

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

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

Annotations already mark the tool idempotent and non-destructive; the description adds the queue-respecting behavior and the all-torrents default when ids are omitted. It does not go into error or side-effect detail, but the annotation coverage lowers the burden.

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?

Two short sentences plus a one-line Args entry; no filler, and the key distinction is front-loaded. It is appropriately sized for a one-parameter tool.

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 a simple optional single parameter and an output schema, the description supplies the needed call semantics. The only notable omission is an explicit pointer to the now-start sibling, which keeps it slightly below excellent.

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 coverage is 0%, so the description bears the full load; it explains that ids are torrent ids or hash strings and that omission targets every torrent. This resolves the schema's bare anyOf and default null.

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 opens with the specific action 'Start torrents' and the qualifier 'respecting the download queue,' which differentiates it from sibling start_torrents_now. The resource and behavior are immediately clear.

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?

It states the only decision point for ids ('Omit to start every torrent') and implicitly frames this as the queue-respecting variant. It does not explicitly name start_torrents_now as the alternative, so exclusion guidance is only inferred.

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

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

Annotations already disclose idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false). The description adds the queue-jumping behavior, which is a meaningful behavioral trait beyond annotations. However, it does not explain side effects (e.g., whether queue order is permanently altered) or the response format. Given annotations cover safety and idempotency, this is adequate but not rich.

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 two sentences: a clear headline action followed by a structured Args section. It is front-loaded with the purpose and contains no fluff. Every sentence contributes value.

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 simple tool with one optional parameter, the description covers the main behavior and the parameter usage. The output schema exists but is not described, which is acceptable. It could mention error cases or consequences of queue jumping, but given the tool's simplicity and the annotations covering safety, it is largely complete.

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 compensate. It does: 'ids: Torrent ids or hash strings. Omit for every torrent.' This clarifies the parameter type and meaning more than the raw schema (which only lists anyOf with no titles or descriptions). However, it does not specify exact formats (e.g., whether IDs are integers or what hash format) or behavior when both torrent IDs and hashes are mixed. It adds baseline meaning but not depth.

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 a clear action: 'Start torrents immediately, jumping the download queue.' This specifies the verb (start), the resource (torrents), and a distinguishing behavior (queue jumping) that separates it from the sibling start_torrents. An agent can immediately infer what makes this tool unique.

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 no guidance on when to use this tool versus the sibling start_torrents or other queue-related tools like queue_move_top. It does not mention prerequisites, situations where it should be preferred, or when to avoid it. The only implicit hint is 'jumping the download queue,' but no explicit direction is given.

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

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

Annotations already declare the tool is not read-only, is idempotent, and is not destructive, so the description does not need to restate those. It usefully adds that omitting ids stops every torrent, which is a globally-scoped behavior an agent should know. It does not describe side effects such as whether torrents remain available for restart, but this is adequately covered by the idempotency annotation.

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 extremely concise, with the core action front-loaded in the first line and a compact argument explanation. Every sentence earns its place, with no redundant or filler content.

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 single-parameter tool with an output schema and informative annotations, the description covers the essential behavior and the important all-torrent fallback. It is slightly limited by not comparing itself to the closely related start_torrents or remove_torrent siblings, but the name and action make the intended context clear enough.

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 no descriptions (0% coverage), so the description carries the full burden for explaining the parameter. It clearly states that ids can be torrent ids or hash strings and that omitting the parameter stops all torrents, fully compensating for the schema gap.

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 a specific verb, 'Stop', and resource, 'torrents', making the tool's purpose unambiguous. It also clarifies the scope of the operation ('every torrent' when ids are omitted), which distinguishes it from sibling tools like start_torrents or remove_torrent.

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 tool's purpose itself implies when to use it, and the description gives a concrete usage condition: omit ids to stop every torrent. However, it does not explicitly mention alternatives or when-not-to-use scenarios, such as preferring remove_torrent for deletion or start_torrents for resuming.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, lowering the bar for additional disclosure. The description adds meaningful context that the check is performed from outside, clarifying the network semantics. It does not detail latency or exact reachability criteria, but for a zero-parameter diagnostic this is adequate.

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 a single sentence with no filler, front-loading the verb and object. Every word contributes to understanding the tool's purpose.

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 zero parameters, a strong annotations set indicating a safe read-only operation, and an output schema, the one-sentence description is sufficient for an agent to invoke the tool correctly and interpret its result. Nothing critical is missing.

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 no properties, so there are no parameter semantics to clarify. The description correctly focuses on the operation rather than attempting to document nonexistent parameters, matching the baseline for zero-parameter tools.

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 uses a specific verb ('check') and a specific resource ('peer port') and clearly states the condition being tested ('reachable from outside'). This is easily distinguishable from the sibling torrent-management tools, none of which perform connectivity checks.

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 sentence conveys the clear intended use case: verify whether the peer port is externally reachable. It does not explicitly name alternatives or exclusions, but no sibling tool competes with this functionality, so the context is sufficiently clear.

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

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

Annotations already state idempotency, non-read-only, and non-destructive behavior. The description adds that this is a network download and that the caller receives a size, but it does not disclose whether the existing blocklist is replaced atomically, whether active torrents are affected, or what happens on failure. No contradiction with 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?

A single efficient sentence with the verb and resource front-loaded. It avoids filler and states the observable outcome in the same breath.

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 0-parameter tool with an output schema and safety annotations, the description adequately covers the core action and result. It could say more about what 'update' means for active state, but nothing essential is missing for invoking it correctly.

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 tool has zero parameters and the schema is complete, so there is no parameter-level burden on the description. The baseline of 4 is appropriate.

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?

Clearly states a specific action ('Download a fresh copy of the blocklist') on a unique resource, with a concrete result ('report its size'). It does not explicitly contrast with sibling tools, but none of the listed siblings concern the blocklist, so the resource itself differentiates it.

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?

Provides no explicit guidance on when to use this tool, what conditions require it, or any alternatives. The usage is only implied by the tool name and the description's action, which is a gap for an agent deciding among sibling tools.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the description correctly does not contradict them. It adds genuinely useful behavioral context beyond annotations by warning that 'Verification restarts the torrent's progress from zero while it runs,' which is a non-obvious side effect an agent should know before invoking.

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 minimal and well-structured: purpose first, behavioral warning second, parameter documentation last. Every sentence is informative and none of the content is redundant with the schema or annotations.

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 that this is a single-parameter tool with an output schema present, the description covers all essential aspects: what the operation does, its notable side effect, and the parameter semantics. No critical information is missing for correct selection or invocation.

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 coverage is 0%, so the description must carry the full semantic burden for the ids parameter. It does so effectively: 'Torrent ids or hash strings. Omit for every torrent' explains accepted value types and the default behavior of targeting all torrents, which the schema alone does not convey.

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 opens with a specific verb and resource: 'Re-check torrent data against its hashes.' This clearly distinguishes the tool from sibling state-changing tools like start_torrents or remove_torrent, while also clarifying that verification is an integrity check rather than a network re-announce.

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 purpose is clear enough to imply when verification would be appropriate, but there is no explicit guidance about when to choose this tool over alternatives. It does not name any sibling or state conditions like 'use when you suspect data corruption.' The 'Omit for every torrent' note is parameter-oriented, not tool-selection guidance.

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