Skip to main content
Glama
Plex MCP Server

Plex MCP Server

by dustinhansen

Random pick

random_pick
Read-onlyIdempotent

Pick N random items from a Plex library using filters like genre, decade, duration, and watched state—default 3—to solve 'just pick something' choices.

Instructions

N random items matching the same filters as list_media (the 'just pick something' tool). Defaults to 3 picks. Combine watched=unwatched with genre, decade, maxDurationMin etc. user picks as a Plex Home user, so unwatched means unwatched by them. collection with no kind picks the kind the collection holds. Each pick is the record list_media returns (title, year, watched state, genres, duration and so on). detail=true adds fields such as directors, actors, collections and summaries so you can explain the pick. The result's filters object names what each genre/collection/country/studio/label filter matched: the same name ignoring case first, else the first one containing it.

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": "random_pick"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNo
userNosee the library as this Plex Home user (name or id)
yearNo
countNo
genreNo
labelNofilter to items carrying this Plex label. Plex lists every label on the server under every library, so a label used only in another library returns no items rather than an error
ratedNoall
decadeNoe.g. '1970s'
detailNo
studioNo
countryNo
libraryNoMovies
watchedNoall
addedSinceNoISO date or relative like '-30d'
collectionNofilter to members of a collection. Leaving kind out uses the kind of item the collection holds. A smart collection with no tag is an error naming the ratingKey to pass to get_children
contentRatingNoe.g. 'PG-13'
maxDurationMinNo
lastViewedAfterNolast viewed after this ISO date or relative like '-30d'
lastViewedBeforeNolast viewed before this ISO date or relative like '-3y'. Never-watched items match too unless watched='watched'

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.10.0
    • changedInput schema / properties / collection / description
      Previous value: -"filter to members of a collection"New value: +"filter to members of a collection. Leaving kind out uses the kind of item the collection holds. A smart collection with no tag is an error naming the ratingKey to pass to get_children"
    • addedInput schema / properties / label
      Added value: +{
      +  "description": "filter to items carrying this Plex label. Plex lists every label on the server under every library, so a label used only in another library returns no items rather than an error",
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. First observedv0.9.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is added context and it delivers: default of 3 picks, the user-scoped meaning of watched state for Plex Home users, kind inference from a collection, an explicit error case for smart collections that names the ratingKey to pass to get_children, and the name-matching rule used to resolve filters in the result. Return-shape detail is summarized rather than fully specified, so it lands at 4 rather than 5.

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?

Dense but front-loaded: identity and default count come first, then filter combination advice, then return shape, then the filter-resolution footnote. Every sentence carries information, though the trailing sentence about the filters object is syntactically tangled ('the same name ignoring case first, else the first one containing it') and costs a read.

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?

For a 19-parameter, zero-required, no-output-schema tool, the description covers the essentials an agent needs to call it correctly: default count, filter combination strategy, user-scoped watched semantics, detail escalation, and the collection error path. The remaining gap is that most scalar filters are delegated wholesale to list_media rather than described here.

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

Parameters3/5

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

With 19 parameters and only 42% schema description coverage, some compensation is required, and the description does explain the high-value ones: count default, detail, user-scoped watched semantics, and collection's kind inference. However, roughly half the filter parameters (year, rated, addedSince, lastViewedAfter/Before, contentRating, maxDurationMin, studio, country, library) get no meaning beyond 'the same filters as list_media', which forces the agent to open the sibling 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 specific verb and resource ('N random items') plus the exact scope ('matching the same filters as list_media'), and the parenthetical 'just pick something' tool distinguishes it instantly from list_media's exhaustive listing behavior. An agent can choose between this and its sibling without opening either schema.

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?

Gives a clear use case ('just pick something') and practical combination guidance ('Combine watched=unwatched with genre, decade, maxDurationMin etc.'), plus when to escalate with detail=true 'so you can explain the pick'. It stops short of an explicit when-not-to-use statement (e.g. 'use list_media when you need the full set'), which keeps it below a 5.

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