arr-doctor

manual_import

Destructive

Import specific download files into Sonarr or Radarr with all-or-nothing validation; manually assign unknown series, episodes, or movies before anything moves.

Instructions

Import specific files from the downloads folder into the library (all or nothing). Never imports a whole folder blindly: every file must be listed, must be matched to a series/episode or movie, must have no rejections, and no two files may target the same episode or movie. If anything fails, nothing is imported and the problems are returned. When Sonarr/Radarr cannot identify a file ("Unknown Series", "matched by ID, manual import required"), pass matches to assign it by hand; the assignment is re-validated first. Replacing a file that is already in the library needs allow_replace=true. By default it waits for the import and verifies each file (Sonarr/Radarr report the command as successful even when a file fails to move), returning the reason from their log for any file that did not get in.

Examples: "Import /downloads/The.Capture.S03E04.1080p.mkv", "Import that file as episode 4 of season 3 of The Capture"

Input Schema

TableJSON Schema

Name	Required	Description	Default
`wait`	No	Wait (up to 2 min) for the import and check that every file really got in
`files`	Yes	Exact file paths as seen by Sonarr/Radarr (from find_orphan_downloads)
`matches`	No	Manual identification for files that were not matched (or were matched wrongly)
`service`	Yes	'sonarr' (series) or 'radarr' (movies)
`import_mode`	No	auto (default, like the web UI): copy/hardlink if the download client is still seeding, move otherwise. copy: always copy/hardlink. move: always move (breaks seeding).	auto
`allow_replace`	No	Allow replacing files that are already in the library (they are deleted)
`allow_downgrade`	No	Also import files Sonarr/Radarr reject as 'not an upgrade' (lower quality or score than the current file). Only when the user explicitly wants the lower version; needs allow_replace.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Oct 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already mark this destructive, but the description goes well beyond them: it explains the all-or-nothing validation contract (every file must be listed, matched, rejection-free, and uniquely targeted), that failures return the problems, that assignment is re-validated, that Sonarr/Radarr falsely report success so each file is verified against the log, and that import_mode 'move' breaks seeding. This is unusually rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the all-or-nothing contract are front-loaded, then edge cases, then examples. Dense but nearly every sentence carries a distinct operational fact; it is longer than strictly necessary but not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is unnecessary; the description covers the remaining risk surface (atomicity, validation, replacement, verification, seeding impact) for a 7-parameter destructive tool. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: allow_replace is required before a replacement, and allow_downgrade both needs allow_replace and should only be used on explicit user intent. It also clarifies that `wait` verification exists because the upstream command lies about success.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb (Import), resource (specific files from the downloads folder), and destination (the library), plus the atomicity constraint. It is clearly distinguishable from siblings like diagnose_import (read-only diagnosis) and find_orphan_downloads (discovery of candidate paths).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit conditions are given for the non-obvious paths: pass `matches` when Sonarr/Radarr report 'Unknown Series' or 'matched by ID, manual import required'; allow_replace=true when replacing a library file; allow_downgrade only when the user explicitly wants a lower version. It also names find_orphan_downloads as the source of valid paths, and the two examples show the intended invocation.

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