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 declare readOnlyHint=true and openWorldHint=true. Description adds ordering logic and that each track contains full audio features, providing transparency beyond annotations without contradiction.

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 sentences, front-loaded with the core action, no wasted words. Every sentence adds 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?

Given the tool's simplicity, good annotations, and an output schema, the description covers return values, ordering, and use cases completely. No gaps.

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 good descriptions. Description adds the ordering logic (closeness then popularity), which is not in the schema. This extra meaning justifies 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?

Description clearly states the tool finds tracks near a target BPM, specifies ordering by closeness then popularity, and lists concrete use cases. It also distinguishes from sibling by mentioning combination with find_tracks_by_key.

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 explicit use cases (DJ set planning, workout playlists, tempo-matching) and mentions an alternative (combine with find_tracks_by_key for key constraints). It does not list when not to use, but the context is clear.

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. The description adds details: accepted key formats (Camelot, Open Key, key name), ordering by popularity, and that results include full audio features. 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?

Two well-structured sentences: first states purpose, second details parameters and alternatives. No wasted words, front-loaded with key 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 output schema exists, return values need not be detailed. The description covers purpose, usage, key formats, ordering, and mentions full audio features. Directs to sibling tool for further needs. Complete for a simple 2-parameter 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 coverage is 100%, so parameters are documented. The description adds value by explaining the key formats more richly and mentioning that results are ordered by popularity, providing context beyond 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?

The description states 'Find catalog tracks in a given musical key — for harmonic mixing and key-locked playlists,' clearly identifying the verb (find), resource (tracks), and purpose (harmonic mixing). It distinguishes from siblings like find_compatible_keys.

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 when to use (find tracks by key) and when not to ('To discover which keys mix well with a given key first, use find_compatible_keys'), providing a direct 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?

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?

Beyond annotations (readOnlyHint, openWorldHint), the description discloses critical behavioral traits: how bad entries are handled, billing conditions, return structure, and special statuses like invalid_no_query and over_limit. 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?

Well-structured with front-loaded main purpose, followed by clear details in separate paragraphs. Every sentence adds value, though slightly verbose in explaining ISRC behavior, making it not perfectly 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?

Despite having an output schema (not shown), the description thoroughly describes return values: counts, per-track result array, feature object same as get_audio_features, skipped items with reasons, and billing info. Completely covers what an agent needs to understand the tool's behavior.

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 description adds significant meaning: explains the relationship between isrc and track (exact match first, fallback), optional artist for accuracy, and consequences of missing both. This enriches the schema beyond its own 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?

The description clearly states it retrieves audio features for many tracks in one call, ideal for analyzing playlists, and explicitly distinguishes from sibling get_audio_features by recommending that tool for single tracks.

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 advises when to use (batch of up to 50 tracks) and when not (single track, use get_audio_features). Details such as ISRC exact matching, no batch failure on bad entries, and instructions for handling over-limit items provide clear usage 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?

Beyond annotations (readOnlyHint, openWorldHint), the description discloses extensive behavioral traits: 'RE-RANKED by genre affinity (so a feature-close cross-genre track doesn't outrank same-genre picks)', 'score is the raw audio-feature cosine similarity... genre affinity influences the ORDER, not the score', 'the list is NOT strictly score-descending', the meaning of 'genre_relation' values, the primary-seed logic, the tuning filter behavior ('min/max are HARD filters and target is a preference'), the added 'filters' block, and the quota cost. This goes far beyond what annotations 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 dense but well-structured, with the opening sentence delivering purpose, followed by output format, genre_relation semantics, tuning mechanics, fallback behavior, and costs—each paragraph serving a distinct role. No sentence is redundant; the example is concrete and illustrative. Length is justified by the tool's complexity and the need to explain nuanced 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 9-parameter schema, output schema, and complexity, the description covers all necessary aspects: input methods (ids vs names), output shape ('Returns seeds... count... tracks'), edge cases (multi-seed label meaning), filtering vs re-ranking, and even problem diagnosis ('if the list comes back short, read that BEFORE assuming the catalogue is thin'). It is complete for an AI agent to select and invoke 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?

While the schema covers 100% of parameters descriptively, the tool description significantly enriches each one. It explains that seed_tracks are 'catalog itunes_track_ids from search_catalog or the itunes_track_id field of a get_audio_features result', that 'track' resolves to a best catalog match echoed as 'seed_query', and that min/target combine into an example ('min={"tempo": 100}, max={"tempo": 130}, target={"energy": 0.8}'). It also clarifies interactions like 'seed_tracks wins if both are given' and the cross_genre values, adding substantial meaning beyond 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?

The description opens with 'Recommended tracks for one or more seed tracks — the drop-in for Spotify's removed GET /v1/recommendations', clearly stating the verb, resource, and scope. It further differentiates itself from sibling suggest_next_track by describing the genre-affinity re-ranking behavior, making its unique purpose unmistakable.

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 clear context for when to use this tool: 'Use cross_genre=strict to return same-genre-family tracks ONLY', 'allow to disable the genre ranking', and 'NO id? Pass track (+ optional artist) instead' for name-based seeding. It also references suggest_next_track to contrast the genre_relation semantics, but it stops short of explicitly stating 'use this instead of suggest_next_track when...', so it lacks direct exclusion criteria.

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 already declare readOnlyHint=true and openWorldHint=true, which are consistent. The description adds critical behavioral details: returns lightweight stubs (not audio features), ranking by relevance, and the seedable boolean with its implications for downstream tools.

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, front-loading the core purpose, then providing usage guidance and warnings. Every sentence adds value without redundancy. It is appropriately sized for the complexity of the tool.

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 covers purpose, usage, edge cases (seedable: false), and workflow integration. The output schema exists to document return fields, so the description's focus on behavior and usage is appropriate and complete.

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?

Both parameters (q and limit) are already described in the schema with 100% coverage. The description adds value by explaining that q accepts any mix of tokens and that limit caps results, but the schema already provides the basics. The extra context about seedable is not parameter-specific.

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 it performs full-text search of the music catalog by track/artist/album tokens. It distinguishes itself from sibling tools by explicitly positioning this as the resolver for fuzzy names before calling get_audio_features.

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?

Provides explicit guidance on when to use (fuzzy/partial matches) and how to proceed (use the best match with seedable: true). Also warns against seeding with non-seedable hits and explains the alternative (get_audio_features first).

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.