Search indexers for a release

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

Goes well beyond the annotations by disclosing that the call queues asynchronously and returns immediately, that success is not guaranteed, and that the confirm token is single-use and argument-bound. It also states that season plus episodes is refused rather than resolved. The only gap is that it doesn't say what the preview payload or response contains, which is partly covered by the output 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 purpose and the "not a title" caveat are front-loaded, and the sentence order moves logically from intent to parameters to async behavior. It is information-dense but slightly redundant where it restates season/episodes exclusivity already documented in 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 complex eight-parameter, multi-service mutation with a confirmation flow, the description covers provenance of the id, per-service variance, mutual exclusivity, and asynchronous semantics. With annotations and an output schema already present, nothing an agent needs to call this 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?

With 88% schema coverage the baseline is 3, but the description adds real meaning the schema lacks — notably that id must come from acquisition.id on a get_library or get_media_details record, and that on Lidarr the id is an artist rather than an album. Some per-service rules duplicate the schema's own parameter 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?

States a concrete verb and resource across the four services and frames the intent memorably as "the 'it never downloaded, try again' action," which separates it from passive listing tools like get_releases and from grab_release. The note that it takes an id rather than a title further sharpens the distinction.

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?

Gives explicit triggering conditions (an item already tracked that never downloaded) and per-service parameter rules, plus the preview-then-confirm workflow. It stops short of naming sibling alternatives such as get_releases or grab_release by name, so the agent must infer those boundaries.

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