Skip to main content
Glama

Diagnose a missing or unplayable item

diagnose_media
Read-only

Explains why a media title is not playable by checking each step from request to playback and naming the first blocking cause, with a remedy and suggested next steps.

Instructions

Why is this not playable? Walks the chain (requested, managed, monitored, downloaded, indexed, imported, scanned) and names the first thing that explains it, with a remedy and, where a tool call fixes it, next_steps to offer the user; this tool never runs them. Give a title as query, or service plus id when you already hold an exact item. A title not in the library is looked up in Cleanuparr, download-client history and the library event log, so a removed release can still be explained. A step it could not check sets certain: false, and the summary says what was missed. With Reclaimerr it says when a cleanup rule deleted or will delete the title; with Bazarr it notes missing subtitles. A Lidarr artist is walked too (tracks on disk, queue, indexers, media server): playable means at least one track, and get_media_details lists its albums. Field reference: arr://docs/diagnose_media.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "diagnose_media"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNo
userNoWhose watch state to consider. Defaults to the configured default_user; any other value requires allow_other_users.
queryNoA title: how a person actually asks.
serviceNoWith `id`: an exact item, when one is already in hand.
instanceNoWhich instance (e.g. "4k") when several of this service exist. Omit it when there is one.

Output Schema

NameRequiredDescriptionDefault
queryYes
stepsYes
historyNo
verdictYes
degradedYes
resolvedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.2.0
    • 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",
      +  "lidarr",
      +  "jellyfin",
      +  "plex"
      +]
  2. Addedv1.84.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond readOnlyHint=true by stating the tool never executes the suggested next_steps, that unverifiable steps set `certain: false` with the miss noted in the summary, that titles absent from the library are resolved via Cleanuparr, download-client history and the event log, and that Reclaimerr/Bazarr/Lidarr integrations add their own findings.

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-loaded with the motivating question and the outcome, then input rules, then edge-case behavior; nearly every sentence carries new information. It is dense and long, with integration asides (Reclaimerr, Bazarr, Lidarr) that could be tightened, but nothing is pure 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 multi-source diagnostic with five optional parameters, the description covers input choice, degraded-result signaling, external-system fallbacks, and domain-specific semantics for Lidarr artists, all of which an agent needs to interpret results. An output schema exists, yet the description still summarizes `remedy`/`next_steps`/`certain`, and it points to arr://docs/diagnose_media for field detail.

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?

With 80% schema coverage the baseline is 3, but the description adds combination semantics the schema only hints at: prefer `query` for human-style titles, reserve `service`+`id` for an exact item already in hand, and it explains the fallback lookup path used when a title is not in the library. The `user` and `instance` parameters are left to the schema.

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 precise verb chain and outcome: it walks requested/managed/monitored/downloaded/indexed/imported/scanned and names the first step that explains the problem, returning `remedy` and `next_steps`. This is clearly distinguishable from siblings like get_media_details, which it references only for album listing.

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

Usage Guidelines4/5

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

Frames the triggering question ('Why is this not playable?') and gives explicit input-selection rules: pass a title as `query`, or `service` plus `id` when an exact item is already held. It does not state when to prefer get_media_details, get_stack_health or get_playback instead, so alternatives remain implicit.

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