commendation

Overview Schema Source Related Servers Discussions Admin

recommend_from_playlist_for_mood

Find new songs from one playlist based on a listener's mood. It reads every track, scores mood fit, and seeds only genuine matches for recommendations.

Instructions

Recommend new songs from ONE playlist, shaped by how the listener feels.

For "I feel like this -- look at this playlist and find me songs". Use this over recommend_from_playlist whenever a mood is part of the ask, and over recommend_for_mood whenever a specific playlist is.

Unlike recommend_from_playlist, which samples a few tracks at random and ignores mood entirely: EVERY track in the playlist is read and scored for mood fit, and only genuine matches -- tracks whose own mood resolves and actually fits the target -- are used as seeds. An off-mood playlist therefore yields few seeds or none, which is reported rather than papered over by seeding from tracks that don't fit.

Seeding costs ~4 API calls per seed, so the best-fitting seeds are capped (default 20, override with seed_cap). seed_report in the result says how many tracks were considered, how many were genuine, and how many were capped away.

Mood arguments behave exactly as in recommend_for_mood (vector preferred, then feeling, then context; falls back to inferred mood). arc shapes the sequence the same way. Results are guaranteed absent from Liked Music, from this playlist, and from every other playlist -- and limit is a ceiling, not a guarantee: filler is capped at 25% of it, same as recommend_for_mood.

This is READ-ONLY -- it never creates a playlist or adds anything anywhere. To turn the result into a real playlist, pass the returned videoIds to a playlist-management tool, then call refresh_library() so the new tracks are excluded from later recommendations.

Input Schema

TableJSON Schema

Name	Required	Default
`arc`	No	mirror
`bpm`	No
`limit`	No
`vector`	No
`bpm_max`	No
`bpm_min`	No
`context`	No
`feeling`	No
`language`	No
`seed_cap`	No
`playlist_id`	Yes
`exclude_languages`	No
`allow_unlabelled_language`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 13, 2026

TDQS

A4.5/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden and does so richly: read-only guarantee, ~4 API calls per seed with a default cap of 20, seed_report contents (considered/genuine/capped), the fact that off-mood playlists legitimately yield few or no seeds rather than being papered over, exclusion guarantees, and the 25% filler ceiling on `limit`. This is exactly the cost/side-effect/auth context an agent needs.

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 one-line purpose and the routing rule before any internals, and every paragraph adds a distinct fact (contrast, cost/seed behavior, mood args, guarantees, read-only follow-up). It is long, and a couple of clauses ('same as recommend_for_mood') are mild repetition, but no paragraph is filler.

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?

With an output schema present it correctly avoids re-describing return values while still flagging the meaningful `seed_report` field. For a 13-parameter, no-annotation, no-schema-description tool it covers behavior thoroughly, but the unaddressed bpm/language parameter family is a real completeness gap.

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?

Schema description coverage is 0%, so the description must compensate and it only partially does. It clarifies vector>feeling>context precedence, arc's shaping role, seed_cap, and limit's ceiling semantics, but 13 parameters exist and bpm/bpm_min/bpm_max, language, exclude_languages, and allow_unlabelled_language are never addressed beyond their self-evident names.

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+resource+scope: 'Recommend new songs from ONE playlist, shaped by how the listener feels.' It explicitly contrasts itself with both closest siblings (recommend_from_playlist and recommend_for_mood) and names the distinguishing dimension (mood presence, playlist specificity).

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 explicit routing rules: 'Use this over recommend_from_playlist whenever a mood is part of the ask, and over recommend_for_mood whenever a specific playlist is,' plus a concrete user-facing trigger ('I feel like this -- look at this playlist and find me songs'). It also explains the follow-up workflow (pass videoIds to a playlist tool, then call refresh_library()).

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

Deploy Server