# find_music_guides: find a Clef guide for a music task

For AI agents: the site index is at https://clefdrills.com/llms.txt and the HTML version of this page is at https://clefdrills.com/docs/mcp/tools/find-music-guides.

Find Clef guides by words in the title and description. Part of the [Clef Music Tools MCP server](https://clefdrills.com/docs/mcp). Endpoint: `https://clefdrills.com/mcp`, no account needed, read-only.

## What it does

`find_music_guides` searches the Clef guide library by words in each guide title and description and returns up to 8 matches, best match first. Use it when someone asks how to convert or learn music: MIDI, PDF, tabs, audio, notation formats, practice routines.

The guides explain workflows. They are not file converters, and this tool does not convert anything. Read a returned guide with the MCP `resources/read` method on its `uri` before answering from it.

## Input schema

```
{
  "query": string, 1 to 200 characters
}
```

All fields are validated before the tool runs.

## Output

On success: `structuredContent` with `guides` (up to 8 items of `{ title, description, uri }`, ranked by how many query words match) and `directory`, a page that lists the guides by task.

## Example calls

### PDF to MIDI

The list is shortened here. The first guide in the live result for this query is a routing guide for music tasks with an AI assistant.

```bash
curl -s https://clefdrills.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_music_guides","arguments":{"query":"pdf to midi"}}}'
```

Result:

```
{ "guides": [
    { "title": "PDF Sheet Music to MusicXML: Scan, Check and Edit",
      "description": "A practical guide to converting PDF sheet music into editable MusicXML with optical music recognition, followed by systematic notation checks and cleanup.",
      "uri": "https://clefdrills.com/blog/pdf-sheet-music-to-musicxml.html" },
    { "title": "Fix Unreadable MIDI Sheet Music: Rhythm, Pedal and Voices",
      "description": "A practical repair workflow for turning a cluttered MIDI-derived score into readable notation by checking rhythmic grids, tuplets, pickup measures, sustain pedal data, and independent voices.",
      "uri": "https://clefdrills.com/blog/midi-notation-rhythm-repair.html" },
    ... up to 8 guides in total
  ],
  "directory": "https://clefdrills.com/blog/music-conversion-workflow-finder.html" }
```

### Guitar tab

The list is shortened here.

```bash
curl -s https://clefdrills.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_music_guides","arguments":{"query":"guitar tab"}}}'
```

Result:

```
{ "guides": [
    { "title": "Tabs to Piano Sheet Music: ASCII, GP Files and Rhythm",
      "description": "A practical guide to converting ASCII guitar tablature or structured GP, GPX and GP5 files into readable piano notation while preserving pitch, rhythm and octave intent.",
      "uri": "https://clefdrills.com/blog/tab-files-to-piano-sheet-music.html" },
    { "title": "Guitar, Bass and Ukulele Tabs to Piano: Tuning, Capo and Octaves",
      "description": "A practical manual method for turning guitar, bass, and ukulele ASCII tabs into playable piano notes while accounting for alternate tunings, capos, octave placement, and incomplete rhythm information.",
      "uri": "https://clefdrills.com/blog/alternate-tuning-tabs-piano.html" },
    ... up to 8 guides in total
  ],
  "directory": "https://clefdrills.com/blog/music-conversion-workflow-finder.html" }
```

### No match

A query with no matching words is not an error: `guides` is an empty array and `directory` still points to the full list.

```bash
curl -s https://clefdrills.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_music_guides","arguments":{"query":"zzzqqq"}}}'
```

Result:

```json
{ "guides": [], "directory": "https://clefdrills.com/blog/music-conversion-workflow-finder.html" }
```

## Edge cases and errors

- Matching looks for each query word inside the title and description text. Use specific words such as `midi`, `tab`, `pdf`, `capo`.
- An empty query is rejected by validation. A query longer than 200 characters is also rejected.
- Results are guides on clefdrills.com. The `uri` values can be read through the server as resources with `resources/read`.

Errors come back as a normal tool result with `isError: true`, so the client can show the message. Real error results from the live server:

```
arguments: {"query":""}

{ "isError": true, "content": [{ "type": "text", "text": "MCP error -32602: Input validation error: Invalid arguments for tool find_music_guides: String must contain at least 1 character(s) at query" }] }
```

## Related pages

- [Connect a client](https://clefdrills.com/docs/mcp/connect)
- [Limits and privacy](https://clefdrills.com/docs/mcp/limits-and-privacy)
- [All Clef Music Tools docs](https://clefdrills.com/docs/mcp)
