FreqBlog Music Metadata

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

The description adds value beyond annotations: it reveals the tool returns data (not mutates), costs 5 quota units, and details the output structure. Annotations already declare readOnlyHint=true and openWorldHint=true; the description reinforces non-destructive behavior and adds cost and output specifics.

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

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

The description is efficient at 4-5 sentences, starting with the main action and then detailing arc, output, usage, and cost. It is front-loaded with the core purpose. Slightly dense but no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is comprehensive: covers input limits (2-100 tracks), arc options, output structure (flow_score, transitions, omitted ids), and even a usage hint (feed into DJ software). Given the tool's complexity and the presence of an output schema, the description adds ample context and covers all key aspects.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats schema info for 'arc' options and 'track_ids' meaning, but adds minimal extra context: start_track_id constraint 'must be one of track_ids'. No significant new meaning beyond schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Order a crate of 2-100 catalog tracks into a beat-matched DJ set that follows an energy arc.' It specifies the resources (catalog tracks) and the output (setlist with transitions, score, etc.). This distinguishes it from siblings like suggest_next_track or score_transition, which focus on individual aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you have a crate of tracks and want a harmonically and tempo-smooth DJ set. It does not explicitly exclude alternatives or mention when not to use it, but the context is clear and no sibling differentiation is provided. The mention of cost provides a constraint.

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

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

Given annotations (readOnlyHint=true, openWorldHint=false), the description adds context about no catalog lookup and no quota cost, which aligns with the read-only nature. It does not contradict annotations and provides additional behavioral details.

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

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

Two concise sentences that front-load the purpose and immediately convey core functionality. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema, the description is complete. It explains what the tool returns, what it does not (no catalog lookup), and how to use it in context with other tools.

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

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

Schema has 100% description coverage, but the description adds meaning by explaining the harmonic logic (same key, relative major/minor, adjacent +/-1, extended +7/-7). This goes beyond the schema's simple parameter description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns harmonically compatible keys for DJ mixing given a Camelot key, specifying the types of keys (same, relative, adjacent +/-1, and optionally +7/-7). It distinguishes from the sibling 'find_tracks_by_key' by emphasizing that this is pure music theory with no catalog lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes when to use (to get harmonic compatibility for DJ mixing) and when not to (no catalog lookup). Suggests pairing with 'find_tracks_by_key' for actual track retrieval, providing a clear alternative.

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

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

Annotations already provide readOnlyHint and openWorldHint. The description adds valuable behavior beyond that: it explains the ordering ('by closeness then by an internal catalogue ordering key (not an audience metric)') and the output richness ('Each returned track carries full audio features'). This is context an agent needs to interpret results and decide on downstream steps, so it adds meaningful transparency.

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

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

The description is two substantive sentences plus a final combination hint. The core purpose is front-loaded in the first sentence, and every subsequent clause adds useful context (ordering, use cases, audio features, key combination). There is no fluff or redundancy, and it stays compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description doesn't need to detail return fields. It covers the matching rule, ordering, use cases, and how to extend with find_tracks_by_key. The safety profile is handled by annotations (readOnlyHint). Nothing an agent needs to invoke and interpret the tool correctly is missing.

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

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

Schema coverage is 100%, so all three parameters (bpm, limit, tolerance) are already documented with descriptions. The description reiterates the tolerance concept ('within +/- tolerance of bpm') and ties it to ordering, but it doesn't add new syntax or format details. The baseline for high schema coverage is 3, and the description adds only marginal value, so 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Find catalog tracks near a target tempo.' It clearly states the matching rule (BPM within +/- tolerance) and the ordering, and it explicitly references the sibling tool find_tracks_by_key for key-based filtering, which distinguishes it from that alternative. The purpose is unambiguous and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear usage context: 'useful for DJ set planning, workout playlists, or tempo-matching.' It also gives an explicit alternative condition: 'To also constrain by musical key, combine with find_tracks_by_key.' It lacks a direct 'when not to use' for other siblings like search_catalog or get_recommendations, but the combination hint and the tempo-specific focus give sufficient guidance.

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

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

The annotations already provide readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds valuable context: it reveals that the result ordering is by an internal catalogue key, explicitly stating it is NOT an audience metric (e.g., popularity). It also mentions that each result includes full audio features, which sets expectations about the response richness. This goes beyond what annotations alone would convey.

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

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

The description is three sentences, compact and comprehensive. The first sentence immediately states the purpose and use case, making it front-loaded. The second sentence details the key parameter format and return ordering behavior, and the third sentence provides a clear alternative. No fluff, every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given this is a read-only query tool with only 2 parameters, the description covers everything: the filtering capability, the parameter formats, the output characteristics (full audio features, ordering), and the workflow with siblings. The output schema exists, so return structure is presumably documented elsewhere. The description is fully sufficient for an agent to call this correctly.

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

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

Schema description coverage is 100%, and the 'key' parameter description in the schema already lists the accepted formats (Camelot, Open Key, key name). The description reaffirms these formats and adds that it accepts formats like '8A', '1m', 'A-Minor', giving concrete examples. For the 'limit' parameter, the default and max are clear from schema. The minimal additional info beyond schema earns a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (find catalog tracks), the resource (tracks), and the specific filter (musical key). It explicitly mentions the use cases (harmonic mixing, key-locked playlists) and differentiates from sibling find_tracks_by_bpm (which filters by BPM not key) and find_compatible_keys (which finds key compatibility, not tracks). This is a specific and unambiguous purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool (when you need tracks in a specific key) and when to use find_compatible_keys first (to discover which keys mix well). This clear routing to the sibling reduces ambiguity and provides practical workflow guidance, which is exemplary.

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

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

Beyond the readOnly/openWorld annotations, the description discloses substantial behavioral traits: identifier precedence, null fields for fallback catalogs, on-demand ingest that may hold the request, a queued response fallback after ~15s, and a terminal 7-day not-found verdict. This gives the agent accurate expectations about latency and retry behavior.

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

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

The description is longer than average, but every sentence earns its place: purpose is front-loaded, identifier guidance is bulleted, and edge-case behaviors are clearly separated. The detail is justified by the tool's complex resolution and ingest behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema is provided and annotations cover read-only/open-world behavior, the description completes the picture: return shape, null handling, fallback catalogs, ingest latency, poll timing, and definitive not-found semantics. Nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains the full precedence order (track > isrc > mbid > spotify_id), advises sending several identifiers instead of choosing, and gives realistic examples. It largely reinforces rather than replaces the schema, so slightly above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Get audio features for ONE track', followed by a concrete list of returned features. It clearly distinguishes this single-track tool from the batch sibling and from search_catalog.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on identifier selection, precedence, and tells users to 'call search_catalog first' when they only have a fuzzy name. However, it never explicitly routes multi-track requests to the get_audio_features_batch sibling; it only implies that through 'ONE track'.

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

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

Even with readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: 'One bad entry never fails the batch,' items over the cap return `found: false` and `backfill_status: "over_limit"`, missing both identifiers yields `"invalid_no_query"`, and the billing rules ('An item is billed only when it returns features or queues an on-demand ingest...') are disclosed. This fully informs the agent of success/failure and cost behavior without contradicting 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.

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

The description is longer than many, but every paragraph earns its place: purpose and scope, failure modes, return structure, billing, and the pointer to the single-track sibling. It is front-loaded with the primary use case and the 'up to 50' constraint, then organizes edge cases logically. A slight condensation of the billing paragraph could help, but the complexity justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a tool with this complexity: it covers the parameter structure, batch limit, invalid-entry behavior, response contents (`counts`, `results`, `skipped`), billing implications, and differentiation from get_audio_features. The output schema exists, so detailed return formatting is not required, but the description still summarizes it sufficiently. No critical information for correct invocation is missing.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema: it clarifies the batch processing limit (50 of up to 200 accepted), explains the matching precedence ('ISRC first, name as the fallback'), and defines what `invalid_no_query` means for the `tracks` array. It also explains how the `skipped` field relates to parameter usage, which the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('Get audio features for MANY tracks in one call') and clearly differentiates itself from its sibling get_audio_features by stating 'For a single track, use get_audio_features.' It also states the ideal use case ('analysing a whole playlist at once'), leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly gives when-to-use guidance: batch playlist analysis vs. single-track lookup, and names the alternative tool. It also provides operational instructions for handling the 50-per-call cap ('split a long list into calls of <=50 and resubmit any skipped rows') and explains when to prefer ISRC over name matching. This goes far beyond implied usage.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=true; the description carries the full behavioral burden and excels. It discloses that the list is NOT strictly score-descending, explains the multi-seed 'cross' label caveat, the primary-seed reference semantics, the filters block when tuning, the 400 error on popularity, and the 2-quota-unit cost. No contradiction with annotations.

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

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

Long but densely packed; every sentence earns its place given the 9-parameter complexity and subtle ranking semantics. It is front-loaded with purpose and alternatives. Could be tightened slightly (e.g., trimming the tuning example), but the density justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema covers return values, yet the description still details response structure (seeds/count/tracks), edge cases (skipped seeds, short lists via filters block), multi-seed semantics, error behavior (400 on popularity), quota cost, and how to source seed ids from sibling tools search_catalog and get_audio_features. Nothing an agent needs is missing.

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

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

Schema coverage is 100% with already-rich parameter descriptions, so the baseline is 3. The description adds genuine value on top: the hard-filter (min/max) vs preference (target) distinction, the seed_tracks-wins-if-both-given interaction, the seed_query echo, and the popularity retirement warning — all beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource ('Recommended tracks for one or more seed tracks') and explicitly positions itself as the drop-in for Spotify's removed GET /v1/recommendations. It distinguishes its unique re-ranking-by-genre-affinity behavior and names suggest_next_track as a related sibling, making its scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance: how to choose between seed_tracks vs track/artist, when to set cross_genre to strict/allow, and explicitly references suggest_next_track as the cross_genre mirror. Includes concrete tuning examples and warns about the retired popularity parameter, so an agent knows exactly when and how to invoke it.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds substantial behavioral details: no exact graph exists, derivation via track vectors, scoring with same-genre lift and cross-genre penalty, and cost of 2 quota units. 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.

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

The description is well-structured with purpose first, then algorithm, return format, usage hints, and cost. It is somewhat lengthy but every sentence adds value. Slightly verbose for very concise standards, but still earns a high score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the algorithmic complexity and the presence of an output schema, the description fully covers purpose, return structure, invocation patterns (e.g., passing sample_track_id to other tools), and cost. No gaps identified for an agent to use the tool effectively.

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

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

Schema coverage is 100% and the schema already describes both parameters (artist and limit) adequately. The description does not add new meaning or constraints beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns artists related to a seed artist, explicitly comparing it to Spotify's removed endpoint. It distinguishes itself from siblings by detailing its derived algorithm and naming specific use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description positions the tool as a drop-in replacement for Spotify's related-artists endpoint, giving clear when-to-use context. It lacks explicit exclusions or comparisons to other sibling tools like get_recommendations, but the context is strong enough for an agent to decide.

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

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

Description details exact return structure (overall score, per-component scores, detail block with key/BPM/energy info, human reason) and explains mixing components (Camelot compatibility, BPM proximity, energy smoothness). Aligns with readOnlyHint annotation.

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

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

Description is efficient with 4 sentences, front-loaded with purpose, and structured logically. Minor redundancy but overall concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all aspects: purpose, input sources, return fields, cost, and complements annotations (readOnlyHint, openWorldHint). No gaps given output schema existence.

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

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

Schema covers both required parameters with descriptions. Description reinforces they are catalog itunes_track_ids and provides an example, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it scores DJ transition compatibility between two tracks (0-100) and distinguishes from sibling tools like get_audio_features (individual track features) and suggest_next_track (track suggestion).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides context for when to use (pairwise scoring not available elsewhere) and where to obtain track IDs (search_catalog or get_audio_features). Lacks explicit when-not-to-use, but sibling list compensates.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds crucial behavioral details: returns lightweight stubs ranked by relevance, explains chart_peak semantics (100 = number-one, null = UNKNOWN not unpopular, Billboard year-end only), and explains the seedable boolean with its implications (404, queue analysis). This is rich context beyond annotations.

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

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

The description is long but every section serves a purpose: purpose, usage, result interpretation, and seeding rules. It is front-loaded with the main purpose and then layers detail logically. No filler; each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (chart_peak interpretation, seedable flag, 404 behavior, routing to other tools), the description covers all necessary behavioral aspects for correct invocation. The output schema exists but the description adds the semantic nuances that schema cannot convey. Nothing an agent needs is missing.

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

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

Schema coverage is 100% with both q and limit having descriptions. The description doesn't add new input semantics beyond schema, but it does clarify usage of q in context (any mix of tokens). Since schema already covers parameters, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('Full-text search the catalog by any mix of track / artist / album tokens') and immediately differentiates from siblings by stating it resolves fuzzy names before calling get_audio_features, and by noting it returns stubs not audio features. This gives an agent a clear, distinct purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it ('BEFORE calling get_audio_features') and provides detailed follow-up instructions: take best match and pass to get_audio_features or reuse itunes_track_id as seed, plus guidance on seedable flag and 404 handling. This is far beyond typical guidance and routes the agent to the correct next steps.

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

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.

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.

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.

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.

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.

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.

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

Annotations readOnlyHint=true and openWorldHint=true are corroborated and extended: the description adds quota cost, resolution precedence, 'misses rather than guessing' on ambiguous Spotify-ID title matches, and the provenance/confidence semantics of each tag. It explains coverage differences between Essentia and AcousticBrainz data without contradicting annotations.

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

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

The description is long, but every section earns its place: purpose, differentiation, provenance semantics, identifier guidance, return shape, and alternatives. It is front-loaded with the core action and uses compact formatting for the confidence/provenance taxonomy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with an output schema, the description is complete: it states required input combinations, result shape, cost, coverage caveats, and how to get alternative outputs. An agent has everything needed to select identifiers and interpret tags.

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

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

Schema coverage is already 100%, and the description adds meaning beyond it: the precedence hierarchy track > isrc > track_id > mbid > spotify_id, the role of artist as an accuracy booster, the 7.5M+ AcousticBrainz coverage via MBID/ISRC, and the ambiguity behavior of spotify_id. This lets an agent choose identifiers correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a precise verb and resource: 'Get a compact, HONESTLY-LABELLED tag list for a track' and enumerates the exact tag categories. It distinguishes itself from get_audio_features ('full numeric feature set') and 'a discovery tool', so an agent can tell it apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance closes the description: 'For the full numeric feature set use get_audio_features; for nearest tracks use a discovery tool.' It also states the required input condition (AT LEAST ONE identifier), the precedence order, and when MBID/ISRC are advantageous.

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