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

With no annotations, the description carries the full behavioral burden, and it does disclose the internal mechanics: the mood vector, which of three source layers produced it, the nearest named moods, and the mood last served against. It stops short of stating error behavior (e.g., what happens if the song was never recommended) or confirming it is side-effect-free.

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 in the first clause, followed by one sentence enumerating what is reported. No filler, no repetition of the tool name.

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

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

For a read-only explanatory tool with an output schema present, the description need not restate return formats and is complete enough to call correctly. The only real gap is the undocumented video_id, which is minor given the output schema carries the result contract.

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% for the single required video_id, and the description never mentions it, so it adds no meaning beyond the bare property name. The parameter is fairly self-evident, which keeps this from being a 1, but the description does not compensate 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?

States a specific verb and resource ('Explain why a song was recommended') and scopes it to mood terms. This clearly separates it from the action-oriented siblings like recommend_from_song and recommend_from_playlist, which produce recommendations rather than explain 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?

Usage is implied: call this after a recommendation exists to understand its basis. There is no explicit when-to-use, no statement of prerequisites (e.g., must the song have been recommended?), and no routing to alternatives among the ten 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 must carry the behavioral burden, and it does reasonably well by disclosing exactly what the report contains and how to interpret low coverage (ranking on signal agreement rather than mood). It never explicitly states the operation is read-only or side-effect-free, which leaves one gap.

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 core purpose is front-loaded in the first sentence and the rest adds diagnostic meaning. A few phrases ('gaps are visible not silent', 'worth saying out loud') are stylistic flourishes that could be trimmed, but the passage stays short.

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

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

Given an output schema exists and there are no parameters or annotations, the description supplies enough conceptual context to know what the report conveys and why it matters. It stops short of describing invocation conditions, but little else is needed for a no-arg diagnostic.

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 takes zero parameters, so per the rubric the baseline is 4. There is no parameter syntax to document and the description introduces none.

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 ('Report how much of the mood index exists') and enumerates the scope it covers (crawl coverage, labelled library layers, Claude-labelling config). This clearly separates it from all siblings, which are recommendation, retrieval, or mutation 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?

Usage is only implied: the tool exists to surface index gaps and the description notes the implication of low coverage for recommendations, which hints at when it's worth calling. But there is no explicit 'use this when...' instruction or contrast with alternatives like refresh_library.

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 well: it discloses the epistemic limits of the tool ('mood inference is often wrong'), instructs that the result be presented as correctable, and names the concrete signals used. It omits anything about latency, caching, or how much history is scanned, but the fallibility disclosure is unusually valuable context.

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

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

Front-loaded with the core purpose, then the return shape, then the interaction rule. The quoted example earns its space by encoding tone, though the enumeration of return fields partially duplicates the output schema and could be trimmed.

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

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

For a zero-parameter tool with a rich output schema and no annotations, this covers purpose, output framing, and the key caveat about unreliable inference. The only real gap is not routing the agent to the mood-recommendation siblings when the user actually wants a suggestion.

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 takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing input semantics.

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 — infer the listener's current mood from recent listening — and frames it as an evidence-backed read, which cleanly separates it from the recommendation siblings (recommend_for_mood, recommend_from_playlist_for_mood). An agent can tell what this returns without opening the output 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?

It gives clear interaction guidance (lead with evidence, offer the inference as a correctable read) but never says when to call this instead of, or before, recommend_for_mood. The when-to-use case is only implied by the conversational framing.

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 full behavioral burden and it does: declares READ-ONLY, guarantees results absent from library, discloses the strict language filter and the unlabelled-drop behavior, and explains the 25% filler cap with a concrete example (7 + 25 = 32). These are non-obvious traits an agent cannot infer elsewhere.

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

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

Front-loaded with purpose and organized under clear parameter headers, so it scans well despite its length. It is verbose and occasionally repetitive (the filler logic is restated in both `limit` and the result description), but nearly every sentence carries operational detail that would otherwise be missing.

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

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

With an output schema present the description need not explain return values, yet it still previews `target`, `seeds`, `match_quality`, and `notes` to tell the agent what to surface to the user. Combined with the alternative routing and the playlist hand-off, an agent has everything needed 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?

Schema description coverage is 0% and the schema has no enums, so the description compensates fully: it defines vector's four numeric dimensions with ranges and semantics, enumerates all eleven `context` values, documents each `arc` mode, and explains bpm_min/max biasing, language filtering, allow_unlabelled_language, and limit's ceiling-not-guarantee semantics. All 12 params gain meaning 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?

States a specific verb+resource ('recommend new songs that match how the listener actually feels') and immediately contrasts its seed-selection mechanism against recommend_from_song. An agent can distinguish it from every sibling 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?

Explicitly names when to switch: 'If they also point at a specific playlist ... use recommend_from_playlist_for_mood instead.' It also clarifies the multi-step playlist workflow (get songs here, create playlist, call refresh_library) and that this tool is not for building playlists directly.

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 so well: it discloses the sampling strategy (up to seed_sample_size random seeds), the pooling/ranking approach, and hard output guarantees (never returns songs in Liked Music, the source playlist, or any other playlist). It also flags a caching staleness risk and the refresh_library remedy, which is exactly the kind of behavioral caveat an agent needs before trusting 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?

Front-loads the one-line purpose, then layers mechanism, guarantees, and the caching caveat in short paragraphs; every sentence carries information. Slightly verbose in restating the multi-signal pipeline, but no filler sentences.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers seeding, exclusions, and cache behavior. The main gap is the unexplained `limit` parameter and no mention of failure modes for an invalid playlist_id, but overall it is sufficient 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?

Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It explains seed_sample_size concretely (random seed count, with whole-playlist fallback) and implies playlist_id's role, but never explains what `limit` (default 20) controls. Partial compensation only.

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?

Names a specific verb and resource ('Recommend new songs based on an entire playlist') and explicitly differentiates its mechanism from the sibling recommend_from_song ('runs the same multi-signal candidate generation as recommend_from_song for each, and pools/ranks'). An agent can distinguish it from recommend_from_song and recommend_from_playlist_for_mood without opening any schema.

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

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

Gives clear context for when this tool applies (you have a whole playlist rather than one seed song) and an explicit follow-up call ('call refresh_library() after adding songs to a playlist by other means'), which routes the agent to a sibling when the cache is stale. It stops short of an explicit 'use recommend_from_song when you only have one track' exclusion, so it is strong but not fully enumerated.

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 behavioral burden and does so richly: read-only guarantee, ~4 API calls per seed with a default cap of 20, seed_report contents (considered/genuine/capped), the fact that off-mood playlists legitimately yield few or no seeds rather than being papered over, exclusion guarantees, and the 25% filler ceiling on `limit`. This is exactly the cost/side-effect/auth context an agent needs.

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 one-line purpose and the routing rule before any internals, and every paragraph adds a distinct fact (contrast, cost/seed behavior, mood args, guarantees, read-only follow-up). It is long, and a couple of clauses ('same as recommend_for_mood') are mild repetition, but no paragraph is 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?

With an output schema present it correctly avoids re-describing return values while still flagging the meaningful `seed_report` field. For a 13-parameter, no-annotation, no-schema-description tool it covers behavior thoroughly, but the unaddressed bpm/language parameter family is a real completeness 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?

Schema description coverage is 0%, so the description must compensate and it only partially does. It clarifies vector>feeling>context precedence, arc's shaping role, seed_cap, and limit's ceiling semantics, but 13 parameters exist and bpm/bpm_min/bpm_max, language, exclude_languages, and allow_unlabelled_language are never addressed beyond their self-evident names.

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

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

States a specific verb+resource+scope: 'Recommend new songs from ONE playlist, shaped by how the listener feels.' It explicitly contrasts itself with both closest siblings (recommend_from_playlist and recommend_for_mood) and names the distinguishing dimension (mood presence, playlist specificity).

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

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

Gives explicit routing rules: 'Use this over recommend_from_playlist whenever a mood is part of the ask, and over recommend_for_mood whenever a specific playlist is,' plus a concrete user-facing trigger ('I feel like this -- look at this playlist and find me songs'). It also explains the follow-up workflow (pass videoIds to a playlist tool, then call refresh_library()).

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 so: it discloses the multi-signal ranking strategy, that the seed song is never returned, exclusion of Liked Music and all playlists, the default cross-artist behaviour, language-filter strictness with allow_unlabelled_language escape hatch, and the response shape with notes. It even flags a cache-staleness behaviour and the refresh_library() remedy — exactly the kind of non-obvious trait annotations would normally supply.

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?

Purpose and the required-argument rule are front-loaded, and essentially every sentence adds a distinct behavioural fact, so length is largely justified. A few conversational asides ('which is the point:') and repeated restatements of the language-filter rationale could be trimmed without losing information.

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

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

An output schema exists so return values need not be re-explained, and the description nonetheless names the response keys and the role of `notes`. Combined with the mutual-exclusion rule, filter semantics, and the cache/refresh_library dependency, an agent has everything needed to call this 14-parameter 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?

Schema description coverage is 0% across 14 parameters, so the description is the only source of meaning, and it explains the semantics of most of them: video_id vs song mutual exclusion, artist narrowing, language/exclude_languages independence from the seed, allow_unlabelled_language, expand_across_language, same_artist_only, and match_seed_tempo/bpm/bpm_min/bpm_max including the half/double-time and missing-BPM cases. It leaves `limit` and `max_per_artist` (the default of 2) 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 first sentence gives a specific verb and resource ('Recommend new songs similar to a seed song'), which cleanly separates it from the playlist- and mood-seeded siblings by seeding resource. It never names those siblings explicitly, so an agent must infer the routing from the resource noun rather than being told.

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?

Strong in-scope guidance: exactly one of video_id or song must be given, with a worked example ('10 songs that relate to Kryptonite by 3 Doors Down'); it also explains when same_artist_only, language filters, and expand_across_language apply. It does not, however, compare itself against the sibling tools (recommend_from_playlist, recommend_for_mood), so the agent gets no explicit alternative 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 carries the full burden. It does disclose a meaningful system effect -- 'Anything marked skipped or wrong_mood is never recommended again' -- which is durable state change worth knowing. However, it omits idempotency, auth/permission needs, error behavior, and whether feedback can be changed after recording.

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?

Short and front-loaded: purpose first, then the allowed values, then the consequence. Every sentence carries weight, though the sentimental framing of 'the valuable one' is mildly editorial rather than operational.

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?

An output schema exists, so return values need not be described, and the reaction semantics are covered well. The one gap is the undocumented required `video_id` and no statement of the recording's persistence or reversibility, which leaves the agent guessing on a required field.

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 enumerates and interprets the `reaction` values, which the schema does not (no enum). But `video_id` is never explained -- the agent must infer where a video id comes from -- leaving half 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+resource ('Record what the listener thought of a recommendation'), making it a feedback sink that is easily distinguished from the sibling recommender tools. It does not explicitly name siblings, but 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?

Use is implied by the recommender sibling set (call this after a recommendation is consumed), and it hints at the value of one reaction type. There is no explicit when-to-use, when-not, or routing to alternatives such as explain_recommendation.

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 so well: it discloses the ~20s build cost, that the result is cached and reused, and that the effect is only otherwise visible after a cache TTL. It also clarifies the incremental freshness rule (likes immediate, playlist adds deferred), which is non-obvious and directly affects whether the agent should call it.

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 action is front-loaded in the first sentence and each subsequent sentence adds real information (cost, cache semantics, call condition). The cache-economics paragraph is slightly more expansive than strictly needed, but it is not wasted.

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?

An output schema exists, so return values need not be described. For a zero-parameter maintenance tool, the description covers the why, the cost, the caching model, and the precise call condition, leaving no material gap for an agent deciding whether to invoke it.

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?

There are zero parameters, so the baseline is 4 and there is no parameter syntax for the description to clarify. Nothing is missing, but there is also no opportunity to add semantic value here.

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?

Names a specific verb and resource ('Rebuild the cached library exclusion set') and immediately explains its relationship to the sibling recommendation tools, which all consume this set. An agent can distinguish this maintenance tool from recommend_* siblings without opening any schema.

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

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

States the exact trigger ('Call this after adding songs to a playlist by other means') and explicitly contrasts it with the case where it is unnecessary, since liking a song is already picked up immediately. It also names the alternative workflow (a playlist-management tool) that creates the need.

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 burden. It discloses read-only behavior ('never adds results anywhere'), the exclusion set semantics (Liked Music OR any playlist), the hard requirement that it returns fewer than limit rather than padding, and the variant-collapsing behavior. It does not state auth/permission requirements or rate limits, so not a 5.

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?

Multi-paragraph but front-loads the core purpose and sibling differentiation first, then layers in exclusion behavior, shortfall semantics, variant collapsing, and caching. Each paragraph earns its place, though some detail could be trimmed.

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

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

The tool has an output schema, so return-value explanation is largely unnecessary, yet the description references result fields ('found' vs 'requested', 'variants_collapsed') to clarify semantics. Covers exclusion behavior, caching caveat, and refresh_library guidance. Could still note artist-resolution failure behavior, but is largely 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%, so the description must compensate. It explains 'artist' is a name resolved to a YouTube Music channel and mentions 'limit' as a qualifying-songs count, adding real meaning. But it does not specify limit bounds, defaults effect, or exact artist-matching semantics, leaving gaps for a 0%-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?

States a specific verb+resource ('Return actual songs by a specific artist -- a direct catalog pull') and explicitly distinguishes itself from siblings by contrasting with similarity recommendations like recommend_from_song/recommend_from_playlist. The direct-catalog-pull framing makes it unmistakable.

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

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

Explicitly contrasts this tool with recommend_from_song and recommend_from_playlist, and clarifies the exclusion scope differs from recommend_from_playlist's single-seed-playlist exclusion. It also instructs when to call refresh_library(). Strong when-to-use guidance.

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