FreqBlog Music Metadata

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavioral context beyond them: the 5 quota-unit cost, and the 'omitted' behavior explaining that ids not in the catalog or lacking audio features are silently dropped rather than erroring. It does not cover auth or rate limits, but the quota and partial-failure disclosure is substantive.

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?

Front-loaded with the core action and scope in the first sentence, followed by the arc vocabulary, then behavior. It is slightly padded by enumerating return fields (arc, count, flow_score, tracks, transitions, omitted) that the output schema already defines, but the list is compact and each item is short.

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 read-only tool with an output schema, the description is close to complete: it gives purpose, arc semantics, quota cost, and partial-result behavior. The only redundancy is restating return fields already in the output schema, and the only gap is that start_track_id's fixed-opener role lives solely in the schema.

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. The description adds genuine meaning for `arc` by explaining the shape of each curve ('peak_time builds to a peak then eases'), which the schema's flat enum list does not convey. It does not mention start_track_id at all, but that parameter is fully documented in the 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?

States a specific verb+resource+scope: 'Order a crate of 2-100 catalog tracks into a beat-matched DJ set that follows an energy arc.' This is clearly distinguishable from siblings like suggest_next_track or score_transition, which operate per-step rather than over a whole crate.

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?

Usage is implied by the batch nature of the tool ('order a crate'), and the export hint shows the downstream workflow, but there is no explicit when-to-use-this vs. suggest_next_track/score_transition guidance or any exclusion. The agent must infer that this is the whole-set counterpart to the per-transition tools.

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?

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond by disclosing that values are on FreqBlog's own scale (not Spotify's), that certain fields are null for catalogue tracks, that Spotify IDs are resolved per request via the embed page without storage, and that a not-found verdict is terminal for ~7 days with an ingest/queue fallback (~15s re-poll). This is unusually rich behavioral context.

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?

Front-loaded with the core purpose and field list, then organized into identifier bullets and caveats. Every sentence carries information, but the total length is substantial and the parenthetical detail (citations, resolution mechanics) makes it denser than strictly needed.

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 exists, so return values need not be spelled out, yet the description still notes that feature fields may be null and explains scale caveats. Combined with identifier rules and ingest/retry behavior, nothing an agent needs to call this 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% (baseline 3), but the description adds real value beyond the schema: the precedence order among the four identifiers, the rule that the rest are ignored, the semantics of the spotify_id resolution and its ambiguity behavior, and format examples. Only slightly short of a 5 since most field-level detail still lives in the 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?

States a specific verb and resource ('Get audio features for ONE track'), enumerates the returned fields (BPM, key, energy, danceability, etc.), and implicitly distinguishes itself from the sibling get_audio_features_batch by emphasizing ONE track. An agent can tell exactly what this returns without opening the schema.

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 says 'Provide AT LEAST ONE identifier', gives the resolution precedence (track > isrc > mbid > spotify_id), advises sending all known identifiers, and routes fuzzy/partial names to search_catalog first. Clear when-to-use and which alternative to pick.

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 supply readOnlyHint and openWorldHint; the description carries the rest and does so well — 2 quota units cost, retired tunables returning 400, server-side dropping in strict mode, null values for liveness/speechiness/instrumentalness, and the filters/dropped_by/limit_reached diagnostic. It also warns that the list is NOT strictly score-descending, which is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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?

Purpose is front-loaded and each paragraph has a distinct job (returns, seeding, tuning). It is long for a tool description and repeats some schema-level detail, notably re-explaining the three cross_genre modes that the schema already documents, but almost no sentence is pure filler given the tool's complexity.

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 9-parameter, zero-required, tuning-heavy tool with only two terse annotations, the description covers seeding, ranking semantics, hard vs soft filters, deprecated parameters, quota cost, and short-result diagnostics. An output schema exists, yet the return explanation is still useful for interpreting genre_relation relative to the primary seed.

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 material meaning beyond it: the retired attributes list (popularity/liveness/speechiness/instrumentalness) that the schema still exposes as valid keys, the seed_tracks-over-track precedence, the primary-seed definition for genre_relation, and the FreqBlog-vs-Spotify value-scale caveat for tuning thresholds.

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?

Opens with a specific verb+resource ('Recommended tracks for one or more seed tracks') and immediately positions itself as the drop-in replacement for Spotify's removed endpoint, which tells an agent exactly what it produces. It also names the sibling it relates to (suggest_next_track for single-seed semantics) and the tools that supply its inputs (search_catalog, get_audio_features), so it is distinguishable without opening any schema.

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 rules: use seed_tracks (catalog itunes_track_ids) or fall back to track(+artist) when no id exists, with seed_tracks winning if both are given. It gives when-to-use for each cross_genre mode (strict vs allow vs auto), explains when to read the filters block, and contrasts min/max (hard filters) with target (preference).

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 only cover readOnlyHint, but the description adds substantial behavioral detail beyond them: quota cost (1 unit, charged only on a served result), no audio upload/compute, the four confidence/provenance classes, the instrumentality null gap, and the different coverage of Essentia vs AcousticBrainz depending on identifier supplied. This is unusually rich disclosure for a read tool.

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?

Purpose, cost model and differentiator are front-loaded, and the confidence/provenance bullets earn their space. It is long and includes a little redundancy (the compute/upload caveat and the identifier rules appear twice across description and schema), but there is no padding sentence that could be dropped without losing information.

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, return values need not be described, yet the description still summarizes the shape and explains the semantics of value/confidence/provenance that the schema alone would not convey. For a 6-param read tool with open-world resolution behavior, nothing essential 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 description coverage is 100%, so the baseline is 3, but the description adds real value by tying identifier choice to outcome: precedence order (track > isrc > track_id > mbid > spotify_id), the 'send them all, you never have to pick' affordance, and the fact that MBID/ISRC unlock 7.5M+ AcousticBrainz recordings. It largely reinforces schema text but the coverage consequence is new meaning.

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 opening sentence gives a specific verb and resource ('Get a compact, HONESTLY-LABELLED tag list for a track') and immediately enumerates the returned tag types. It explicitly separates itself from siblings get_audio_features ('full numeric feature set') and the discovery tools, so an agent can pick it 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.

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

It routes clearly: use get_audio_features for the full feature set, a discovery tool for nearest tracks, and this tool for labelled tags. It also explains identifier precedence so the caller doesn't have to choose. It stops short of explicit when-not-to-use conditions or prerequisites (e.g., when tags will be empty), but the alternative-naming is strong.

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