sonarr_trigger_downloaded_scan

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

With no annotations, the description carries the burden of explaining behavior. It conveys that this is a mutating action (importing files) and requires a path, but it does not disclose whether the command runs asynchronously, returns a command ID, or has side effects like potential duplicate imports. The description is accurate but lacks deeper behavioral detail.

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 concise sentences. The first sentence front-loads the action and purpose, the second clarifies the required parameter with an example. Every word adds value with no redundancy or fluff.

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 trigger tool with no output schema, the description is nearly complete: it explains what it does, when to use it, and what input is needed. However, it doesn't mention what the user should expect in response (e.g., command ID or status), which would make it fully complete. Given the simplicity, a 4 is reasonable.

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 100% (single 'path' parameter with a helpful description). The tool description essentially repeats the schema's parameter description and adds an example. It doesn't add significant new meaning beyond what the schema already provides, so baseline 3 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?

The description clearly states the tool's verb and resource: 'Force a scan of a completed downloads path to import any files that were not auto-imported.' This distinguishes it from sibling trigger tools like sonarr_trigger_rescan_series (which scans series folders) and sonarr_process_manual_import (manual imports). The purpose is specific 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?

The description provides clear context for when to use the tool: when files were not auto-imported, you force a scan of the completed downloads path. It also specifies the required input (absolute path). However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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