Discover Tracks by Criteria
discover_tracksRead-only
Find catalog tracks by criteria, with no seed track: tempo, key, genre, release year, chart placement and audio-feature ranges in one call — e.g. house at 122-126 BPM in 8A or its neighbours with energy above 0.7: min={"tempo": 122, "energy": 0.7}, max={"tempo": 126}, key="8A", harmonic=true, genre="house".
At least one narrowing filter is required (a tempo/feature bound, key, mode, genre, year
or chart). Returns `results` (one per recording, each with its bpm, camelot, energy,
danceability, valence, acousticness and loudness_db plus catalog metadata),
`total_matches` (exact up to 1,000; `total_matches_capped` above that), `next_offset`
for the next page, and `filters` — what was applied and how many tracks each filter
removed (`dropped_by`); if the list is short, loosen the largest one. energy, danceability
and valence are on FreqBlog's own scales, so derive thresholds from values you have seen
rather than from another service's. Results reach a depth of 500 per query; narrow the
filters to go further. Pass a result's itunes_track_id to get_audio_features for every
field, or to suggest_next_track / build_setlist. Costs 1 quota unit.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "discover_tracks"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Comma list of keys: Camelot ('8A'), Open Key ('1m') or names ('A minor'). | |
| max | No | HARD upper bounds, e.g. {'tempo': 126}. Same attributes as `min`; combine the two for a range. | |
| min | No | HARD lower bounds, e.g. {'tempo': 122, 'energy': 0.7}. Tracks below the bound, and tracks with no analysed value, are excluded. Attributes: acousticness, danceability, duration_ms, energy, loudness, tempo, valence. | |
| mode | No | 'major' or 'minor' only. | |
| sort | No | 'chart' (default: charted first, then newest), 'newest', 'oldest', 'tempo', '-tempo', 'energy', '-energy', or 'target' (default when `target` is given). | chart |
| genre | No | Comma list of catalog genre names, e.g. 'house' or 'hip-hop,r&b'. Unknown names in a list are skipped and listed in filters.ignored with close matches; only a list where every name is unknown is rejected. | |
| limit | No | Tracks per page (default 20). | |
| offset | No | Skip this many tracks for the next page; offset + limit may not exceed 500. | |
| target | No | PREFERRED values, e.g. {'energy': 0.8}: nearest first, nothing removed. Same attributes as `min`. | |
| charted | No | true = only tracks with a known chart placement (about 4% of tracks have one). | |
| explicit | No | true = explicit tracks only, false = non-explicit only; omit for either. | |
| harmonic | No | Widen each key to its harmonically compatible keys (same, relative, one step either way on the Camelot wheel). | |
| max_year | No | Latest release year. | |
| min_year | No | Earliest release year. | |
| tempo_match | No | 'exact' (default) or 'half_double' — also match double/half the min/max tempo range (an 87 BPM track for a 174 BPM set). | exact |
| min_chart_peak | No | Best chart position required, as chart_peak (1-100, 100 = a number one). | |
| include_subgenres | No | Also match every subgenre of a top-level genre. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||