Use this when the user asks which rooms, speakers, or outputs Roon can play to, or before starting playback when the target zone is unclear (e.g. "what zones are on?", "play in the kitchen", "which speaker is in the office?"). Lists every zone/output the paired Core exposes with its id, display name, current playback state, and output ids. Call this first if no zone is obvious and ROON_DEFAULT_ZONE is not set.

Use this when the user names music to find — an artist, album, track, playlist, radio station, or genre (e.g. "find Tycho", "look up the album In Rainbows", "play some Psytrance", "anything by Ryuichi Sakamoto?"). Resolves a free-text query into ranked Roon browse candidates. Optionally restrict to one item type (artist, album, track, genre, playlist, radio); for non-genre types, an empty typed search broadens to all categories. type:"genre" is special — genres don't appear in Roon's flat search, so the server walks the dedicated Genres tree and returns the nearest-match genre nodes (with parent path in the subtitle) without broadening; e.g. "Psychedelic Trance" yields "Psytrance"/"Trance". Set includeStreaming:true (only meaningful for type:"genre") to also pull a track mix from streaming services (e.g. TIDAL): the server takes the genre-relevant albums and samples tracks across them, so library genre nodes come first and ready-to-play streaming tracks are appended after. Returns opaque, session-scoped item keys for use by the playback tools — pair with get_tracks_for to expand, then play_now or enqueue_and_play.

Use this after search_music when the user wants a concrete list of songs — to preview tracks, build a queue, or pick one to start with (e.g. "what tracks are on this album?", "give me 5 tracks of Dark Ambient", "what's on this playlist?"). Expands an artist, album, genre, or playlist candidate into concrete playable tracks. Pass an itemKey from a recent search_music result. Returns track candidates with session-scoped item keys (use them promptly with enqueue_and_play). Non-expandable items return empty tracks with a skipped reason rather than an error.

Use this when the user wants one specific thing playing right now — an album, artist, playlist, genre mix, or single track (e.g. "play Tycho", "put on In Rainbows", "start some Psytrance in the office", "play that track"). Immediately plays a single search candidate in the target zone and replaces whatever was queued. Pass an itemKey from a recent search_music (or get_tracks_for) result — item keys are session-scoped, so use a fresh one. zoneId is optional: omit it to use ROON_DEFAULT_ZONE, or fall back to the only zone / an "Office" zone / the currently-playing zone; if it still can't decide it returns ZONE_AMBIGUOUS so the agent can ask the user or call list_zones. Optionally shuffle. Returns a PlaybackResult.

Use this when the user wants a custom lineup — a mix of artists, a shuffled selection across albums, a hand-picked set of tracks, or any time "queue", "setlist", "mix of", or "play these in order" comes up (e.g. "queue up five Tycho tracks then some Boards of Canada", "shuffle 10 ambient tracks", "build a set: artist A, then B, then C"). Builds an ad-hoc queue from an ordered list of curated item keys and starts playback in the target zone. This replaces the zone's current queue: the first playable item starts immediately (Play Now), the rest are appended in order. Pass itemKeys from recent get_tracks_for / search_music results (use them promptly — they are session-scoped). zoneId is optional (omit to use the default zone; see play_now). Optionally shuffle. Returns a PlaybackResult with queued/skipped counts so you can backfill skipped items.

Use this when the user asks what is currently playing, what song is on, who's singing, what just started, or wants a snapshot before skipping or pausing (e.g. "what's playing?", "what's playing in the kitchen?", "who's this?", "what's the current track?", "what song is this?"). Returns a structured snapshot: zone id and name, playback state (playing/paused/loading/stopped), title, artist, album, and the current seek position when available. title/artist/album are undefined when nothing is playing. Call this before pause/skip/volume changes when the user hasn't named a zone — it confirms where to act and what the state is. zoneId is optional: omit to use ROON_DEFAULT_ZONE, or fall back to the only zone / an "Office" zone / the currently-playing zone; if it still can't decide it returns ZONE_AMBIGUOUS so the agent can ask the user or call list_zones.

Use this for the common transport verbs — pause, resume, skip, next track, previous track, stop (e.g. "pause", "pause the kitchen", "skip", "next track", "next song", "play the next song", "resume", "resume in the office", "stop", "stop the music"). Runs one transport verb against the resolved zone. For "louder"/"softer" without a number, call now_playing first to read the current state, then set_volume with a target percent — this tool is verbs only. zoneId is optional and resolves like now_playing. Returns the resolved zoneId, the action taken, and the resulting playback state.

Use this when the user wants to change how loud a zone is — turn it up, turn it down, set the volume, or pick a level for a specific room (e.g. "turn it up to 60", "volume to 30 in the office", "set the kitchen to 50", "louder" — see note). Sets the zone's volume to level percent (0 = silent, 100 = max). The server rescales to each output's native range, so a single value works across mixed devices in a grouped zone. Incremental outputs (IR blasters with no numeric range) are reported as skipped rather than guessed at. zoneId is optional and resolves like now_playing. NOTE on relative changes ("louder" / "softer" without a number): this tool is absolute — read the current state with now_playing isn't enough on its own (volume isn't exposed there), so for relative changes, ask the user for a target percent or apply a reasonable default delta.

Use this when the user wants to mute or unmute a zone (e.g. "mute", "mute the kitchen", "unmute", "silence the office", "stop the noise"). Mutes (or unmutes) every output in the resolved zone. zoneId is optional and resolves like now_playing. muted: true mutes, muted: false unmutes.