Server Quality Checklist

Tool Scores

• get_artworkA
  4.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It describes the return structure but does not disclose edge-case behaviors such as handling of missing artwork or invalid IDs, which limits transparency.

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

  Conciseness5/5

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

  The description is concise and well-structured with Args and Returns sections. Every sentence provides value, with no redundancy or fluff.

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

  Completeness4/5

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

  With no output schema, the Returns section adequately describes the response format. However, it omits potential error conditions or empty results, leaving a small but acceptable gap for a simple tool.

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

  Parameters5/5

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

  The Args section explains that mbid is a 'MusicBrainz release-group ID' and refers to 'search_release', adding meaningful context beyond the bare schema. This fully compensates for the 0% schema description coverage.

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

  Purpose5/5

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

  The description clearly states a specific action: 'Get cover art for a release group from the Cover Art Archive.' This distinctly separates it from sibling tools like get_credits or get_editions by focusing on artwork retrieval.

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

  Usage Guidelines4/5

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

  It provides clear context by specifying that mbid comes from 'search_release', indicating a prerequisite workflow step. While not explicitly excluding alternatives, the context is sufficient for an agent to understand when to use this tool.

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

• refresh_box_sets_cacheA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the network fetch, caching side effect, filtering rule, required DISCOGS_TOKEN, and return summary. It does not explain overwrite/destructive behavior or rate limits, but it covers the key behavioral traits for using the tool safely.

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

  Conciseness5/5

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

  The description is well-structured into purpose, filtering/exclusion/token note, and return summary. Every sentence adds useful information with no fluff or repetition, and the key purpose is front-loaded.

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

  Completeness4/5

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

  The description covers the tool's purpose, filtering, exclusion, auth requirement, and return output despite no output schema. It falls short only in not explaining the force parameter, which is a meaningful gap for correct invocation.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not compensate. It mentions the artist context but never explains the force parameter or the roles of artist_mbid/discogs_artist_id beyond what the schema names imply. 'force' is left completely ambiguous.

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

  Purpose5/5

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

  The description states a specific action: fetch King Crimson's compilations/box sets from Discogs and cache their tracklists for use by song_box_sets. It clearly distinguishes from siblings like song_live_releases and refresh_live_releases_cache by scoping to Main-role compilations/box sets.

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

  Usage Guidelines5/5

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

  It explicitly says this refresh supports song_box_sets lookups and excludes single-show live downloads, which are covered by song_live_releases. This provides both a clear when-to-use and an explicit alternative, making the usage context strong.

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

• get_editionsA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does well: it discloses the resolution strategy, requires DISCOGS_TOKEN, and describes the returned fields and match_method. It stops short of error handling or rate limits, but provides solid behavioral context beyond a simple list.

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

  Conciseness5/5

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

  The description is well-organized with clear sections for intro, resolution logic, args, and returns. It is succinct without fluff; every sentence adds value and is front-loaded with the primary purpose.

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

  Completeness5/5

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

  For a two-parameter tool with moderate complexity, the description covers the resolution algorithm, required token, input parameters, and return structure. It is complete enough for an agent to invoke correctly, despite lacking an output schema.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description includes an Args section explaining mbid as a MusicBrainz release-group ID from search_release and max_versions as a range (1-50). This adds essential semantics beyond the bare schema, making the parameters clear.

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

  Purpose5/5

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

  The description clearly states the tool lists physical editions/pressings of an album via Discogs, using a specific verb ('List') and resource. It distinguishes from siblings by detailing the Discogs master resolution process, making its purpose distinct from other album-related tools.

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

  Usage Guidelines3/5

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

  The description explains that the mbid comes from search_release and describes the resolution logic (preferring a Discogs relation, falling back to search). However, it does not explicitly contrast with sibling tools like get_incarnations or song_box_sets, leaving when-to-use vs alternatives implied rather than stated.

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

• get_creditsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of disclosing behavior. It explains that per-track credits are 'resolved from the recording level in MusicBrainz,' includes a 'deduplicated album roster,' and describes the selection logic when release_mbid is omitted. This goes beyond a generic 'get' and gives meaningful insight into underlying processes.

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

  Conciseness4/5

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

  The description is efficiently structured with separate Args and Returns sections, front-loading the primary purpose. It contains no redundant phrasing, though it is longer than necessary for a simple getter. The extra detail is justified by the need to explain resolution logic and parameters.

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

  Completeness5/5

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

  The description is self-contained: it explains the main purpose, parameter origins and defaults, and lists the exact keys in the returned dict. Since there is no output schema and no annotations, the description carries the full burden and fulfills it, making the tool's behavior and inputs clear enough for an agent to invoke correctly.

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

  Parameters5/5

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

  The input schema has no descriptions (0% coverage), so the description fully compensates by explaining mbid as 'MusicBrainz release-group ID (from search_release)' and release_mbid as an optional specific release with a clear fallback behavior. This provides complete semantic meaning beyond the raw type information.

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

  Purpose5/5

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

  The description starts with a specific verb and resource: 'Get performer and production credits for an album (release group).' It clearly distinguishes the tool from siblings like search_release, get_artwork, and get_live_history by focusing on credit resolution from MusicBrainz recording levels.

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

  Usage Guidelines4/5

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

  The Args section states that mbid comes from search_release, providing a clear use case and workflow context. It also explains the optional release_mbid and the fallback to a representative official release, giving practical guidance. It does not explicitly list when not to use the tool, but the guidance is sufficient.

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

• get_live_historyA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It states the required SETLISTFM_API_KEY, describes the return format as a dict with a setlists list, and notes that the limit parameter maps to a single API page. It doesn't mention rate limits or explicitly confirm read-only behavior, but the 'Search' verb implies a safe operation.

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

  Conciseness5/5

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

  The description is well-structured and appropriately sized: a brief summary, a motivational use case, an API key note, a clear Args list, and a Returns section. Every sentence adds value, and the format is front-loaded with the main purpose.

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

  Completeness5/5

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

  Despite lacking an output schema and annotations, the description covers all essential aspects: the return format, parameter semantics, and a prerequisite API key. The inclusion of the setlist structure (date, venue, city, country, songs) makes it fully self-contained for a search tool.

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

  Parameters5/5

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

  Since the schema has 0% description coverage, the description fully compensates by explaining each parameter: query (optional venue/city keyword), artist (defaults to King Crimson), year (optional filter), and limit (max setlists, 1-20, one API page). This is comprehensive and adds significant meaning beyond the bare schema.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Search live performance history / setlists via setlist.fm.' This uses a specific verb and resource, and the context about King Crimson differentiates it from sibling tools like song_performance_history, which target individual song histories.

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

  Usage Guidelines4/5

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

  The description provides clear context: 'Useful for King Crimson given their extensive touring' and notes the API key requirement. However, it does not explicitly name alternative tools or state when not to use this tool, stopping short of full alternative differentiation.

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

• search_releaseA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It discloses the search is read-only, explains the concept of release groups, and clearly describes the return structure. It does not mention rate limits, result ordering, or error behavior, but for a search tool this level of transparency is strong.

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

  Conciseness5/5

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

  The description is well-structured: a brief opening that defines the resource, followed by Args and Returns sections. Every sentence adds value—the release group definition, the workflow hint, and the parameter/return details. It is neither overly verbose nor under-specified.

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

  Completeness5/5

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

  With no output schema, the description fully explains the return value format. It covers the search concept, all parameters, and how to use the results. Given the tool's simplicity and the richness of the sibling context, the description is complete enough for an agent to select and invoke it correctly.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must compensate. The 'Args' section thoroughly explains each parameter: query (free-text title with examples), artist (restrict to this artist, with default), and limit (max results 1-25). This adds substantive meaning beyond the schema's basic type/default definitions.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: searching MusicBrainz for release groups (albums) matching a query. It uses a specific verb ('search'), identifies the resource ('release groups'), and distinguishes itself from sibling tools (which are all get_* operations) by being the sole search tool and by instructing to use the returned mbid with other tools.

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

  Usage Guidelines4/5

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

  The description implies when to use the tool: 'Use the returned mbid with the other tools' establishes a discovery-first workflow, and the release group granularity is explicitly positioned for browsing a discography. It does not explicitly exclude alternatives when an mbid is already known, but the context makes this clear.

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

• song_performance_historyA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description discloses that the tool reads from a local cache and depends on freshness (refresh prerequisite). It also describes the return structure in detail. It implies a read-only operation but never explicitly states 'does not modify data', and it does not mention edge cases like cache emptiness. Still, it is reasonably transparent for a cache-backed lookup.

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

  Conciseness5/5

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

  The description is structured into a brief summary, an Args block, and a Returns block. It front-loads the purpose, includes necessary parameter details, and avoids redundancy. Each sentence adds value, and the format is easy to parse.

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

  Completeness5/5

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

  Given the tool's moderate complexity (3 params, no output schema, no annotations), the description is complete. It covers the tool's purpose, data source, prerequisite, all parameters, and the return dictionary contents (cache_info, performance_count, first/last, by_year, by_tour, list). This is everything an agent needs to invoke it correctly and interpret results.

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

  Parameters5/5

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

  The schema has no parameter descriptions (0% coverage), but the description fully compensates: it explains 'song' with examples, notes the default for 'artist_mbid' (King Crimson), and defines the two allowed values for 'match' (exact vs contains). This gives the agent complete information to construct valid calls.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Trace how often and when a song was played live.' It further clarifies the data source (local setlist cache) and the aggregation by year and tour. This clearly distinguishes it from sibling tools like get_live_history which likely lack this song-specific aggregated view.

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

  Usage Guidelines4/5

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

  The description states a clear prerequisite: 'Run refresh_setlist_cache first.' It also specifies the context (local setlist cache) and gives an idea of when results will be useful. However, it does not explicitly compare to alternatives (e.g., get_live_history or song_live_releases), so it falls short of a 5.

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

• get_incarnationsA
  4.7/5.0
  Behavior4/5

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

  No annotations are present, so the description carries the burden. It discloses the return shape ('A dict with an `incarnations` list') and the fields included, but does not mention ordering, completeness, or error behavior. For a simple list tool, this is adequate but not exhaustive.

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

  Conciseness5/5

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

  The description is three short paragraphs with no redundant information. Each section (overview, usage, returns) serves a distinct purpose and every sentence earns its place.

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

  Completeness5/5

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

  Given 0 params and no output schema, the description provides enough detail about the output structure and the tool's role relative to a sibling tool. It could include an example but is not necessary for a straightforward list tool; the description is complete for its complexity.

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

  Parameters4/5

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

  There are zero parameters, so the schema and description have nothing to clarify. Baseline of 4 applies as there is no parameter information to miss.

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

  Purpose5/5

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

  The description opens with a clear verb 'List' and specifies the resource 'King Crimson's line-up eras (incarnations)', followed by an enumeration of returned fields. It also distinguishes itself from the sibling `song_performance_history` by positioning itself as the reference for incarnation IDs/names.

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

  Usage Guidelines5/5

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

  It explicitly states 'Use this to look up who played in a given era' and references the sibling `song_performance_history` to note that its per-era counts are keyed by the same IDs/names, making this tool the lookup reference. This gives clear when-to-use guidance and points to an alternative for related data.

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

• refresh_live_releases_cacheA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses that the tool makes network requests to MusicBrainz, adheres to the User-Agent policy via MCP_CONTACT, caches results locally, can force re-fetching, and returns a summary with totals and cache path. It also mentions retry behavior for transient errors.

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

  Conciseness5/5

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

  The description is well-structured: a concise summary, usage context, requirements, parameter list, and return description. Every sentence adds value without verbosity.

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

  Completeness5/5

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

  Given the lack of an output schema, the description includes a Returns section detailing the summary contents. It covers purpose, prerequisites, parameters, and behavior, making it self-contained for an AI agent to decide when and how to call this tool.

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

  Parameters5/5

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

  The schema provides only types and defaults with zero descriptions. The description's Args section explains each parameter: artist_mbid (defaults to King Crimson), max_pages (safety cap), max_retries (retry on transient errors), and force (re-fetch even if cache exists). This fully compensates for the lack of schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool fetches King Crimson's official live releases from MusicBrainz and caches them locally, parsing recording dates. This distinguishes it from sibling cache tools (refresh_setlist_cache, refresh_box_sets_cache) by focusing on live releases and mentioning its role in song_live_releases.

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

  Usage Guidelines4/5

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

  The description says it is used by song_live_releases to map songs to live albums, and notes that the live catalog is fixed so it rarely needs re-running. This provides clear context for when to invoke it, though it does not explicitly discuss alternatives or exclusions.

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

• refresh_setlist_cacheA
  4.8/5.0
  Behavior5/5

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

  There are no annotations, so the description carries the full burden. It discloses important behaviors: retries with backoff against setlist.fm failures, records failed pages instead of aborting, requires SETLISTFM_API_KEY, caches locally as JSON, and returns a summary dict rather than the setlists themselves. These details go well beyond the basic function.

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

  Conciseness5/5

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

  The description is well-organized: a front-loaded purpose statement, a robustness note, an args section, and a returns section. Every sentence adds value, and the length is proportional to the tool's complexity. No fluff or repetition.

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

  Completeness5/5

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

  With 4 parameters, no annotations, and no output schema, the description addresses all essential aspects: purpose, side effects, parameter details, failure behavior, and return value. It even clarifies that the return is a summary, not the setlists, which is important given the tool's name. The description is complete for successful agent invocation without further assumptions.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description fully compensates by explaining each parameter's role: artist_mbid (MusicBrainz ID, defaults to King Crimson), max_pages (safety cap with 20 shows/page), max_retries (per page on transient errors), and force (re-fetch even if cache exists). This adds clear meaning beyond the schema's simple names and defaults.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: fetch an artist's complete concert history from setlist.fm and cache it locally as JSON for instant/offline analysis. It distinguishes the tool from siblings by specifying the data source and cache target, and adds context about when it's needed (rarely, since King Crimson's history is fixed).

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

  Usage Guidelines4/5

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

  The description provides context for when to use the tool ('so song/tour analysis runs instantly and offline') and notes that it 'rarely needs re-running' due to the band ending in 2021. However, it does not explicitly mention alternatives among sibling cache-refresh tools (e.g., refresh_live_releases_cache) or when not to use it, so it falls short of fully explicit exclusions.

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

• song_live_releasesA
  4.8/5.0
  Behavior5/5

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

  With no annotations, description carries full burden. It openly explains the matching mechanism (setlist cache + recording date parsed from title), limitations (excerpt compilations edge case), and the coverage note for unmatched releases, giving users an accurate expectation of behavior.

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

  Conciseness5/5

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

  Front-loaded with the main purpose, then organized into 'How it works,' prerequisites, Args list, and Returns. Each sentence adds essential information without redundancy, making it appropriately sized for the tool's complexity.

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

  Completeness5/5

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

  Despite no output schema, the description explains the return value (by_incarnation groupings plus coverage note) and gives necessary context for decision-making. Prerequisites, edge cases, and parameter details are all covered, making the description complete for usage.

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

  Parameters5/5

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

  Schema has 0% coverage, but description fully compensates by explaining every parameter: song with example, artist_mbid with default, match with allowed values and definitions. This adds complete meaning beyond the bare schema.

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

  Purpose5/5

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

  First sentence states a specific action (Find official live releases) and a specific resource (captured a given song), plus grouping by incarnation. It clearly distinguishes from sibling tools like song_box_sets and song_performance_history.

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

  Usage Guidelines4/5

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

  Provides clear context: requires both caches to be refreshed first, and explains the matching logic and edge cases. However, it does not explicitly name alternative tools for when-not-to-use, so it stops short of full when/when-not guidance.

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

• song_box_setsA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral disclosure burden. It reveals the data source (Discogs), the dependency on a cache refresh, the matching modes ('exact' vs 'contains'), and the return details including how many times the song appears. This is rich behavioral context beyond just 'this lists box sets.'

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

  Conciseness5/5

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

  The description is well-structured with clear sections for purpose, complementary usage, prerequisites, args, and returns. Every sentence adds value: the example, the cache instruction, the match semantics, and the return fields. It is concise for the amount of guidance provided, with no filler or redundant restating of the tool name.

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

  Completeness5/5

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

  The tool has 3 parameters, no output schema, and no annotations, yet the description covers all of these gaps: it documents every parameter, describes the return structure (title, year, format, Discogs URL, occurrence count), and gives the necessary cache-refresh prerequisite. In the context of the sibling tool list, this is a complete and self-sufficient description.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description fully compensates. It explains each parameter with examples and semantics: song ('Song title (e.g. "Red")'), artist_mbid ('MusicBrainz artist MBID (cache key). Defaults to King Crimson'), and match ('exact (case-insensitive full track title) or contains'). This gives the agent everything needed to set parameters correctly.

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

  Purpose5/5

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

  The description opens with a specific verb, resource, and scope: 'List King Crimson box sets / compilations that contain a given song (from Discogs).' It immediately distinguishes itself from the sibling tool song_live_releases, stating that this tool covers multi-show box sets and comps, while the other maps single-show live albums. This is a clear, well-scoped purpose statement.

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

  Usage Guidelines5/5

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

  The description explicitly names the complementary tool song_live_releases and explains the division of labor: 'that tool maps single-show live albums to eras; this one covers the multi-show box sets and comps that date-matching can't resolve.' It also states a required prerequisite: 'Run refresh_box_sets_cache first.' This gives an agent explicit when-to-use and operational context.

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