mcp-lyricscom

Search lyrics by word

search_lyrics

Read-onlyIdempotent

Find songs by a remembered lyric fragment or phrase. Returns matching songs with artist, title, lyric excerpt, and ID/URL for fetching full lyrics.

Instructions

Search lyrics.com for songs whose lyrics contain a given word or phrase. Returns matching songs with artist, title, a short excerpt of the line where the word appears, and the lyrics.com id and URL needed to fetch the full text with get_lyrics. Use this when someone remembers a fragment of lyrics but not the song, or wants songs mentioning a word or theme. One call returns one page of lyrics.com results; to see more, increase 'page' rather than 'limit'. lyrics.com also returns loose and title-only matches, so results are filtered locally to keep only songs where the word genuinely appears in the lyrics. Set 'verify' to "none" to see the raw, unfiltered list.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	Result page on lyrics.com. Each page holds up to 24 raw results.
`limit`	No	Maximum songs to return from this page.
`query`	Yes	Word or short phrase to look for inside the lyrics, for example 'autrefois'.
`verify`	No	How to confirm the query really appears in the lyrics. 'snippet' checks the excerpt lyrics.com already returned and costs nothing. 'full' fetches up to 5 song pages and checks the complete lyrics, which is slow and can trigger rate limiting. 'none' disables filtering.	snippet
`include_excerpt`	No	Include the matching lyric line excerpt in each result.

Output Schema

TableJSON Schema

Name	Required	Description
`page`	Yes
`notes`	Yes	Caveats worth knowing, such as a cache hit or partial verification.
`query`	Yes
`source`	Yes
`results`	Yes
`has_more`	Yes
`next_page`	Yes
`filtered_out`	Yes	Rows dropped because the query was not found in their lyrics.
`raw_result_count`	Yes	Rows lyrics.com returned before local filtering and deduplication.

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv2.0.0Aug 26, 2026

addedOutput schema / properties / filtered_out / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / filtered_out / minimum
```
Added value: +-9007199254740991
```

changedOutput schema / properties / next_page / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / page / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / page / minimum
```
Added value: +-9007199254740991
```
addedOutput schema / properties / raw_result_count / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / raw_result_count / minimum
```
Added value: +-9007199254740991
```

addedOutput schema / properties / results / items / properties / album / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / results / items / properties / album / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / results / items / properties / excerpt / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / results / items / properties / excerpt / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

changedOutput schema / properties / results / items / properties / year / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv1.0.0Aug 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral context beyond that: one call returns one page, increasing page is preferred over limit, lyrics.com returns loose and title-only matches so results are filtered locally, and verify='full' can be slow and trigger rate limiting. None of this contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Six sentences, no filler, and every sentence earns its place: purpose, return value, use case, pagination behavior, filtering rationale, and verification option. The most important scoping information is front-loaded.

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 read-only search tool, this is complete: it covers trigger scenarios, return shape, pagination, filtering behavior, verification tradeoffs, and the connection to get_lyrics. The output schema handles return details, and annotations handle the safety profile, so nothing an agent needs to invoke it correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, so every parameter is already documented, but the description adds operational guidance beyond the schema: use 'page' rather than 'limit' to see more results, verify='none' exposes the raw unfiltered list, and verify='full' fetches up to 5 pages with rate-limit risk. This materially helps an agent choose parameter values correctly.

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?

The description opens with a specific verb and resource: 'Search lyrics.com for songs whose lyrics contain a given word or phrase.' It also distinguishes itself from get_lyrics by stating it returns the id and URL needed to call get_lyrics, and the use case ('remembers a fragment of lyrics but not the song') separates it from a song-title search like search_songs.

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?

The description gives an explicit trigger: 'Use this when someone remembers a fragment of lyrics but not the song, or wants songs mentioning a word or theme.' It does not explicitly name search_songs as the alternative or state when not to use this tool, so it stops short of a 5.

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

Deploy Server