arr-mcp

Overview Schema Source Related Servers Discussions Admin

Delete a film, series or book

delete_media

Destructive

Removes a movie, series, or book entry from Radarr, Sonarr, Whisparr, or Grimmory, with an option to delete files from disk. Previews first, then confirms to apply.

Instructions

Removes a film from Radarr, a whole series (or Whisparr site) from Sonarr or Whisparr, or a book from Grimmory, optionally deleting its files from disk. Grimmory always deletes the files of a book, so it needs delete_files: true and takes no import exclusion. Destructive and not undoable — files are gone, not moved to a recycle bin unless the service itself is configured for one. Takes service and id, never a title: take id from acquisition.id on a get_library or get_media_details record. Sonarr and Whisparr delete the entire series/site; to remove one season's files or specific episodes, use delete_episode_files instead. Previews first; confirm to delete.

Input Schema

Name	Required	Description
`id`	Yes	The item's id within that service, as an integer string.
`confirm`	No	The token from this tool's preview, passed back verbatim to apply it. Single-use and bound to the previewed arguments.
`dry_run`	No	Preview without a confirm token, for "what would happen if" questions; not the first step of a real change.
`service`	Yes
`instance`	No	Which instance (e.g. "4k") when several of this service exist. Omit it when there is one.
`delete_files`	No	Also delete the files from disk. Defaults to false, which removes only the entry and leaves the media where it is.
`add_import_exclusion`	No	Also add an import exclusion so it is never re-added automatically. Defaults to false.

Output Schema

Name	Required	Description	Default
`noop`	Yes
`tier`	Yes
`tool`	Yes
`result`	No
`target`	Yes
`applied`	Yes
`dry_run`	Yes
`effects`	Yes
`service`	Yes
`summary`	Yes
`audit_id`	No
`warnings`	No
`operation`	Yes
`unchecked`	No
`next_steps`	No
`permission`	Yes
`confirm_error`	No
`confirm_token`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedv1.74.0Nov 9, 2026

removedInput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / confirm / description

Previous value: -"The confirmation token from this same tool's preview of this same operation. Omit it to get a preview and a token; pass the token back verbatim to apply the change. Tokens are single-use, expire, and are bound to the exact operation and arguments previewed."New value: +"The token from this tool's preview, passed back verbatim to apply it. Single-use and bound to the previewed arguments."

changedInput schema / properties / dry_run / description

Previous value: -"Preview only: resolve the target and describe exactly what would happen, then stop. Never mutates anything and never returns a confirmation token. Use this to answer \"what would happen if…\" — not as the first step of actually doing it."New value: +"Preview without a confirm token, for \"what would happen if\" questions; not the first step of a real change."

changedInput schema / properties / instance / description

Previous value: -"Which instance, when several of this service are configured — for example \"4k\" or \"hd\". Omit it when there is only one. If several are configured and you omit it, the call is refused and the names are listed."New value: +"Which instance (e.g. \"4k\") when several of this service exist. Omit it when there is one."

removedInput schema / properties / service / description

Removed value: -"radarr, sonarr, whisparr, or grimmory."

changedInput schema / properties / service / enum

Previous value: -[
-  "radarr",
-  "sonarr",
-  "whisparr",
-  "lidarr",
-  "prowlarr",
-  "bazarr",
-  "jellyfin",
-  "seerr",
-  "sabnzbd",
-  "nzbget",
-  "transmission",
-  "qbittorrent",
-  "plex",
-  "profilarr",
-  "cleanuparr",
-  "reclaimerr",
-  "dispatcharr",
-  "shelfmark",
-  "grimmory"
-]New value: +[
+  "radarr",
+  "sonarr",
+  "whisparr",
+  "grimmory"
+]

removedOutput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

removedOutput schema / properties / applied / description

Removed value: -"Whether the change actually happened. False on every preview, refusal and no-op."

removedOutput schema / properties / audit_id / description

Removed value: -"The audit row this call wrote. Every branch writes one, including previews and refusals."

removedOutput schema / properties / confirm_error / description

Removed value: -"Why a presented token was rejected. Present only when one was presented."

removedOutput schema / properties / confirm_token / description

Removed value: -"Present when a preview is awaiting confirmation. Single-use, expiring, bound to this exact operation and arguments."

removedOutput schema / properties / dry_run / description

Removed value: -"Whether this was an explicit preview."

removedOutput schema / properties / effects / description

Removed value: -"Itemised consequences, most severe first. Empty is legitimate for a no-op."

removedOutput schema / properties / next_steps / description

Removed value: -"Present on an applied write when another call is worth offering. Offer it to the person; do not run it."

removedOutput schema / properties / noop / description

Removed value: -"True when the request resolved but there was nothing to do — already monitored, already approved."

removedOutput schema / properties / result / description

Removed value: -"Whatever the service returned, on a write that landed."

removedOutput schema / properties / summary / description
```
Removed value: -"One sentence, safe to show a human."
```

removedOutput schema / properties / target / description

Removed value: -"The resolved id the write acts on — what the confirmation token is bound to."

removedOutput schema / properties / unchecked / description

Removed value: -"Present when a service could not be asked, so its absence from `warnings` means nothing."

removedOutput schema / properties / warnings / description

Removed value: -"Present on a preview when another service has something to say about this change. Tell the user before confirming."

First observedv0.1.0Nov 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the destructiveHint annotation: states the action is not undoable, files are gone rather than recycled unless the service itself is configured for a bin, and that Sonarr/Whisparr delete the entire series/site. It also discloses the service-specific quirk that Grimmory always deletes book files, requiring delete_files=true and taking no import exclusion.

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?

Front-loads the core action and per-service mapping, then the safety warning, then the alternative tool. Dense but each sentence carries a distinct constraint; the Grimmory caveat and the id-sourcing note could be tightened slightly but neither is filler.

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?

For a destructive multi-backend delete with an output schema already covering returns, the description supplies everything an agent needs: target resource per service, id source, preview/confirm protocol, irreversibility, and the correct sibling for narrower deletion.

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 already 86%, so baseline is 3; the description adds genuine cross-parameter meaning the schema cannot express — that `id` comes from `acquisition.id` on a get_library or get_media_details record, and that Grimmory requires delete_files=true and forbids add_import_exclusion. It stops short of explaining `instance` or the dry_run/confirm token relationship, which remain schema-only.

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?

States a specific verb ("Removes") and enumerates the exact resource per backend: film from Radarr, series/site from Sonarr or Whisparr, book from Grimmory. It also names the sibling it must not be confused with (delete_episode_files), so an agent can route correctly without opening a schema.

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 when-to-use and when-not: use delete_episode_files to remove one season's files or specific episodes instead. It also prescribes the workflow ("Previews first; confirm to delete"), warns that `service`+`id` are required and never a title, and tells where to source the id.

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