arr-mcp

Overview Schema Source Related Servers Discussions Admin

Media details

get_media_details

Read-only

Retrieve merged media details across services—watch state, ratings, availability, audio languages, and season counts—or inspect one service's raw record by service and id.

Instructions

Everything known about one item. A title as query returns the merged record (acquisition, watch state, ratings, presence across services); service plus id returns that service's raw view, for checking a join that looks wrong. A series carries seasons with per-season watched, on-disk, aired and total counts, and monitored, Sonarr's own flag: check it before delete_episode_files, because deleting a monitored season's files makes Sonarr download them again. At detail: "full" a series lists its episodes and a Lidarr artist its albums with their ids. audioLanguages (per episode for a series, on the record for a film) are the tracks read off the file: that, not a MULTi release name, answers "is the dub here". With Reclaimerr, cleanup says what will delete or move it, and when. Field reference: arr://docs/get_media_details.

Input Schema

Name	Required	Description	Default
`id`	No	The item's id within that service.
`limit`	No	Maximum items to return. Defaults to 50, hard maximum 500.
`query`	No	A title, matched against every title the services know (original and alternate titles too). When other items match equally well, the answer carries `ambiguous: true` and their `candidates`. A title not in your library is refused with what a metadata lookup knows of it, so no other search is needed.
`detail`	No	How much per-item detail to return. Defaults to standard.	standard
`service`	No	With `id`: one service’s own view.
`instance`	No	Which instance (e.g. "4k") when several of this service exist. Omit it when there is one.

Output Schema

Name	Required	Description	Default
`kind`	Yes
`title`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.74.0Nov 9, 2026

removedInput schema / $schema

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

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."

changedInput schema / properties / query / description

Previous value: -"A title. Resolved through the library index."New value: +"A title, matched against every title the services know (original and alternate titles too). When other items match equally well, the answer carries `ambiguous: true` and their `candidates`. A title not in your library is refused with what a metadata lookup knows of it, so no other search is needed."

removedOutput schema / $schema

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

First observedv0.1.0Nov 9, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=true, and the description adds real behavioral context: merged vs. raw sourcing, an `ambiguous: true` plus `candidates` outcome for tied title matches, refusal-with-metadata for titles not in the library, and per-season monitoring consequences downstream. It does not cover pagination or how `limit` interacts with `detail` for large series.

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

Conciseness5/5

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

Front-loaded with a one-line scope statement, then a dense sequence of mode, caveat, and field notes with no filler sentences; the pointer to arr://docs/get_media_details correctly offloads the exhaustive field list. Its length is justified by the number of non-obvious behaviors it must surface.

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

Completeness4/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 values need not be enumerated, and the description still highlights the fields an agent would otherwise misread (`seasons`, `monitored`, `audioLanguages`, `cleanup`). Slightly incomplete on result-volume behavior (`limit` default 50, max 500) when `query` matches many items.

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; the description earns above that by explaining what `query` actually matches (original and alternate titles, ambiguity handling) and what `detail: "full"` changes structurally, which the schema only labels. `limit` and `instance` are left to their schema text.

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

Purpose4/5

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

States a concrete retrieval verb and resource ("Everything known about one item") and distinguishes its two access modes: merged record via `query`, raw single-service view via `service`+`id`, with `detail: "full"` expanding to episodes/albums. It never names the sibling reader tools (get_library, search_media, lookup_media) directly, though the note that a miss returns metadata "so no other search is needed" implicitly routes away from them.

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?

Gives mode-selection guidance with reasons: `service`+`id` is "for checking a join that looks wrong"; `detail: "full"` when you need per-episode or per-album ids. It adds a concrete pre-condition for a destructive sibling ("check `monitored` before delete_episode_files") and tells the agent which field to trust when resolving dub presence.

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