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 on-demand ingest holding behavior, queued fallback with ~15s re-poll, terminal not-found caching, spotify_id embed-page resolution that misses rather than guesses, and per-field null behavior. It also documents that values are on non-Spotify scales, which prevents downstream misuse.

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 identifiers before the longer caveat paragraphs, and the bulleted identifier list is scannable. It is on the long side and restates some spotify_id resolution detail already present in the schema, but nearly every sentence carries operational value.

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 need not explain return shape, and it correctly focuses on the things structured fields cannot convey: value scales, null semantics, ingest/polling behavior, and terminal error caching. Nothing an agent needs to call it 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: the precedence ordering, the rationale for sending multiple identifiers, and the caveat that spotify_id is a lossy fallback preferred against track/isrc. It also explains the artist dependency for short titles.

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+resource ('Get audio features for ONE track') and enumerates the returned fields, which immediately separates it from the sibling get_audio_features_batch. The 'drop-in replacement for Spotify's deprecated /audio-features endpoint' framing further anchors the 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 the identifier requirement ('AT LEAST ONE'), the resolution precedence (track > isrc > mbid > spotify_id), and the advice to send all identifiers rather than choose. It also routes fuzzy/partial names to search_catalog first and warns the not-found verdict is terminal for ~7 days.

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, so the safety profile is covered but nothing operational. The description adds substantial behavior: cap handling (over_limit), invalid_no_query, partial-failure tolerance ('One bad entry never fails the batch'), billing rules (no match is free, queued+collected costs one unit), and the backfill_status state machine including which states are terminal.

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 purpose and the routing alternative, then operationally important failure and billing details. It is long and a few clauses restate points already made in the schema (ISRC-first precedence appears twice), so it stops short of perfectly tight, but nearly every sentence carries decision-relevant 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?

Given an output schema exists, the description still supplies the return semantics an agent needs to act (counts, per-item result/isrc echo, null-when-not-found, retry vs terminal backfill_status). Combined with annotations and a documented schema, nothing needed to invoke or interpret results 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 semantics the schema cannot express: the <=50 processed vs 200-accepted distinction that explains why an in-schema-valid array still yields skipped rows, and the precedence rule (ISRC matched exactly first, name as fallback) that governs multi-field interaction.

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 with scope: 'Get audio features for MANY tracks in one call (up to 50 processed)'. It explicitly distinguishes itself from the single-track sibling by naming get_audio_features at the end, so an agent can route without opening either 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?

Gives explicit when-to-use ('ideal for analysing a whole playlist at once') and when-not ('For a single track, use get_audio_features'). It also gives per-item selection guidance: prefer `isrc` for CJK/K-pop/niche tracks whose fuzzy name match misses, or supply both with ISRC first and name as fallback.

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 adds materially more: quota cost (2 units), server-side dropping in strict mode, the fact that ordering is not score-descending, 400 outcomes for retired tunables, value-scale provenance (own scales vs AcousticBrainz vs Spotify-tuned), and the filters/dropped_by/limit_reached diagnostic block. That is far beyond what annotations convey and directly shapes how an agent interprets a short list.

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 and organized under implicit headings (seeding, return shape, TUNING), with no filler sentences. It is long, and the multi-seed genre_relation paragraph is dense enough to slow reading, though the ambiguity it resolves (a 'cross' label not implying demotion on multi-seed calls) is genuinely non-obvious. Slightly overlength for its purpose, but nearly 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?

For a 9-parameter tool with zero required params, an output schema, and a non-obvious ranking algorithm, this covers what an agent needs: seeding fallbacks, genre-mode behavior, filter semantics, cost, error cases, and how to read the response when results are short. Nothing material is left to inference.

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%, but the description still adds meaning the schema cannot: min/max are HARD filters that also drop unanalysed tracks while target is a non-removing preference, the retired attributes and why (popularity measured catalogue entry, others null for catalogue tracks), and the instruction to derive thresholds from FreqBlog's scales rather than Spotify's, with a concrete min/max/target example.

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 and scope ('Recommended tracks for one or more seed tracks'), then immediately positions itself against the removed Spotify endpoint and against siblings like suggest_next_track and search_catalog, which are named as the source of seed ids. An agent can distinguish this from build_setlist, suggest_next_track or find_tracks_by_bpm 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?

Explicitly states the two seeding routes (seed_tracks ids vs track(+artist) name resolution), the precedence rule when both are given, the three cross_genre modes with when to pick each, and where the ids come from (search_catalog, get_audio_features). It also names the exclusion condition (retired tunables -> 400) and the sibling whose genre semantics it mirrors (suggest_next_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?

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the semantics of chart_peak (1-100, null = unknown, not popularity, and the exact source charts with date ranges), the lightweight stub return shape, the meaning of the `seedable` flag, the failure mode (seeding a non-seedable id returns 404), and the recovery path (run get_audio_features first, then retry). That is unusually rich operational 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-loads purpose, then usage, then edge cases, so an agent gets the essentials in the first two sentences. It is on the long side and the chart_peak paragraph, while useful, is somewhat tangential to selecting/calling the tool and could be trimmed.

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 search tool with an output schema, an open-world flag, and only two params, this covers everything an agent needs: query intent, downstream routing, the seedable precondition, and the 404 recovery loop. Return-value detail is extra given the output schema but not redundant enough to penalize.

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 both parameters are already documented there (q as 'artist / track / album tokens', limit as max results). The description echoes the q semantics without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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?

Starts with a specific verb+resource: 'Full-text search the catalog by any mix of track / artist / album tokens.' It immediately distinguishes itself from retrieval siblings (get_audio_features, find_tracks_by_bpm, find_tracks_by_key) by declaring that it returns ranked name-matches, not audio data.

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 frames when to use it ('resolve a fuzzy, partial, or misspelled name') and sequences it in a workflow ('BEFORE calling get_audio_features'), then repeats the routing at the end ('pass them to get_audio_features, or reuse its itunes_track_id as a track_id seed'). When-not guidance is also given via the seedable constraint, which warns against seeding with unanalysed tracks.

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 and openWorldHint; the description adds substantial behavior beyond them: cost model ('same 1 quota unit, charged only on a served result'), no audio upload/no extra compute, and a full taxonomy of tag confidence/provenance semantics (measured vs derived vs model-estimated vs catalog-genre) plus which sources are reached per identifier type (7.5M+ AcousticBrainz recordings only when MBID/ISRC is supplied). This is well beyond annotation coverage.

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, then structured into the confidence/provenance bullets and identifier guidance, so the important material comes first. It is dense and leans on ALL-CAPS emphasis and a long single flowing paragraph in places, which costs a little readability, but nearly every sentence carries information an agent needs.

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, output-schema-backed lookup tool, the description covers the gaps that matter: cost/quota, confidence semantics, identifier precedence, ambiguous-spotify_id failure mode, and coverage limits of each identifier path. Nothing an agent needs in order to call it correctly and interpret the labels 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. The description consolidates the resolution precedence chain and the 'send them all, we ignore the rest' behavior in one place, and flags that `artist` is only meaningful with `track`. This adds usable invocation guidance, though much of the precedence detail is already duplicated in the schema descriptions, keeping it short of a 5.

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 a compact, honestly-labelled tag list for a track') and enumerates exactly which tags come back (energy/danceability/valence/acousticness/instrumentalness + mood + genre). It explicitly positions itself against siblings: 'It is a tag-shaped projection of the same open-data analysis get_audio_features returns' and names get_audio_features and a discovery tool as the alternatives. An agent can distinguish it from get_audio_features without opening either 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?

Gives explicit routing: 'For the full numeric feature set use get_audio_features; for nearest tracks use a discovery tool.' It also spells out the identifier strategy with precedence (track > isrc > track_id > mbid > spotify_id) and tells the agent to send several rather than choose. Both when-to-use and when-to-use-something-else are covered.

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