Skip to main content
Glama
Sign In
lyricmood-mcp

lyricmood-mcp

by yigitates17
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Build Mood Playlist

build_mood_playlist

Generate a mood-matched, ordered song playlist from lyric themes and valence/energy targets, optionally following a 2–5 stage emotional arc; review it before saving to Spotify.

Instructions

Pick and order songs for a mood, judging both what the lyrics are about (mood_text) and how the music feels (valence/energy targets you choose from the user's request). With arc, songs move gradually through 2-5 moods (e.g. heartbroken -> hopeful). Songs come from the seed artists and similar artists, or from the user's top and liked songs. This only proposes a list: show it to the user, then call create_spotify_playlist with the ids if they want it saved. The first run for new artists can take a minute or two.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mood_text": "<mood_text>"
    },
    "name": "build_mood_playlist"
  }
}

Input Schema

NameRequiredDescriptionDefault
arcNoOptional journey, e.g. sad -> hopeful: 2-5 stages in order. Songs move gradually from the first stage to the last. Overrides mood_text/valence/energy for ordering.
sizeNoNumber of songs (5-50).
energyNoTarget intensity 0-1 (calm ≈ 0.2, mid ≈ 0.5, intense ≈ 0.85).
valenceNoTarget musical positivity 0-1 (sad ≈ 0.15, neutral ≈ 0.5, happy ≈ 0.85).
mood_textYesWhat the lyrics should be about or feel like, e.g. 'missing someone, lonely nights'. Several lines are averaged: give the mood in each language of the music (e.g. English and Finnish), because the model favours lyrics in the query's language.
seed_artistsNoDraw songs from these artists and similar ones. Empty: use the user's own top and liked songs.
feature_weightNoHow much valence/energy count against lyrics (0 = lyrics only).
max_per_artistNoVariety cap per artist.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that the tool is non-mutating ("only proposes a list"), where candidate songs come from, that `arc` overrides other ordering inputs, and a real latency caveat ("first run for new artists can take a minute or two"). It stops short of any failure-mode or rate-limit guidance, so it is not fully complete.

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?

Purpose is front-loaded in the first clause and every following sentence adds new information (arc behavior, song sources, save workflow, latency). The parenthetical "(valence/energy targets you choose from the user's request)" is slightly awkward but not wasted.

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 an 8-parameter tool with one required argument and no output schema, the description covers the intent, the source pool, the ordering modes, the downstream save step, and latency. What it omits are edge cases such as behavior when a user has no top/liked songs and no seeds, which would matter for a first-time caller.

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 still adds relational meaning the schema cannot convey, notably that `arc` takes 2-5 ordered stages through which songs move gradually and that it overrides mood_text/valence/energy for ordering. It does not explain feature_weight or max_per_artist in prose, leaving those 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?

"Pick and order songs for a mood" gives a specific verb plus resource, and the description immediately clarifies the two signals it judges on (lyrics via mood_text, feel via valence/energy). It also distinguishes itself from the sibling create_spotify_playlist by stating it only proposes a list rather than saving one.

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?

It spells out the workflow: show the proposed list to the user, then call create_spotify_playlist with the ids if they want it saved. It also states when to prefer `arc` over mood_text/valence/energy for ordering, and when seed_artists is empty the fallback to the user's top and liked songs is explicit.

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

Deploy Server

Other Tools