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

No annotations are provided, so the description carries the full burden — and it delivers exceptionally: success envelope {'svg': ...}, no_data/204 case, the known live bug where release_group_mbids-only grids return HTTP 500 (with the tool's detection behavior), 400 on unknown combos, image/svg+xml embedding via <object>, and playlist auth. Failure modes and upstream quirks are disclosed thoroughly.

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?

Length is fully justified by 6 endpoints × 19 parameters with zero annotations. It is logically ordered: purpose, endpoints, response contract first, then shared args, then per-action detail. Bold action markers aid scanning, and warnings/known-bug notes are flagged prominently. Every sentence earns its place given the tool's objective complexity.

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

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

For a tool with 19 params, 6 endpoints, no annotations, and an output schema, nothing an agent needs is missing: all params are explained, response formats are specified, auth needs (playlist) are stated, unknown-combo failure (400) and the live 500 bug are documented, and embedding guidance is included. The output schema covering the response means return-value detail is optional, yet it is still provided.

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 0%, so the description must compensate — and it does, covering essentially all 19 parameters: action enum, dimension range 1..5, layout semantics, image_size range, background values, cover_art_size choices, tiles format, time_range enum, custom_name known values, and the release_mbids/release_group_mbids precedence rule. This is near-exhaustive compensation for the empty 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 a specific verb+resource ('Generate ListenBrainz cover art — returns an SVG string') and immediately distinguishes it from all 36 siblings by listing the six discrete endpoints and actions. An agent can tell this covers art generation apart from the playlist/listen/stats tools without ambiguity.

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?

Each action gets explicit guidance: grid for release/release_group mbids, grid-stats for user top releases, custom for named art types, year-in-music with its REQUIRED image caveat, playlist requiring auth, artist-grid for artist top release groups. This is clear per-action context, though it never explicitly contrasts against sibling tools — the differentiation from the 36 siblings is implicit rather than stated.

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?

With no annotations provided, the description carries the full behavioral burden. It discloses multiple non-obvious behaviors: that count/offset are ignored for several type values, that year is required only for certain types, and that different endpoints correspond to each type. It does not mention authentication, error handling, or rate limits, but the input/output schemas and read-only nature are implied. Given the wealth of behavioral detail, a 4 is justified.

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 sentence delivers necessary information: purpose, endpoint mapping, parameter rules, and exclusions. It uses clear sections (endpoint list, args) and front-loads the core purpose. There is no filler; the density is justified by the tool's complexity with ten activity types.

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 tool with this many types and conditional behaviors, the description is remarkably complete. It covers all parameter conditions, defaults, and which types disregard pagination. Since an output schema exists, return value documentation is not required. The only minor omission is lack of examples or error scenarios, but those are not expected given the schema. Overall, nothing needed to call 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 description coverage is 0%, so the description must fully explain parameters. It does: user_name is defined as a ListenBrainz username, type has an explicit list of allowed values, year is described as required for two types and ignored otherwise, range is tied to the get_user_stats enum, and count/offset have ranges and defaults. It also notes which types ignore count/offset. This goes well beyond the schema and makes parameter usage unambiguous.

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 clear verb-resource pair: 'Fetch a user's listening activity, maps, and activity summaries.' It then enumerates specific endpoint variants and type values, making it distinct from siblings like get_user_stats (which covers broader statistics) and get_listens (raw listening events). An agent can immediately understand the tool's scope.

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?

There is no explicit guidance on when to choose this tool over its siblings. It references get_user_stats for the range enum, but does not say 'use this for detailed activity metrics vs. that for aggregate stats.' An agent must infer usage from the tool name and the list of activity types, which is not ideal for disambiguation among several statistics 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the return shape difference (list vs object), parameter clamping (count clamped 1..1000, offset floored at 0), defaults, and the fact that all-flairs ignores count/offset. It even notes the 60s timeout versus the usual 30s, which is a significant behavioral nuance. This is exemplary 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 information-dense but every sentence earns its place. It is organized with endpoints and arguments, front-loads the core purpose, and packs edge-case behavior into a compact format. Nothing is redundant or filler; the length is justified by 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?

Given the tool's complexity (three modes, parameter interactions, timeout differences) and that an output schema exists, the description is remarkably complete. It covers all usage scenarios, parameter nuances, and performance caveats. An agent has everything needed to invoke the tool correctly without external knowledge.

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 0%, so the description must compensate. It fully explains each parameter: mode with its three enumerated options, count with its default and clamping range, and offset with its default and flooring. It also clarifies that the latter two are ignored for all-flairs. This goes well beyond the schema, which only lists names and types.

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: 'List MetaBrainz donors and their ListenBrainz flairs.' It then breaks out the three modes (recent, biggest, all-flairs) with their exact endpoints, making the purpose unambiguous and differentiating the variants. This is far beyond a tautology and clearly distinct from any sibling tool.

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 explains when to use each mode: 'recent (latest donors)', 'biggest (largest donations)', and 'all-flairs (username → flair map for every eligible donor)'. It also notes that count and offset are ignored by all-flairs, and warns of its longer runtime with an extended timeout. This gives an agent complete guidance on selecting the right mode and parameterization.

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?

With no annotations, the description carries the full burden. It discloses that the operation returns information, describes the response fields (id, timestamp, dump_type), and explains the optional parameter behavior. While it does not mention errors or side effects, it is a simple read-only getter and the provided details are sufficient for an agent to understand the 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 three lines and every piece is useful: purpose, endpoint, parameter behavior, and response format. No redundant or vague language. It is front-loaded with the core purpose and includes supporting details compactly.

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 simple getter with an output schema, the description covers the essential aspects: what it does, the optional parameter semantics, and the response structure. Nothing an agent needs to call it correctly is missing. The output schema exists, so the description does not need to explain return values in more depth.

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?

The schema has 0% description coverage, but the description adds meaning to the dump_id parameter: it is optional, and if omitted, information about the latest dump is returned. This goes beyond the schema's type and default, giving the agent crucial semantic context.

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 a specific verb and resource: 'Get information about ListenBrainz data dumps.' It is clearly distinct from all sibling tools, which deal with listens, metadata, recommendations, etc. The inclusion of the endpoint further clarifies the exact 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?

No explicit guidance on when to use this tool versus alternatives. However, the tool is the only one about data dumps, so usage is self-evident. There is no mention of when not to use it or any prerequisites, but the lack of alternatives makes this a minor gap.

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?

With no annotations, the description carries the full burden. It states the endpoints and arguments but does not disclose the response format, any read-only nature explicitly, potential error conditions, or rate limits. The reference to get_user_stats for the enum is the only behavioral hint, leaving much to inference.

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 compact and structured: one purpose line, two endpoint lines, and an Args line with clear parameter definitions. No filler or repetitive content—every sentence serves a purpose.

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 the endpoints and all parameters, and the presence of an output schema mitigates the need to describe return values. However, it lacks usage context (e.g., typical use cases), fails to fully enumerate the range enum, and does not mention any input validation or edge cases. It is adequate for a simple fetch but not fully self-contained.

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 0%, so the description compensates well by defining each parameter: entity lists the allowed values, mbid is described as the MusicBrainz ID, and range notes its default and points to another tool's enum. This provides sufficient semantic grounding for all three parameters, though the enum reference requires cross-tool lookup.

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 immediately states 'Fetch listeners for an artist or release-group by MBID,' specifying the verb, resource, and entity types. It clearly distinguishes itself from siblings like get_entity_metadata and get_popularity by focusing specifically on listener counts.

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?

No guidance is provided on when to use this tool versus other stats tools, such as get_user_stats or get_popularity. The only reference to an alternative is the 'same enum as get_user_stats' for the range parameter, which implies existence but offers no comparative usage context.

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?

With no annotations, the description carries the full burden and does disclose important behavior: the 75-item limit, the live-probed 502 beyond that, and upstream rejection of unsupported entity/inc combinations. It also notes the comma-joining wire format. However, it omits auth requirements and rate limits, which are minor given the tool's read-only nature.

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 compact and logically ordered: purpose, endpoints, then parameter details, then a caveat. Each sentence earns its place—no repetition or filler—and the key limitations are front-loaded near the relevant parameter.

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 3-parameter tool with no schema descriptions, the description covers all parameters, their formats, and constraints, plus endpoint specifics and a verified limitation. The output schema presumably handles return structure, so nothing critical 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 0%, so the description must compensate fully. It does: 'entity' is restricted to two values, 'mbids' is explained as a list of MBIDs with a hard limit of 75 and comma-joining, and 'inc' is described as a space-separated subset of 'artist tag release'. This is exactly the meaning an agent needs.

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: 'Fetch MusicBrainz metadata for artists or release-groups by MBID.' This is specific (verb 'fetch' + resource 'MusicBrainz metadata') and distinguishes it from siblings like get_recording_metadata, which handles recordings. The explicit endpoints reinforce the scope.

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 does not explicitly frame when to use this tool versus other metadata lookups (e.g., lookup_metadata or get_recording_metadata). It only implies usage through the entity parameter and mentions limitations, but offers no guidance on selection criteria or exclusions.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses authorization requirements ('upstream also requires the token owner to match'), parameter interactions (mutual exclusivity, ignored params for event mode), and defaults (count 1..1000, default 25), and notes that the census route carries no query parameters. No mutation is implied; 'Read' clearly signals a read-only operation.

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 organized: it starts with the purpose, lists endpoints inline, then details each parameter with cross-references. Every sentence adds unique information; there is no filler or repetition. The format makes it easy to scan despite its length.

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

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

The description covers all modes, endpoint variations, parameter constraints, auth requirements, and edge cases (e.g., ignored parameters). It references the get_listens rule for consistency, and since an output schema exists, return value details are not needed. No critical aspect of invoking this tool 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 0%, so the description must fully explain each parameter. It does: mode enumerates all four values, count has bounds and default, min_ts/max_ts are described as mutually exclusive unix timestamps, event_id is required only for event mode, and user_name is the target user. This is comprehensive and goes well beyond the bare 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 a clear verb ('Read') and a specific resource ('a user's timeline feed events or listen events'). It distinguishes four modes (events, following, similar, event) and maps them to exact endpoints, making the tool's function unmistakable even among many sibling tools like get_listens and manage_timeline.

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 when-to-use guidance for each mode, e.g., 'events: full timeline events; following/similar: listen events from followed/similar users.' It also references the get_listens rule for min_ts/max_ts mutual exclusivity, which helps align with another tool. However, it does not explicitly state when to prefer this tool over alternatives (e.g., get_listens for raw listening history), so it falls short of full routing 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?

With no annotations, the description carries the full burden of behavioral disclosure. It explains key behaviors: days is clamped to 1–90, color must be a hex value and ignores several other parameters, optional filters ride along only when given, and days always rides along with its clamped value. It does not explicitly state read-only semantics or auth requirements, but the tool's nature and endpoints imply a read operation. Given the detailed parameter interactions, it provides substantial transparency beyond the schema.

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 logically structured: a one-sentence summary, endpoint listing, then category-specific parameter explanations. It front-loads the core purpose and uses clear formatting with line breaks. Every sentence adds value—no filler or repetition. For an 8-parameter, 3-mode tool, this is appropriately concise without sacrificing completeness.

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

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

Given the complexity (8 parameters, 3 distinct modes with different constraints), the description covers all necessary invocation details: endpoints, parameter defaults, allowed values, clamping, color format, and how modes interact. An output schema exists, so not describing return format is acceptable. Nothing an agent needs to call 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 0%, so the description must explain every parameter, and it does so comprehensively. It defines source with its three values, explains days with its default and clamp, sort with per-source vocabulary, past/future booleans, user_name for the user source, color with a strict format, and release_date as an optional pivot. It also clarifies which parameters are ignored in color mode, leaving no ambiguity for the agent.

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 clear verb+resource statement ('Discover fresh (upcoming + recent) releases') and then elaborates three distinct modes (explore, user, color), each with its own endpoint and behavior. This goes beyond a generic statement and gives the agent a precise understanding of what the tool does and how it differs internally.

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 does not mention alternative tools or explicitly say when not to use this tool, but it provides strong guidance on how to choose among the three sources (site-wide vs. user-specific vs. color-based) and explains which parameters apply per source. This effectively tells an agent when to use each mode, which is essential for correct invocation. A small gap is that it does not differentiate against sibling tools, but the internal routing guidance is clear enough to be rated above baseline.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It states that min_ts and max_ts are mutually exclusive, that playing_now ignores count/min_ts/max_ts, and that the playing-now endpoint is used when playing_now=True. This exposes key conditional behaviors beyond the parameter schema. It does not mention authentication or rate limits, but for a read-only fetch these are less critical; a 4 is warranted.

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, with a clear two-line purpose statement followed by endpoint details and parameter semantics. It is not overly padded, but the formatting is slightly verbose (multiple lines and dashes). It is well front-loaded and earns its space, though a small trim could make it more 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?

Given the complexity of conditional behavior (mutual exclusivity, playing_now ignoring other params) and the presence of an output schema, the description covers the essential calling contract well. It does not mention error cases (e.g., what happens if both min_ts and max_ts are provided, or user not found), but those are less likely to prevent a correct call. Overall it is sufficiently complete for an agent to invoke it 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?

The schema description coverage is 0%, so the description must compensate. It does so excellently: it explains user_name as a ListenBrainz username, count's range and default, the mutual exclusivity of min_ts/max_ts, and the effect of playing_now. This gives meaning far beyond the bare schema types and defaults, fully compensating for the coverage gap.

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: 'Fetch a user's listens, or their currently-playing track.' This clearly distinguishes it from siblings like get_listen_summary, submit_listen, and manage_listen. It also names the two endpoint variants, making the tool's scope unambiguous.

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

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

The description explains the two usage modes (history vs. currently playing) and the conditions that select them (playing_now=True). While it does not explicitly mention alternatives like get_listen_summary or submit_listen, the context is clear enough for an agent to know when this tool applies. No exclusions are given, so it falls just 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.

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

No annotations are provided, so the description must carry the burden. It discloses the merging behavior and the fail-fast error handling ('If either call returns an error envelope, it is returned as-is'). This goes beyond a bare statement and gives useful operational context. However, it does not state read-only nature or other potential side effects, but for a data retrieval tool this is acceptable.

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 relatively concise, with the summary front-loaded. It uses a clear list for endpoints and a brief paragraph for merging. There is slight redundancy between the initial summary and the later merge explanation, but overall it is well structured and to the point.

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, return values need not be detailed. The description covers the endpoints, the argument, the merge behavior, and error handling. It lacks mention of any authentication or rate limits, but these are not typically expected in tool descriptions and the provided context appears sufficient for an agent to make the call.

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 0%, so the description must compensate. It clearly explains 'user_name — ListenBrainz username whose total listen count and connected services are fetched.' This adds meaning by identifying the parameter as a ListenBrainz username and its role, going beyond the bare schema type. It could include format constraints, but the explanation is sufficient.

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 function: 'Total listen count and connected services for a user, merged.' It specifies the resource (user summary) and the specific data points, distinguishing it from sibling tools like get_listens or get_user_stats by its unique combined scope.

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?

No explicit guidance on when to use this tool versus alternatives. The description implies it should be used when both listen count and services are needed, but it does not name alternatives or provide exclusions. An agent would have to infer the use case.

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 are absent, so the description carries the full burden of behavioral disclosure. It only mentions 'fetch', which implies a read-only operation, but does not clarify authentication requirements, response format, error scenarios, or whether any side effects exist. This is a significant gap for a tool with no annotation support.

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 exceptionally concise: one sentence plus endpoint and argument, with no fluff. The core purpose is front-loaded, making it immediately scannable and efficient for an agent to parse.

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 simple read operation with a single parameter and an output schema, the description fully specifies how to make the call (endpoint and argument). It omits usage context, but that is addressed in the usage guidelines dimension; the tool invocation itself is 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?

With 0% schema description coverage, the description compensates by explaining recording_msid as 'the MessyBrainz ID to look up', adding semantic meaning beyond the schema's parameter name and type. For a single parameter, this provides sufficient clarity, though it lacks constraints or format details.

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 explicitly states 'Fetch the manual MSID→MBID mapping for a recording MSID', specifying a precise verb and resource. This clearly distinguishes it from siblings like submit_manual_mapping (which submits, not fetches) and get_recording_metadata (which retrieves different metadata).

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?

No guidance is provided on when to use this tool versus alternatives such as lookup_metadata or get_recording_metadata. The description only states the action without any context on selection criteria, leaving the agent to infer when this specific tool is appropriate.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently documents the endpoint, the truncation logic with the 'truncated' marker, the two envelope shapes (live and legacy), and the defensive handling of legacy payloads. It also explains the effect of fetch_metadata and limit in detail.

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 detailed but well-structured: a one-sentence purpose, then endpoint, then parameter explanations. Every sentence adds value, though some sections (like the envelope shape explanation) are slightly verbose. The front-loaded purpose ensures clarity.

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 complexity and the presence of an output schema, the description is complete. It covers all parameters, edge cases (legacy payload shape), side effects (truncation), and the conditional behavior of limit. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It clearly defines playlist_mbid as required, fetch_metadata as a flag to skip metadata lookup, and limit with its truncation behavior including the addition of 'truncated_to'. This far exceeds the schema's type-only info.

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 'Fetch one playlist in JSPF format,' which is a specific verb ('Fetch') and a singular resource ('one playlist') plus the format. This clearly distinguishes it from list_playlists (which retrieves multiple) and manage_playlist (which modifies).

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 this tool is for fetching a single playlist, but it does not explicitly state when to prefer it over alternatives like list_playlists or get_playlist_status. No exclusions or conditional usage guidance is provided, leaving the agent to infer context.

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?

There are no annotations, so the description carries the full burden. It states the endpoint is GET, implying read-only, and describes the return (age in seconds). However, it does not disclose whether authentication is required, any rate limits, or explicitly confirm that no data is modified. The GET method implies safety, but the lack of explicit statements about side effects or auth leaves transparency incomplete.

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 succinct: three sentences with the core purpose in the first line, followed by endpoint and return details. There is no fluff, and every sentence contributes essential information. It is well-structured and easily scannable.

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 has no parameters and an output schema (which covers return format), the description fully explains what it does and what it returns. It names example playlists, which gives context. No critical information for calling the tool 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?

The tool has zero parameters, and the schema coverage is 100% (no properties). Per the calibration, a zero-parameter tool gets a baseline of 4 as no extra parameter explanation is needed. The description adds no parameter-related information, which is acceptable.

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 purpose: 'Get freshness metrics for recommendation playlists.' It specifies the resource (recommendation playlists) and gives concrete examples (daily-jams, weekly-jams, weekly-exploration). This distinguishes it from sibling tools like get_service_status or get_fresh_releases, which serve different purposes.

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 indicates when to use it (to check freshness of monitored recommendation playlists) but does not explicitly mention alternatives or conditions for not using it. It does not say 'use this instead of X when Y', so the guidance is only implied by the phrasing, not explicit.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly covers response ordering, null handling for unknown MBIDs, error behavior for non-integers, authentication requirements for top mode, and parameter interactions. This is exemplary transparency beyond what schemas could provide.

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?

Although lengthy, the description is densely informative with a clear structure: endpoints first, then parameter details. Every sentence adds value—no filler. The front-loaded purpose and organized sections make it easy for an agent to parse.

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 presence of an output schema, the description need not explain return values. For all other aspects, it is complete: it covers both modes, all parameters, edge cases, authentication, and endpoint mapping. An agent has everything needed to call this tool 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?

The input schema has 0% description coverage, yet the description fully compensates by explaining every parameter: mode, entity, mbids, artist_mbid, count, including defaults, constraints, and how they relate. It even details the POST body structure and live-verified key, which is essential for correct invocation.

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 fetches ListenBrainz popularity with total listen and listener counts. It distinguishes between batch and top modes, listing the endpoints for each. This is specific and immediately tells an agent what the tool does and how it differs from the siblings.

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 explains when to use batch (explicit MBIDs) versus top (an artist's most-listened entities). It also notes that top mode requires authentication and batch ignores certain parameters. While it doesn't contrast with alternative tools, the mode selection guidance is clear and sufficient for typical usage.

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

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

There are no annotations, so the description carries full burden. It discloses that the endpoint is experimental ('Experimental upstream: model output quality varies'), the return format (raw payload, scores only), and the need to resolve against MusicBrainz for names. It also states parameter defaults and constraints ('count — 1..1000 (default 25); offset — non-negative'). No contradictions with annotations (none provided).

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 a few sentences but front-loads the core purpose. It packs a lot of detail (endpoint, args, return format, caveat) without redundancy. Minor inefficiency: repeating 'raw' multiple times and slightly redundant 'recording recommendations' vs 'CF payload', but overall efficient and well-organized in a single paragraph.

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 3-param tool with no annotations and an output schema, the description covers all essentials: endpoint, parameter constraints, return format, and experimental caveat. It doesn't detail pagination beyond offset, but explains defaults. It doesn't mention error handling (e.g., unknown user), but given upstream context, it's adequate. Minor gap: no indication of how to interpret scores (e.g., scale), but that's upstream-dependent.

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 0%, so the description must fully explain parameters. It does: 'user_name — ListenBrainz username; count — 1..1000 (default 25); offset — non-negative (default 0)'. It introduces constraints not in schema (count upper bound, offset non-negativity) and explains the semantic role of user_name. This far exceeds what the schema offers.

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 a specific verb ('Fetch'), a clear resource ('raw collaborative-filtering recording recommendations'), and the exact endpoint. It explicitly distinguishes the return data (raw CF payload: mbids + scores only) from what it is not (no titles/artists), and references sibling-like resolution needs. This is clearly differentiated from sibling tools like get_recording_metadata or get_listens.

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 effectively says when this should be used: when raw score data is needed and names the alternative ('resolve against MusicBrainz if you need names'). It does not explicitly state when NOT to use it (e.g., prefer get_recording_metadata for enriched data), but the 'raw' vs 'if you need names' guidance makes the intended use clear. It also warns about experimental quality, which helps an agent judge applicability.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It transparently reveals endpoint routing (GET vs POST), the batch parameter's effect, the critical quirk that 'inc' must be a JSON string on the POST body (not a list), and that responses are keyed by MBID. It does not mention rate limits, authentication, or error handling, but for a read-only metadata fetch, the disclosed details are 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?

The description is information-dense but efficiently organized: a clear opening sentence, a bulleted list of endpoints, then a concise 'Args' section with clarifying notes. Every sentence adds value, and the critical format warning for inc is prominently placed. Slightly longer than minimal but justified by the tool's complexity.

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

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

Given the presence of an output schema (which covers return values) and no annotations, the description covers the essential behavioral details: endpoint selection, batch semantics, inc format, and response keying. It does not address broader concerns like rate limits or alternative tools, but for a single-tool perspective it is quite 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?

Schema coverage is 0%, and the description fully compensates by explaining each parameter: mbids (one or more MBIDs), inc (space-separated subset of artist tag release), and batch (forces POST even for single mbid). It even clarifies the exact format for inc on the POST body, going beyond what the schema alone provides. This is exemplary compensation for a low-coverage 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 clearly states the verb (Fetch), resource (MusicBrainz metadata for recordings), and the key identifier (MBID). It goes beyond a generic statement by specifying endpoints and the single-vs-batch distinction, which distinguishes it from sibling metadata tools like lookup_metadata and get_entity_metadata.

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 strong context for when to use the tool (when you have recording MBIDs and need MusicBrainz metadata) and provides detailed calling instructions, including endpoints and batch behavior. However, it does not explicitly mention when NOT to use it or compare it to alternatives like lookup_metadata or get_entity_metadata, leaving the selection decision to the agent without explicit routing.

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?

With no annotations, the description must carry the burden of behavioral disclosure. It does describe the response content (ages in seconds, queue length), which is useful, but it does not mention whether the endpoint requires authentication, whether it has side effects (likely none, but unstated), rate limits, or error handling (e.g., timeout or service-unavailable behavior). The 'Get' verb implies read-only, but this is not explicitly disclosed.

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 concise and front-loaded with the core purpose. It adds the endpoint path, which is useful extra context, and then lists the returned metrics in a compact list format. Every sentence earns its place; there is no fluff or repetition. Slightly longer than necessary but still efficient.

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 tool is simple (no parameters) and has an output schema (which we don't see but exists), so the description's explanation of return values is partially redundant. However, it omits operational context: authentication requirements, whether the endpoint is public, potential error conditions, and whether data is real-time or cached. Given siblings like validate_token, auth might be needed, but the description is silent. For a status tool, this is a notable gap.

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?

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter semantics—there are none. It correctly omits any parameter explanation, and the empty input schema confirms this. The description adds no parameter info because none exists, which 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's purpose: 'Get freshness metrics for ListenBrainz services.' It enumerates exactly what is returned (ages of last data dump, stats generation runs, per-stat ages, sitewide stats age, and number of listens in the incoming queue), making it unambiguous. This specificity distinguishes it from sibling tools like get_sitewide_stats or get_dump_info.

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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is a read-only status check, nor does it contrast it with similar tools (e.g., get_sitewide_stats, get_dump_info). An agent has no explicit condition for selecting this over siblings.

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?

No annotations are provided, so the description carries the full burden. It discloses that these are GET endpoints and describes the two behaviors, but it does not detail any rate limits, authentication requirements, error scenarios, or output structure beyond the endpoints. The core behavior is transparent, but important contextual traits (e.g., pagination, data freshness) are missing.

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 efficiently structured: a one-sentence purpose, a clear endpoint listing, and a parameter breakdown. It front-loads the core purpose and uses line breaks for readability. Every sentence earns its place with no filler.

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 (a GET with two possible modes) and the presence of an output schema (not shown but present), the description covers the essential call patterns. Missing are edge-case notes like what happens when a user does not exist or when similarity is undefined, but these are not critical for correct usage and may be handled by the output 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 description coverage is 0%, so the description must compensate. It defines user_name as a ListenBrainz username and explains that other_user_name is optional and switches the tool into comparison mode. This adds semantics that the schema lacks, though it could be slightly more explicit about the expected format of usernames.

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 a specific verb and resource: 'Find a user's similar users, or how similar two users are.' It clearly identifies two distinct functions and includes the exact endpoints, distinguishing it from siblings like search_users or get_user_stats. The dual-mode behavior is unambiguous.

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

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

The description explains the two operational modes based on whether other_user_name is provided: if present, compare the two users; if absent, list similar users for the given user. This is clear context for when to use each mode. However, it does not explicitly state when to prefer this tool over alternatives such as search_users, though the distinct purpose makes that implicit.

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?

Provided no annotations, the description carries the full behavioral burden. It does disclose that for listening-activity, artist-map, artist-activity, era-activity, and artist-evolution-activity, count/offset are not sent — a genuinely useful behavioral detail. But it stays silent on side effects (fetch implies read-only, yet it is never stated), rate limits, and what the response structure looks like, leaving meaningful gaps.

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 nine-line endpoint block largely duplicates the type enum that follows it (same values with a /1/stats/sitewide/ prefix), adding length without new information. The Args paragraph is compact and well-organized, and the lead sentence front-loads the purpose, but the redundant endpoint list keeps this from being tight.

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?

Balanced against significant complexity — nine distinct stat types with varying parameter applicability — the description covers the essential nuance by calling out which types ignore count/offset. Since an output schema exists, return-value documentation is not required, making this reasonably complete 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.

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

With 0% schema description coverage, the description compensates well: it enumerates all type values, imposes the count range (1..1000) and offset constraint (non-negative), states defaults, and references the range enum to get_user_stats. The only shortfall is deferring the full range enum to another tool rather than listing it.

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+resource ('Fetch sitewide top entities and activity') and enumerates all nine endpoints. The 'sitewide' scope clearly distinguishes it from siblings like get_user_stats, though that differentiation is implied by the word rather than stated explicitly.

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 context is implied by the 'sitewide' scope — an agent can infer this is for global stats, not user-specific ones. However, there is no explicit statement of when to prefer this over get_user_stats, get_activity_stats, or get_popularity, nor any when-not-to-use guidance. The exclusion is left entirely to inference.

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?

No annotations are provided, so the description carries the full burden. It discloses the endpoints and parameter constraints, implying a read-only operation via the verb 'Fetch'. However, it does not explicitly state that it only reads data, nor does it mention authentication, rate limits, or error behavior. For a simple GET-based tool, this is adequate but not enriched beyond the basic API 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?

The description is well-structured, starting with the purpose, then listing endpoints in a bullet-like format, and then detailing parameters. It is slightly verbose due to the full parameter list, but given the 0% schema coverage, this detail is necessary. It is front-loaded with the core purpose and remains organized.

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 that an output schema exists and this is a straightforward read operation, the description is quite complete. It covers all parameters, provides endpoint URLs, and gives default values. It does not describe the return format, but the output schema covers that. It lacks notes on authentication or potential errors, but for a fetch endpoint the description is sufficient for an agent to call it 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?

The schema has 0% description coverage, so the description compensates fully. It explains every parameter: user_name as ListenBrainz username, entity with explicit enum values, range with explicit enum values and default, count with range 1-1000 and default, offset as non-negative with default. This goes well beyond the schema's type and default information, providing the exact allowed values and constraints.

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 fetches a user's top entities (artists, releases, etc.) and lists the specific endpoints. The verb 'Fetch' and resource 'a user's top entities' are specific. However, it does not explicitly differentiate from sibling tools like get_activity_stats or get_sitewide_stats, though the user-scope is implied by 'a user's'. This is clear but lacks explicit sibling differentiation.

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 provides no guidance on when to use this tool versus alternatives. It lists parameters and endpoints but does not mention any conditions or contexts where this tool is preferred, nor does it mention any exclusions. There is no reference to sibling tools or when to choose them instead. This is a gap for a stats endpoint among many similar ones.

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?

With no annotations provided, the description carries the full burden and delivers exceptionally. It discloses upstream resolution behavior (entire prompt treated as ONE exact-spelling artist name, 400 failure mode with live probe date), response format differences across modes, a critical gotcha (tags mode returns raw entries, NOT a valid tag list), the extended 120s client timeout versus 30s default, and the uppercase AND/OR requirement. No annotation contradiction exists since none were supplied.

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 front-loaded with the core purpose and uses mode headers/endpoints for structure, but it is a dense wall of text with repetition: pop_begin/pop_end constraints and 'required upstream' appear multiple times across modes. The length is partly justified by the tool's three-mode complexity, yet an agent must parse a large block with redundant spec lines, which harms digestibility.

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 an 11-parameter, zero-annotation tool with no schema coverage, this description is remarkably complete. It explains every mode, all parameter quirks, error behavior, response shapes, and timeout handling. An output schema exists so return values need no clarification. Nothing an agent needs to invoke this tool correctly across its three distinct modes 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 0%, so the description must compensate — and it does, covering all 11 parameters: mode, prompt, difficulty, seed_artist_mbid, max_similar_artists, max_recordings_per_artist, pop_begin/pop_end (with range and ordering constraints), tags, operator (with case requirement), and count (with default and required-status). It adds value far beyond the bare schema, including validation rules, defaults, and upstream requirements.

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 a specific verb ('generate'), resources ('playlist or recording pool'), and three distinct input sources (prompt, artist, tag list). It clearly delineates the three modes with their endpoints (explore/artist/tags), making the scope unambiguous. It effectively distinguishes from sibling tools like manage_playlist and the get_* retrieval tools, which are about managing or reading existing playlists rather than generating them.

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 mode-specific usage guidance: what each mode returns (JSPF vs. dict keyed by artist MBID vs. raw recording entries), and which parameters each mode requires. It calls out when the 'tags' mode needs a non-empty list, and warns that free-text prompts fail upstream. It does not explicitly name sibling alternatives or state exclusion conditions (e.g., 'use manage_playlist for editing'), but the mode-level context is strong enough to guide correct selection.

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?

With no annotations provided, the description carries the full burden, and it delivers. It discloses that site-wide search is slow (~30s+ upstream) and that a 90s timeout override is applied, that mine includes private playlists when authorized while createdfor are always public, and that recommendations have no pagination. It also notes the local enforcement of the 3-character query minimum. No contradictions with annotations exist (none provided).

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 information-dense; every line adds necessary detail given the multi-mode nature of the tool. It is front-loaded with the main purpose and then systematically covers endpoints, parameters, and exceptions. While it could be tightened slightly, the structure is logical and each sentence earns its place.

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

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

For a tool with five parameters, multiple source modes, pagination differences, and a known slow path, this description is exceptionally complete. It covers auth implications, performance, edge cases, and all relevant parameter interactions. Since an output schema exists, the lack of return-value description is acceptable. 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 description coverage is 0%, so the description must compensate for every parameter, and it does thoroughly. It explains source with all valid values and their semantics, playlist_user_name with its placeholder spelling and which sources require it, query with its length restriction, and count/offset with ranges, defaults, and which sources they apply to. This goes far beyond the minimal schema types.

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 'List, recommend, or search playlists for a user,' stating the verb-action and resource clearly. It goes further to enumerate the exact endpoints and source modes, making the tool's scope unmistakable. This distinguishes it from sibling tools like get_playlist (single playlist) without naming them explicitly, but the purpose is fully clear.

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 detailed when-to-use guidance for each source: mine vs createdfor vs search, including the requirement for playlist_user_name for per-user routes and the site-wide nature of search. It explicitly states that search plus user_search need a query and that queries under 3 chars are rejected. However, it does not explicitly compare to alternative sibling tools (e.g., get_playlist) for when to use this versus others; it's internally complete but lacks cross-tool exclusions.

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?

Since no annotations are provided, the description must fully disclose behavioral aspects. It does explain the wire format (GET vs POST), the parameter-to-field mapping, and the batch precedence rule, which is useful. However, it does not mention whether the operation is read-only, authentication requirements, rate limits, or error behavior. Given the absence of annotations, this leaves significant behavioral gaps.

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 and efficient. It opens with the core purpose, then lists endpoints, then parameters with clear explanations. Every sentence contributes value, and the precedence rule for batch is explicitly stated. There is no fluff or 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?

The description covers most essential aspects needed to call the tool correctly: parameter requirements, wire mapping, endpoint selection, and batch precedence. It does not mention authentication requirements (likely needed for a private API) or the exact shape of batch items, but the presence of an output schema means return values are covered. Overall, it is fairly complete for a lookup 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?

The description adds substantial meaning to all parameters, compensating for the 0% schema description coverage. It explains artist/release/track and their wire names, duration as seconds, recording_mbid as a disambiguator, and batch as a list that overrides the others. The only gap is the internal structure of each item in the batch, but overall it goes well beyond the bare 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 clearly states the tool's purpose: 'Look up a recording MSID/MBID from listen metadata names.' It identifies a specific operation (lookup) and resource (recording identifiers). While it does not explicitly distinguish itself from siblings like get_recording_metadata or get_entity_metadata, the purpose is unambiguous and focused on name-based identifier mapping.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any sibling tools, conditions, or scenarios that would make this the preferred choice over other metadata lookup tools. The only implicit usage is the purpose itself, but there is no explicit when-to-use or when-not-to-use information.

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?

With no annotations provided, the description carries full responsibility. It fully discloses the actor semantics (token owner is the acting account), the absence of a request body for writes, authentication requirements, and the return of full lists for read actions. This covers all key behavioral aspects.

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 and well-organized, with a summary line, endpoint table, and parameter notes. It is longer than necessary but every detail serves a purpose, and the key information (action set and semantics) is front-loaded. Minor redundancy exists in repeating the endpoint list.

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 multi-action complexity and the absence of any parameter descriptions in the schema, the description is remarkably complete. It covers endpoints, action values, parameter semantics, authentication, and pagination behavior. No critical information for correct invocation is missing.

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

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

Schema coverage is 0%, so the description is the sole source of parameter meaning. It defines action as one of four enumerated values and explains the two distinct interpretations of user_name (target for follow/unfollow, owner of lists for followers/following). This is complete and precise.

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 clear, specific statement: 'Follow, unfollow, or list a user's followers/following.' It enumerates all four actions and maps each to an endpoint, making the tool's purpose unambiguous and distinct from siblings like manage_listen or manage_playlist.

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 explains when to use each action (follow/unfollow vs read lists) and clarifies the semantics of user_name for reads vs writes. It notes authentication requirements for writes and the lack of pagination for reads. However, it doesn't explicitly compare to alternative tools, though none clearly overlap.

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?

With no annotations, the description carries the full burden. It discloses that all actions require authentication, maps each action to its endpoint, explains parameter dependencies per action, and notes that for get_latest_import, literal null error/status fields are stripped to avoid a misleading 'error': null. These are useful behavioral details beyond the schema.

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: a one-sentence summary, then endpoints, then argument details. It is informative without redundant phrasing, though slightly long due to covering three actions. The primary purpose is front-loaded.

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 tool with 5 parameters, 3 actions, and no annotations, the description covers the essential use cases, auth, and one behavior quirk. However, it omits details on track_metadata structure, user_name format, and error handling (beyond the null-stripping note). The output schema exists but is not referenced, so an agent may need more info to fully understand responses.

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 0%, so the description must compensate. It explains which parameters each action requires (e.g., delete_listen needs listened_at + track_metadata) and that listened_at and timestamp are unix seconds. However, it does not describe what track_metadata should contain or the expected format of user_name, leaving gaps in parameter understanding.

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 can delete a listen or read/set the user's latest-import timestamp, and enumerates the three specific actions with endpoints. This is a specific verb+resource combination that distinguishes it from siblings like submit_listen (submit) and get_listens (retrieve).

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 when to use the tool (when you need to delete a listen or manage the latest-import timestamp) and provides per-action parameter requirements, but it does not explicitly compare with alternatives or state when not to use it. The context is present but not framed as a choice between 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?

With no annotations, the description carries the full burden of behavioral disclosure and does so richly. It notes that pins auto-expire after 7 days upstream, distinguishes 'unpin' (deactivates) from 'delete' (removes from history), warns that write actions require authentication, and even flags a live API spec discrepancy that would cause a 404. This is comprehensive and prevents misunderstanding.

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

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

The description is long but every section serves a purpose: the one-liner summary, endpoint list, parameter requirements, behavioral caveats, and the spec-error note. It is structured with headers and line breaks, making it scannable. It is slightly dense, but given 8 parameters and 8 distinct actions, the length is justified.

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 multi-action tool with 8 parameters and an output schema present, the description covers all essential operational details: actions, endpoints, parameter validity, authentication, pagination, and edge cases (auto-expiry, deactivation vs deletion, the spec discrepancy). No critical missing information that would prevent correct invocation was found.

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 0%, so the description must define parameter semantics, and it does: it maps each action to required and optional parameters (recording_mbid for pin, row_id for unpin/delete/update/get, blurb_content for update), and specifies constraints for list (count 1–1000, offset non-negative, defaults). It also clarifies the user_name usage for the list-type actions. This adds substantial meaning beyond the raw 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 a clear verb and resource: 'Pin, unpin, update, delete, or read pinned recordings.' It enumerates the full set of operations and lists the concrete endpoints for each, which unambiguously identifies the tool's domain. While it does not explicitly contrast with siblings, the specificity of 'pinned recordings' makes it distinct from listen/stat/playlist tools.

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 provides no explicit guidance on when to choose this tool over alternatives. It is implied by the tool's name and scope that pins are handled here, and the internal action selection (pin, unpin, etc.) is well documented. However, there is no mention of sibling tools or conditions under which a different tool should be used, so the usage guidance is only implicit.

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?

With no annotations provided, the description carries full disclosure burden. It explicitly covers auth requirements ('All write actions require authentication upstream'), the upstream quirk requiring an explicit public flag on create, the non-clobbering behavior of edit, and the exact response shape of export_xspf. This is thorough and beyond expected.

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 and dense, but it is logically organized by endpoints then per-action details. Every sentence adds information, and the density is justified by having nine actions and eleven parameters. It could be slightly more scannable with header formatting, but it earns its length.

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

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

Given the complexity (8 actions, 11 parameters) and the existence of an output schema, the description is complete. It covers all parameter prerequisites, optional flags, edge cases (no id on import_playlists), and response formats where relevant. Nothing that an agent needs to call this 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 description coverage is 0%, so the description must compensate. It does so comprehensively: for every parameter it states which actions use it, what it means, and any format expectations (e.g., jspf as a bare object or JSON string, service enum values). This is exactly the kind of compensation needed when schema titles are unhelpful.

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 precise verb set ('Create, edit, delete, copy, or transfer playlists') and enumerates eight distinct actions, each with its own endpoint. This makes it unmistakable which operations this tool covers, fully distinguishing it from siblings like list_playlists, get_playlist, and manage_playlist_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?

Each action lists its required and optional parameters, and the description notes authentication requirements for writes. It also flags quirks like the mandatory public flag on create. However, it does not explicitly compare with sibling tools (e.g., when to use manage_playlist_tracks instead), though the action breakdown makes the intended usage reasonably 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?

With no annotations provided, the description bears the full burden of behavioral disclosure, and it excels. It details the exact endpoint URLs, the required JSPF body format (and explicitly warns against the alternative format), parameter constraints (e.g., offset clamping, max 100 recordings), local enforcement, and the requirement that all actions need authentication. This goes well beyond a basic summary and fully prepares the agent for server 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 dense but well-organized. It opens with a one-sentence summary, then lists endpoints, then breaks down each action with its specific parameters. Every sentence adds crucial information—no filler or redundancy. The structure logically groups related details, making it easy for an agent to parse and apply. It is appropriately sized given the complexity of supporting three different operations.

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 complexity (8 parameters, 3 actions, no parameter descriptions in schema, no annotations), the description is remarkably complete. It covers endpoints, body format, authentication, parameter constraints, defaults, and even notes local enforcement of the recording limit. The only missing element is return/error behavior, but the presence of an output schema implies that information is structured separately. The description fully equips an agent to invoke the tool 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?

The schema provides no descriptions (0% coverage), so the description must fully explain each parameter. It does this comprehensively: for each action it names the relevant parameters, their defaults, constraints, and how they map to the API (e.g., recordings are wrapped into canonical URIs, offset becomes a path segment). It also clarifies that move requires all of recording_mbid/index/to_index/count in the body, and delete requires both index and count. This is exemplary context that the schema alone cannot provide.

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 clear verb phrase 'Add recordings to, reorder, or remove items from a playlist' that precisely scopes the tool's function. It then explicitly lists the three supported actions (add, move, delete) and provides corresponding endpoints, making it easy to distinguish from sibling tools like manage_playlist (which likely handles playlist metadata) and get_playlist. The purpose is unambiguous and specific.

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 clearly outlines the three actions and their parameter requirements, indicating when to use each. It does not explicitly state exclusions (e.g., 'use manage_playlist for playlist creation'), but the action breakdown provides strong contextual guidance. Authentication requirements are mentioned, and the distinction between this and other tools is implicit in the naming and scope.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals authentication needs, the required mbids for get_recordings, the 75-item URL length limit, and the fact that the upstream 400s without mbids. It does not discuss rate limits or side effects beyond these, but the coverage is strong for a multi-action tool.

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

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

The description is dense and front-loaded with the purpose, then organized by endpoint. Every sentence carries necessary information, including the gotcha about plural vs. singular paths. It is long but warranted given the tool's complexity; it could be tightened slightly but remains well structured with line breaks for readability.

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, 0% schema coverage, and an output schema present, the description covers all essential operational context: parameter constraints, required fields per action, authentication, failure modes, and path discrepancies. An agent has enough information to call this tool correctly without external docs.

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 0%, so the description must fully explain the parameters. It does so comprehensively: it defines action options, enumerates valid rating values (love/like/hate/dislike/bad_recommendation), explains recording_mbid for submit and delete, user_name for get_user/get_recordings, the count/offset defaults and ranges, and the mbids format (comma-separated, max 75). It adds meaning far beyond the bare 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 clearly states the tool submits, deletes, or reads recommendation feedback, and enumerates the exact endpoints and actions. It distinguishes this from sibling tools (e.g., manage_recording_feedback) by specifying the recommendation context. The wording is specific and actionable.

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 explicit guidance for each action, including authentication requirements (submit/delete need auth) and a critical warning that the OpenAPI spec's plural paths are incorrect (404). It also gives the conditions for using get_recordings (requires mbids) and notes upstream failure modes, leaving little ambiguity about when and how to invoke each action.

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?

With no annotations present, the description carries the full burden of behavioral disclosure. It explicitly states that submit and import require authentication upstream, reveals that get_bulk is deliberately not exposed via GET due to URL-length middleware causing 502s, and clarifies that import's user_name is the username on the external service (lastfm/librefm), not a ListenBrainz name. It even references a live probe and upstream contract lines, demonstrating deep transparency about real-world behavior and pitfalls.

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?

Although the description is long, it is densely packed with critical information and organized logically: first a one-line summary, then a mapping of endpoints to actions, then per-action parameter details. Every sentence adds value—there is no filler. The front-loading of the summary and the clear action breakdown make it easy for an agent to parse despite the length, and the complexity justifies the verbosity.

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 complexity (9 parameters, 6 actions, multiple endpoints), the description is fully complete. It covers all parameters, explains per-action requirements, discloses authentication needs, identifies potential failures (e.g., URL-length 502s), and corrects upstream documentation errors. An agent has everything needed to select and invoke the correct action without external lookup. The existence of an output schema is acknowledged (not shown) but not required to explain return values, so no gap exists.

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 0%, so the description must fully explain all parameters and it does. For each action it details which parameters are required, optional, and their constraints (e.g., score ∈ {1, -1}, count 1..1000, offset non-negative). It also clarifies semantic nuances such as mbids being MBIDs on the wire as recording_mbids, and that the import action takes no feedback items. This goes far beyond the raw schema, making the parameters self-explanatory.

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 clear, specific summary: 'Submit or read recording (love/hate) feedback.' It then enumerates all six endpoints and their corresponding actions, making the tool's scope unambiguous. It differentiates from sibling tools (e.g., manage_recommendation_feedback) by focusing specifically on recording feedback, so an agent can instantly place it.

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 provides exhaustive usage rules per action: for submit, it mandates exactly one of recording_mbid/recording_msid plus a score of 1 or -1; for get_for_user it specifies required user_name, optional score filter, count range, and offset default; for get_bulk it explains why only the POST variant is exposed (the GET twin fails over ~75 items). It also warns about the OpenAPI spec's incorrect spelling for get_for_msid and instructs not to 'fix' it. This is model guidance for when and how to use each action.

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?

No annotations are provided, so the description carries the full burden and largely meets it. It discloses that unset flair sends null and REMOVES the current flair, that arbitrary args are ignored per action, that unknown brainzplayer keys are rejected, and even notes the MCP-layer boolean coercion quirk and that upstream's type-check is the authoritative rejection layer. This is rich, candid behavioral context.

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

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

The endpoint map is front-loaded and highly scannable, followed by per-action parameter breakdowns. Every block earns its place. It is dense, and the Round-3 QA note about coercion is arguably tangential for an agent, but it is organized enough that the length is justified rather than padded.

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 5-parameter tool spanning four distinct actions with an output schema present, the description is nearly complete: it covers required args, defaults, removal semantics, rejection behavior, and per-action valid keys. The only small gap is that it doesn't describe the response/return shape, though the presence of an output schema mitigates that.

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 0%, so the description must compensate, and it does thoroughly. It enumerates all valid flair values, documents zonename's required format (Europe/London), clarifies export_to_spotify as a boolean Troi preference, and lists the full set of valid brainzplayer_prefs keys plus dataSourcesPriority. The schema itself has only titles/defaults, so the description is the sole carrier of meaning.

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

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

The description states a specific verb and resource (update the authenticated user's settings) and maps out four distinct endpoint/action combinations. It is easily distinguished from every sibling, none of which touch user settings (siblings cover listens, playlists, feedback, pins, follows, timeline, etc.), so an agent can select it without ambiguity.

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 action-based routing is explicit: each action maps to a specific endpoint and the required vs optional args per action are spelled out (zonename required for timezone, export_to_spotify for troi, etc.). It states the authentication precondition (acts on the token's owner) and that irrelevant args are ignored per action. It doesn't give explicit 'when not to use' guidance, but no sibling overlaps meaningfully, so alternatives need no exclusion.

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?

With no annotations provided, the description carries the full burden and does a good job: it discloses authentication requirements, upstream restrictions (approved playlist bots, linked account, token owner match), and the mutating nature of actions (delete, hide, etc.). It does not mention reversibility or side effects (e.g., whether hidden events can be unhidden later), which would be valuable, but the information given is sufficient for safe invocation.

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 deliberately organized: it starts with a one-line summary, lists endpoints grouped by action, then provides per-action parameter requirements. Each sentence adds specific value; there is little fluff. For a 15-parameter tool with 0% schema coverage, this level of detail is justified. It could be slightly tightened, but the structure aids comprehension.

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 complexity (15 parameters, 0% schema coverage, no annotations) and the presence of an output schema (so return format is not needed), the description is quite complete. It covers all actions, their required parameters, authentication constraints, and upstream limitations. Missing details like error handling or rate limits would be nice but are not essential for correct invocation, and the output schema covers the response.

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 0%, so the description must compensate. It effectively maps parameters to actions: e.g., create_recording documents recording_mbid/recording_msid, delete_event documents event_type and event_id, create_review documents entity_name/entity_id/entity_type/text/language. It also enumerates allowed values for event_type in some actions. It does not explain every parameter's format or constraints (e.g., 'users' list behavior), but it covers the essential meaning for all actions, which is strong given the tool's complexity.

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 clear statement of purpose: 'Create timeline events, or delete/hide/unhide/thank feed events.' It names the resource (timeline/feed events) and the specific verbs (create, delete, hide, unhide, thank). The list of endpoints and actions makes the scope explicit and distinguishes this from siblings like get_feed (read-only) and manage_pins (different resource).

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 provides detailed per-action usage requirements, such as which parameters are required for each action and upstream restrictions (e.g., token owner match, approved playlist bots, linked CritiqueBrainz account). It does not explicitly state 'when to use this tool vs. alternatives,' but the action breakdown makes it clear this is the tool for timeline event management, and sibling tools like manage_pins or get_feed are obviously separate concerns. A brief note on when to prefer another tool would push this to 5, but it is already quite actionable.

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?

With no annotations, the description carries the full burden. It states the operation returns an ok response, which implies read-only behavior, but does not mention authentication, rate limits, or any side effects. For a trivial health check, this is minimally sufficient but lacks depth.

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 extremely concise—a single sentence that covers the purpose and expected output. It is front-loaded and wastes no words, exactly as appropriate for a ping endpoint.

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 has no parameters, a straightforward output, and an output schema (as indicated by context signals), the description is fully sufficient for an agent to call it correctly. Nothing essential is missing.

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

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

The tool has zero parameters, so the baseline of 4 applies. There is nothing for the description to add about parameters, and the empty input schema confirms this.

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 performs a health check and returns a simple ok response. It is unambiguous and specific, though it does not explicitly differentiate from the sibling get_service_status, which likely provides more detailed service information.

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?

No guidance is provided on when to use this tool versus get_service_status or other siblings. The description does not mention any context, prerequisites, or exclusions, leaving the agent to infer usage.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals the exact endpoint, the clamping of page_size to 100, the default of 25, and the critical trailing-slash requirement (including a probe date and consequence of slashless spelling). This goes beyond basic expectations for a read-only search tool.

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

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

The description is compact and front-loaded with the purpose. The trailing-slash note is slightly verbose but essential. No redundant sentences detract from the content.

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 that an output schema exists, return-value details are omitted appropriately. The description covers the endpoint, parameter semantics, and a critical URL quirk. It lacks explicit error-handling or timeout behavior, but these are minor for a simple search operation.

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 0%, so the description must compensate for the schema's lack of documentation. It fully explains both parameters: search_term ('text to search for') and page_size ('results per page, clamped to at most 100 (default 25)'), adding meaning beyond the raw schema types and default.

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 'Search ListenBrainz users by name,' stating a clear, specific verb and resource. It unambiguously distinguishes this from sibling search-like tools (e.g., get_similar_users) by focusing on name-based searching.

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 does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. The purpose is self-evident for name searches, but no guidance about when interchanging with other user-related tools might be appropriate is given.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose meaningful behaviors: the practical limit of 1000 listens in import mode, the precedence of clear_playing_now over other args, and the endpoint distinction. It stops short of detailing authentication requirements, error responses, or side effects beyond the immediate operation, leaving some important behavioral context unspecified.

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 yet economical. It leads with the core purpose, then lists endpoints and parameters in a structured, scannable way. Every sentence adds value: no filler, no repetition of schema fields verbatim, and the most important constraints (import limit, precedence) are highlighted. The format uses short lines and logical grouping, making it easy for an agent to parse.

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 complexity (four parameters, three modes, two endpoints, an output schema), the description is largely complete. It covers the API endpoints, parameter semantics, constraints, and mode behavior. The output schema covers return values, so no need to describe those. Minor gaps include explicit authentication requirements and error conditions, but overall the description provides enough context for correct invocation.

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 0% (no descriptions in the input schema), so the description must explain all parameters. It does so thoroughly: it defines the allowed values for listen_type, describes the structure of each listen dict (listened_at, track_metadata with track_name and artist_name), explains that listened_at is not used for playing_now, clarifies return_msid's purpose, and details clear_playing_now's effect and precedence. This fully compensates for the sparse 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 a precise verb-resource pair: 'Submit listens to ListenBrainz' and explicitly names the three submission modes ('single', 'playing_now', 'import') plus the delete action ('or delete the user's currently-playing track'). It also names the concrete HTTP endpoints, which removes ambiguity about the tool's scope and distinguishes it from sibling tools that read or manage listens in other ways.

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 using the tool: it explains when to use 'clear_playing_now' instead of submitting ('instead of submitting, POST to /1/playing-now/delete') and that it 'takes precedence over listen_type/listens'. It also specifies the import limit (at most 1000 listens) as a usage constraint. However, it does not explicitly contrast this tool with sibling tools like 'manage_listen' or 'get_listens', so the when-to-use-this-vs-alternative guidance is only internal.

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 are absent, so the description carries the behavioral burden. It discloses the authentication requirement ('auth-required upstream') and specifies the exact request body format ('Body is sent verbatim as {...}'), which goes beyond the schema. However, it does not mention side effects (e.g., whether existing mappings are overwritten), error scenarios, or rate limits. Given it is a mutation tool with no annotation support, the disclosure is partial but not minimal.

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 compact, with no wasted words. It leads with the purpose, then the endpoint, and then the parameter explanations. Every sentence adds value, and the structure is easy to scan.

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 simple two-parameter tool, the description covers the necessary information: purpose, endpoint, parameter semantics, and authentication. An output schema exists, so return values are presumably documented there. It could mention whether the mapping must not already exist, but that is not critical for a basic call. The description is adequate for an agent to correctly invoke the 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 description coverage is 0%, meaning the parameters have no descriptions in the schema. The description fully compensates by explaining both: 'recording_msid — the MessyBrainz ID; recording_mbid — the MusicBrainz ID it should map to'. This gives the agent complete semantic understanding of each parameter.

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: 'Submit a manual MSID→MBID mapping'. It names the specific resource (manual mapping) and distinguishes it from the sibling get_manual_mapping, which is a retrieval operation. The purpose is unambiguous.

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

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

The description implies this is a write operation (submit) for creating mapping, and the sibling get_manual_mapping reads mappings. However, it does not explicitly name the alternative or state when to use one over the other. It also mentions 'auth-required upstream', which gives context. Overall, clear usage context but no explicit exclusions or alternatives.

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?

With no annotations provided, the description carries full burden. It discloses that the tool sends the server's configured token to upstream and returns the verdict verbatim including exact fields, which clarifies the read-only nature (GET request, returns a verdict without side effects). It does not explicitly state 'no modifications', but the semantics strongly imply a safe validation operation.

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 short sentences: endpoint, behavior, and limitation. Every sentence adds value—the endpoint, the exact response structure, and the constraint. No filler, and the key points are front-loaded.

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 zero-parameter tool with a clearly stated response format and scope, the description is complete. The output schema exists and likely mirrors the described fields, so no additional return-value explanation is needed. All necessary information for an agent to call and understand the result is present.

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?

Since there are zero parameters, the description does not need to elaborate on them. The tool has no parameters, and the description correctly omits any parameter guidance. Baseline for 0 params is 4, and the description adds no irrelevant information.

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 a specific verb+resource: 'Validate the ListenBrainz auth token configured on THIS server.' It clearly distinguishes scope from siblings by noting it validates the server's own token only, which is distinct from 'ping' or 'get_service_status'. The end-to-end behavior (sending the configured token and returning the verdict) is precisely stated.

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 frames the tool as a 'health check for the server's credentials' and clarifies that it cannot validate any other token, which informs when NOT to use it. However, it does not name specific sibling alternatives or give explicit when-to-use vs when-not-to-use scenarios beyond the token scope limitation.

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