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

Annotations already declare a safe read-only, closed-world operation, and the description goes well beyond them: it discloses the 'feasible' boolean and 'max_achievable_display' return semantics, plus a refusal protocol and a presentation rule (never surface or convert millisecond figures). That is real behavioral context an agent could not infer from readOnlyHint alone.

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

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

Front-loaded with the core purpose and the sequencing rule, and most sentences add distinct policy. The refusal paragraph slightly over-enumerates ('do not build a playlist anyway, do not relax the constraint yourself, and do not try alternative track combinations'), which are three phrasings of one instruction.

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 six-parameter, no-output-schema tool the usage and refusal policy are complete, but the description omits any explanation of the parameter formats an agent must supply, which is the main remaining risk. It explains two return fields but not the full result shape.

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 carries the full burden for six parameters, yet it never explains any of them. It is ambiguous whether released_after/released_before are years or epoch timestamps, and units for max_track_duration_ms and min_total_duration_ms are only obliquely implied by the millisecond warning.

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

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

States a specific verb and resource ('check whether a playlist brief is possible') and positions it temporally ahead of track selection, which distinguishes it from query_library and validate_playlist. An agent knows immediately that this is a pre-flight gate, not a builder or validator.

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

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

Explicit when-to-call ('first, before query_library, whenever the user asks for a playlist with constraints'), explicit when-not ('a brief with no constraints at all cannot be checked — ask them before calling'), and explicit failure behavior ('tell the user which constraint fails and stop', 'do not relax the constraint yourself'). Alternatives and exclusions are both covered.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing the data sources (MusicBrainz, Wikipedia), the grounding contract (answer only from returned passages, refuse otherwise), and the citation protocol required in the reply. These are response-shaping rules the annotations cannot convey.

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

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

Front-loaded with purpose, then usage, then output contract, then sibling routing. Every sentence adds an actionable rule; nothing is redundant with the schema or annotations.

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?

No output schema exists, and the description supplies the return shape ('passages ... that best match the question') along with the id format used in citations. An agent has everything needed to call it and to post-process the result correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: 'artist' is clarified as the name and 'question' as the user's question, which implies phrasing the question in natural language rather than keywords. It stops short of format examples or naming conventions for the artist string.

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

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

States a specific verb and resource ('look up background on one artist ... from published sources') and names the sources. The final sentence explicitly separates it from query_library, so an agent can route without opening the schema.

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

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

Gives an explicit trigger ('any question about an artist's history, members, origins, influences or career') and an explicit exclusion plus alternative ('This tool knows nothing about the user's tracks. Use query_library for those.'). Both when and when-not are covered.

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

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

Annotations already establish read-only and non-destructive behavior, but the description adds substantial behavioral context beyond that: the tracks list is truncated to limit, totals are computed exactly, ordering is computed server-side, energy is an estimate with provenance, and genre fallback is available. These details materially change how an agent should interpret and present results.

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 action and key rules, and most sentences carry actionable guidance. It is somewhat long and repeats the same anti-estimation theme across multiple sentences, which costs some conciseness, but the structure remains purposeful.

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?

There is no output schema, so the description appropriately explains key return fields such as total_matching, total_duration_ms, tracks, duration_display, and energy_provenance. However, for a 9-parameter tool with 0% schema description coverage, it leaves important input filters undocumented, so the overall context is only partially 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 description coverage is 0% and there are 9 parameters, so the description must carry the burden of explaining them. It adds meaning for order_by values, genre fallback behavior, and limit truncation, but it does not explain artist, played, released_after, released_before, min_duration_ms, or max_duration_ms, leaving more than half of the parameters undocumented.

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: search the user's music library and return matching tracks with totals. It is immediately distinguishable from the sibling tools validate_playlist, enrich_artist, and check_feasibility, 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?

It gives explicit usage rules: call before stating any fact about the library, never estimate counts or durations, use total_matching and total_duration_ms, and pass order_by for longest/shortest/highest/lowest queries. It also explains the genre fallback path and when to search again with known_genres. The guidance is unusually complete for an agent.

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

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

Annotations already establish that this is a safe read (readOnlyHint=true, destructiveHint=false), and the description adds substantive behavior the annotations cannot convey: violation records carry track ids and a signed adjust_by in the constraint's unit, duration violations also carry adjust_by_display, and target_energy is scored rather than enforced. It also warns that energy is estimated and must be disclosed, which is a real behavioral constraint on downstream answers.

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 most important directive (what the tool does, and call it before presenting) is front-loaded, and every subsequent paragraph carries a distinct instruction: adjust_by semantics, verbatim quoting rules, cross-tool bound reuse, and energy caveat. It is on the long side for a nine-parameter tool, but no sentence is redundant.

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

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

With no output schema, the description has to sketch the return shape and it does: violations, adjust_by, adjust_by_display, soft_scores, track_count, total_duration_display. The remaining gap is the unmentioned constraint parameters, which an agent must guess from their names alone.

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 carries the full burden. It explains target_energy well (0-1 range, scored not enforced, soft_scores output) and gives intent for released_after/released_before by tying them to check_feasibility, but required_genres, max_total_duration_ms versus min_total_duration_ms, max_track_duration_ms, and max_tracks_per_artist are never mentioned — half the parameters remain opaque.

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

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

States a specific verb and resource (check a proposed playlist against hard constraints) plus the scope of the output (report every violation). It implicitly separates itself from check_feasibility by instructing the caller to reuse the release-year bounds given to that sibling, so an agent can tell the two apart.

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

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

Explicit temporal gating ('Call this before presenting any playlist', 'Do not judge for yourself'), an explicit cross-tool dependency ('Pass the same release-year bounds you gave check_feasibility'), and an explicit conditional trigger ('If the user asks for an energy level or a mood, pass target_energy'). Nothing is left to inference.

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