reannounce_torrents

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.