mcp-lyricscom

Search lyrics by word

search_lyrics

Read-onlyIdempotent

Find songs when you remember only a lyric fragment or theme by searching lyrics.com for a word or phrase; get matching titles, artists, excerpts, and URLs for 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.

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": {
      "query": "<query>"
    },
    "name": "search_lyrics"
  }
}

Input 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

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.

Changed4 schema fields changedv2.1.0Oct 30, 2026
- removedOutput schema / properties / results / items / properties / album / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / album / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / results / items / properties / excerpt / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / excerpt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

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.7/5.0

Behavior4/5

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: lyrics.com returns loose and title-only matches that are filtered locally, 'full' verification can trigger rate limiting, and one call yields only one page. It does not quantify paging limits or error behavior, but the annotations already carry the safety profile and the description adds substantial operational context.

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?

Front-loads the core action and return shape, then adds usage trigger, pagination guidance, filtering caveat, and the verify escape hatch. Five sentences, no filler, each adding distinct decision-relevant information.

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 5-parameter read tool with an output schema and full annotation coverage, the description supplies everything needed to call it correctly: triggering condition, pagination strategy, filtering semantics, and rate-limit risk. Return-value detail can be deferred to the output schema, so nothing material is missing.

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?

With 100% schema coverage the baseline is 3, and the description adds real meaning on top: it explains the page-vs-limit tradeoff ('increase page rather than limit') and the semantics of verify='none' as raw unfiltered output. It leaves the numeric caps to the schema, which is appropriate.

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 ('Search lyrics.com for songs whose lyrics contain a given word or phrase') and spells out the return payload: artist, title, excerpt, lyrics.com id and URL. It explicitly links to the sibling get_lyrics as the follow-up for full text, so the agent can distinguish it from both siblings without opening a schema.

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 the exact triggering scenario ('someone remembers a fragment of lyrics but not the song') and names the alternative (get_lyrics) for fetching full text. It also resolves the operational ambiguity between 'page' and 'limit' and explains when to use verify='none', which is guidance an agent could not infer elsewhere.

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

Deploy Server