FreqBlog Music Metadata

Suggest Next Track

suggest_next_track

Read-only

Given a seed track, return the top-N catalog tracks to play NEXT, ranked by transition score. Each suggestion carries the same score, per-component scores and human reason as score_transition (e.g. "11B->11B same key, 118->117 BPM (-0.29), energy +0.12"), plus its genre and genre_relation to the seed. GENRE-AWARE by default (cross_genre=auto): off-genre picks that only coincidentally share the seed's key/BPM sink to the bottom — use cross_genre=strict for same-genre-family only, or allow for the old harmonic-only ranking. It is the seed's sonic neighbours re-ranked for a clean mix.

Returns `seed`, `count`, and a `suggestions` array of {track, score, components, reason}.
seed_track_id is a catalog itunes_track_id from search_catalog or a get_audio_features
result. Pair with build_setlist to order a whole crate. Costs 3 quota units.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`n`	No	How many next-track suggestions to return (default 10).
`bpm_drift`	No	Max BPM difference pre-filter before scoring (default 12).
`min_score`	No	Drop candidates below this overall transition score (default 0).
`cross_genre`	No	Genre handling: 'auto' (default) keeps picks in a mixable genre lane so an off-genre track that only shares key/BPM sinks to the bottom; 'strict' = same genre-family only; 'allow' = genre-blind (harmonic+tempo+energy only).	auto
`seed_track_id`	Yes	The track currently playing — a catalog itunes_track_id.
`max_key_distance`	No	Max Camelot-wheel hops pre-filter before scoring (default 2).
`exclude_same_artist`	No	Drop tracks by the seed's artist (default false).

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnlyHint=true and openWorldHint=true, which align with a read-only suggestion tool. Description adds value by stating cost (3 quota units), explaining genre-awareness defaults, and detailing output format. No contradictions.

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?

Reasonably concise given the information volume. Organized with clear purpose first, then output details, genre modes, and usage context. A few sentences could be tightened (e.g., 'It is the seed's sonic neighbours re-ranked for a clean mix'), but overall economical.

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?

Given 7 parameters, full schema coverage, and existing output schema, the description sufficiently explains output format (seed, count, suggestions array with details). Mentions pairing with build_setlist for workflows. Minor gap: no handling of invalid seed_track_id or error cases, but acceptable for a suggestion tool.

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 covers 100% of parameters with descriptions. Description adds context for seed_track_id (acceptable sources) and cross_genre (behavior explanation), enhancing clarity beyond the schema's basic descriptions.

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?

Clearly states verb (return, suggest), resource (catalog tracks to play NEXT), and scope (ranked by transition score). Distinguishes from siblings like score_transition by specifying it returns suggestions based on a seed, not a pair score. Mentions output includes score, components, reason, genre.

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?

Describes when to use (given a seed track), explains cross_genre modes, and suggests pairing with build_setlist. Lacks explicit when-not-to-use alternatives like score_transition or find_compatible_keys, but the purpose implies the distinction.

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

All FreqBlog Music Metadata tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: search, feature retrieval, set building, transition scoring, etc. There is no overlap or ambiguity.

Naming Consistency5/5

All tools use consistent snake_case verb_noun pattern (e.g., find_tracks_by_key, get_audio_features, build_setlist). No style mixing.

Tool Count5/5

12 tools is well within the ideal range, covering search, features, discovery, and set building without bloat or deficiency.

Completeness4/5

Core metadata retrieval, search, harmonic mixing, and DJ set tools are all present. Minor gaps like user library management are outside the scope.

Resources

Need Help?