sonarr_list_manualimport

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

The readOnlyHint annotation already signals a safe read operation. The description adds minimal context by mentioning that folder and download_id are query params, but it does not disclose behavior such as the scope of results (all candidates vs. filtered) or any limitations. The added value is small but not contradictory.

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, containing only two short sentences. It successfully front-loads the purpose and avoids unnecessary words, though this brevity comes at the cost of detail.

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?

The tool is a simple list operation with a readOnly annotation and an output schema, which mitigates some gaps. However, the description fails to mention all filtering options or any output behavior, and the lack of guidance on when to use this tool makes it only minimally sufficient for an agent to use 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?

With 5 parameters and 0% schema description coverage, the description was expected to compensate. It only mentions 'folder' and 'download_id' as query params without explaining their meaning or format, and it entirely omits 'series_id', 'season_number', and 'filter_existing_files'. This leaves the semantics of the other parameters unclear.

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 'List' and the resource 'manual import candidates', which accurately defines the tool's action. It also distinguishes itself from the sibling tool 'sonarr_commit_manual_import' by focusing on listing rather than committing.

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 alternatives. The description only states the action and mentions two query parameters, but does not explain when to use them or any preconditions.

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