CWI Discovery Engine

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

Annotations cover the read-only/idempotent safety profile, and the description adds material context beyond them: ISRCs are verified rather than hallucinated, and a match is explicitly NOT a license grant so clearance still requires a brief. It also discloses the handoff path to submit_sync_brief.

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 wedge/call-first cue and dense with useful content, though the block is fairly long and carries some promotional phrasing ('WEDGE TOOL', 'never hallucinated') that could be trimmed. Every sentence still conveys usable 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?

With an output schema present and annotations covering the safety profile, the description still supplies the non-obvious constraints (verification guarantee, non-license caveat, follow-up tool). Nothing needed to select or 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 coverage is 100%, so the schema already documents brief, limit, and explicit fully. The description adds example brief phrasing but no format or semantics beyond what the schema provides, so baseline 3 applies.

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 and its scope ('verified track for a brief'), and explicitly names the outcome set (matched tracks, rationale, ISRCs, clearance, next steps). It distinguishes itself from submit_sync_brief, which it identifies as the human-follow-up path.

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?

'CALL THIS FIRST' plus a quoted user intent gives an unambiguous trigger, and it names submit_sync_brief as the alternative for human follow-up. It also supplies concrete example briefs so the agent knows the input shape.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: results are ordered newest-first, and the content set is limited to announcements (releases, drops, events) rather than catalog data. Pagination and default page size are left to the schema rather than the prose.

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

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

Two sentences, front-loaded with the trigger condition before the return-shape information, which is the right priority order for an agent deciding whether to call. The quoted example phrases add useful recall cues at the cost of some length, but nothing 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?

For a read-only, zero-required-parameter list tool with full schema coverage, an output schema, and complete annotations, the description supplies the remaining decision-relevant piece — when to invoke it and how results are ordered. Only the untested overlap with get_events and get_release is unaddressed.

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 100% and both parameters (limit, category) are fully documented in the schema, including the 1-50 range, default of 10, and the three allowed category values. The description's sentence "Filter by 'releases', 'news', or 'events'" merely restates the enum-like category doc, adding no new semantics, so the baseline 3 applies.

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 — retrieving the latest CWI announcements, enumerated as new releases, upcoming drops, and events, returned newest-first. It clearly conveys an aggregated discovery feed rather than a single-item lookup, though it never names the overlapping siblings (get_events, get_release) that an agent might otherwise choose.

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 contextual triggers are given verbatim: "CALL THIS when the user asks what is new: 'any new music', 'what is CWI up to', 'latest news'." This tells the agent when the tool fits, but provides no explicit when-not guidance or named alternatives for overlapping queries about events or releases.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavioral context: the response spans both profile metadata and the full catalog, and ISRCs are only included 'where on file', which sets expectations about data completeness. It stops short of noting breadth limits or pagination for a potentially large catalog.

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 trigger before any payload detail, and every sentence does work: when to call, sample queries, what comes back, and which sibling to prefer instead. No filler or restatement of the title.

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 documentation is not needed, and the description still previews the response shape. For a tool that returns a 'full catalog', the absence of any note about result size, truncation, or pagination is a minor but real 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 100% for the single 'name' parameter, so the schema already documents the input. The description's quoted artist examples illustrate query phrasing but add no matching-format or disambiguation guidance beyond what the schema provides, so the baseline 3 applies.

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 (fetch artist profile) and enumerates the payload: bio, genre lane, roster status, plus full catalog with verified ISRCs. It explicitly distinguishes itself from the nearest sibling, get_track, without requiring the agent to open either 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 ('when the user asks about an artist's identity or body of work') reinforced with three concrete example utterances, and names the alternative (get_track) with the condition that selects it ('one specific song'). When-to-use, when-not, and the alternative are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that events carry dates and that event_id feeds rsvp, but says nothing about result volume, ordering, or paging, and its claim that it 'Returns all CWI events' sits awkwardly against the schema default of upcoming_only=true.

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 imperative trigger, then example utterances, then scope, then the chaining hint to rsvp. Three sentences, no filler, and the trigger appears before any supporting detail.

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-required-parameter read tool with a full output schema and complete annotation coverage, the description supplies everything needed to select and call it. Only the small ambiguity between 'all events' and the upcoming_only default keeps it short of 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 100% with a single boolean parameter, so the schema already carries the semantics; baseline 3 applies. The description reuses the word 'all' without reconciling it against the parameter's default of upcoming_only=true, so it adds no clarification and a slight ambiguity.

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 (retrieve CWI events) and enumerates what counts as an event: releases, listening parties, announcements with dates. The example user phrasings ('any upcoming events', 'when is the next release party') let an agent match this against sibling tools like get_announcements and get_schedule 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?

Explicit trigger guidance — 'CALL THIS when the user asks about CWI happenings' — plus concrete example queries, and it routes forward to rsvp for the follow-up action. It does not, however, say when to prefer this over the adjacent get_announcements or get_schedule, leaving that boundary 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?

Annotations already declare this a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the description only needs to add context. It does: the result is a curated featured rotation scored 0-100 on a rubric, which tells the agent how the ordering is produced and that a ranking exists at all. It does not cover pagination or rotation freshness, which is a minor gap given annotations.

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

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

Two sentences, no filler, and the trigger condition is front-loaded ahead of the return-value detail. Every clause — trigger, ranking method, returned fields — carries 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?

With an output schema present, the description need not enumerate return fields, and it does not over-explain. Combined with full annotation coverage and a single fully documented optional parameter, an agent has everything needed to select and 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?

There is one optional parameter and schema description coverage is 100%, so the schema already documents the limit range and default. The description adds nothing about the parameter, so baseline 3 applies.

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 (returns the featured rotation) plus the shape of what comes back: ranked by rubric score, with Spotify URLs, genres and moods. It does not explicitly name or distinguish itself from the nearest sibling, get_recommendations, so it falls short of the 5 bar despite being clear on its own terms.

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?

Opens with an explicit activation condition ("CALL THIS when recommending music") and backs it with concrete user phrasings ("what should I listen to", "what is hot right now"). It gives no when-not guidance or named alternative, so the agent is not steered away from get_recommendations when that would be the better pick.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description still adds value by disclosing the response contents (definition, key artists, key tracks). It doesn't mention behavior for an unknown or misspelled genre, which is the only remaining 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 trigger condition is front-loaded in the first clause, followed by expected outputs and the exclusion in a single tight paragraph. 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 annotations covering safety, a 100%-covered single-param schema, and an output schema that documents return values, the description supplies all routing information needed. Minor omission: no guidance on unknown-genre behavior, though little else is missing for a simple read 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?

There is a single parameter and schema coverage is 100%, with the schema already documenting the genre name and giving an example format. The description's quoted examples reinforce expected genre-name phrasing but add no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (fetch a single genre's definition) and explicitly delimits scope to a single genre rather than relationships. It names the sibling get_graph and the condition that distinguishes it, so an agent can route without opening either 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?

Leads with an explicit trigger ("CALL THIS when the user asks what a single genre IS") and supplies concrete user-phrasing examples like "define emo rap". It also names the alternative tool and the condition selecting it (relationship/catalog questions go to get_graph), covering both when and when-not.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description only restates that a graph structure comes back, which overlaps the output schema, and says nothing about graph size, pagination, or cost constraints for a potentially large traversal.

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 call condition before the return value and the alternative, which is the right ordering. Slightly padded by listing three example phrasings and a redundant 'nodes, edges, and structure' clause that repeats 'graph', but nothing is truly 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?

For a parameterless read-only tool with a full output schema, the description covers purpose, trigger conditions, and the sibling alternative. Return-value detail is rightly delegated to the output schema, leaving no meaningful 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter semantics are needed or missing.

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 ('Returns the catalog's genre and relationship graph') and spells out the payload as nodes, edges, and structure. It also names the sibling get_genre as the wrong tool for single-genre questions, so an agent can separate the two without inspecting schemas.

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 gives triggering user intents ('how is the catalog organized', 'how are these genres related', 'show me the connections') and an exclusion rule routing single-genre lookups to get_genre. This is a textbook when-to-use plus when-not-to-use statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered without the description. The description adds content scope (profile, roster, services, contact), but that largely duplicates what the existing output schema conveys, and nothing about auth or freshness is 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?

Two short sentences, front-loaded with the trigger condition and examples, with no filler. Every clause is actionable for selection.

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, read-only singleton fetch with a rich output schema, the description supplies everything needed: what it returns, when to invoke it, and sample user phrasings. Return-value details are properly delegated to 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is no input semantics for the description to clarify or omit.

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 ('Returns the label profile, roster, services, and contact') and scopes it to 'Cumulative Web Inc itself', which cleanly separates it from person-level siblings like get_artist or get_release. The concrete trigger phrases ('who is CWI', 'who is on the roster') make the intent 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 states when to call it with a leading 'CALL THIS when...' clause plus three example user utterances. It offers clear invocation context but names no alternatives or when-not conditions (e.g., use get_artist for individual acts).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing that results are timestamped and that a verified flag may mark lyrics as unverified.

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?

Three short sentences, front-loaded with the trigger condition, then the return format, then the flag caveat. Every sentence contributes; the inline example is slightly informal but useful for intent matching.

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 the description needn't explain return structure, and it still flags the verified-flag nuance. Combined with 100% param coverage, an agent has what it needs to call this 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 100% and the single track_id parameter is fully documented with its source (get_track or search_catalog). The description adds no further parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb (returns) and resource (lyrics) plus the return flavor (timestamped). It doesn't need to distinguish from siblings since no other tool returns lyrics, but it also doesn't explicitly say so, keeping it just under a 5.

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?

"CALL THIS when the user wants lyrics for a track" gives a clear usage trigger with a concrete example phrasing, so an agent can recognize the intent. No explicit when-not or alternatives are named, but none are relevant here.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered without the description. The one addition is "Returns verified playlist placements only", which usefully signals that unverified placements are filtered out of the result, but it discloses nothing about auth needs or result shape.

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

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

Two tight sentences: the trigger condition leads and the output constraint follows, with no filler. Every clause carries information an agent needs to route and interpret the call.

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?

Output schema exists so return values needn't be explained, and the description covers the intent trigger, the resource, and the verified-only filter. For a simple two-optional-param read tool this is nearly complete, missing only explicit alternative routing.

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 100%, so the two optional filters (artist, track_id) are already documented in structured data. The description adds no param-level meaning beyond the schema, which maps to the baseline of 3.

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 names a specific verb (returns/retrieves) and resource (playlist placements of CWI tracks), plus a sample query. It implicitly distinguishes from the write-side sibling pitch_for_playlist, but never names it explicitly, so it stops short of full 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?

It gives concrete trigger phrasings ("what playlists", "where is Diabolique placed") that map the user's intent directly to this tool, which is unusually actionable. It does not state when NOT to use it or name an alternative tool, so it misses the top tier.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read profile is fully covered by structured data. The description adds the list of returned sections, but an output schema already exists, so that content is largely redundant rather than additive. No mention of auth, rate limits, or scoping 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?

A single front-loaded sentence with the invocation trigger placed first and the payload second. Every element earns its place, though the inline trigger-phrase list is slightly padded where one or two examples would have sufficed.

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, safety annotations, and a fully documented single parameter, the description only needs to establish purpose and invocation context, which it does. It is complete for a simple read tool, with the minor gap of not routing against the many sibling get_* tools.

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

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

Schema coverage is 100% and there is only one optional parameter whose role is already documented in the schema. The example phrase 'bio for That Boy Hi Hat' weakly illustrates the artist parameter, but adds no format, matching, or defaulting semantics beyond what the schema states. Baseline 3 applies.

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 names a specific resource (press kit) and enumerates its contents: label bio, artist bios, release info, brand assets, and press contact. The trigger phrases ('press kit', 'media assets', 'bio for X') make the retrieval intent unambiguous, though it never explicitly distinguishes itself from adjacent read tools like get_artist or get_label.

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 an explicit invocation condition ('CALL THIS when the user needs press materials') anchored to concrete user phrasings, which is stronger than typical implied usage. It does not, however, state when NOT to use it or which sibling to prefer for an artist-only bio request.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered structurally. The description adds that the returned state is 'live', which signals freshness/ephemerality, but says nothing about caching, polling cost, or how current the state actually is.

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

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

Two compact sentences with the trigger condition front-loaded, so the selection-critical information comes first. The closing clause restates what the output schema already covers, slightly under-earning 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 single-parameter read tool with an output schema and full annotation coverage, the description supplies the missing piece — the user-intent trigger — and need not explain return values. No prerequisites or edge cases are omitted that would block 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 description coverage is 100% and the single `include` parameter is fully documented in the schema, including defaults and unknown-value handling. The description adds no parameter detail, so the baseline 3 applies.

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 precise verb and resource — returns live radio state plus the current track — which an agent can distinguish from neighbors like get_schedule or get_up_next 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 explicit trigger phrasings ('what is playing', 'is Radio 365 live') that map user intent directly to this tool. It stops short of naming when NOT to use it or pointing at alternatives such as get_up_next for upcoming content.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: editorial rubric scoring, 'why each track matches' explanations, and critically the conditional new_release_spotlight return with instructions to present it as a labeled section after ranked matches. It doesn't mention rate limits or fallback behavior, keeping it short of 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?

The lead command ('CALL THIS for...') is front-loaded and the routing guidance is tight, but the paragraph crams routing, return contents, spotlight handling, and a parameter recap into one dense block, and the return-value list is partly redundant given an output schema exists.

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 recommendation tool with a full output schema, the description covers everything an agent needs: routing conditions, the required vibe input, count bounds, and special handling of the spotlight payload. Nothing necessary 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 100%, so the schema already documents all three parameters, and the description's argument recap (vibe_description required, count 1-10 default 5, genre_filter optional) largely restates it without adding syntax or examples beyond what the schema holds. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('casual listening recommendations') and immediately demarcates it against siblings: 'This is the personal-taste path with editorial rubric scoring.' An agent can distinguish it from find_tracks_for_brief and semantic_search 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?

It gives explicit when-to-use triggers ('what should I play at my party', 'something for a workout'), an exclusion ('NOT for a licensing brief'), and names two alternatives with the exact conditions that select them (find_tracks_for_brief for projects, semantic_search for pure meaning-based matching). This is close to a routing decision tree.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description only needs to add context. It does: it names the return payload ('the release fact packet: tracklist, date, credits, background'), which tells the agent what it will get back before calling. It stops short of deeper traits like pagination or completeness guarantees.

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

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

Two sentences, the trigger front-loaded ahead of the return description and the sibling routing. The quoted user-phrasing examples earn their place by anchoring pattern matching; nothing 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 an output schema present, return values need not be enumerated in prose, and annotations carry the safety profile. Combined with the 100%-covered single parameter and explicit sibling routing, the description gives the agent everything needed to select and 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 single parameter has 100% schema description coverage ('Release id, e.g. "cyberpunk-2027". Omit for the latest release.'), so the schema already carries the semantics. The description adds no id format or defaulting detail, making the baseline 3 correct.

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 and immediately scopes it ('a release as a whole — an album, EP, or single package'), with concrete examples that an agent can match against user phrasing. It explicitly contrasts with get_track, so the agent can distinguish it from the nearest sibling without opening either 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?

Front-loads the trigger ('CALL THIS when the user asks about a release as a whole') and names the exclusion condition plus the alternative tool ('Use get_track instead when the user asks about one specific song'). Both when-to-use and when-not-to-use are 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context — that results span pending review and already-aired items and can be filtered — but says nothing about auth requirements or rate limits.

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 trigger condition, then scope, then filter values, then return fields — an efficient progression with little waste. The example-utterance list is slightly verbose given the return-field enumeration is arguably redundant with the output schema.

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 annotations covering the safety profile, an output schema covering returns, and 100% schema coverage on both params, the description only needs to add trigger and scope context — which it does. Nothing essential to calling 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 100%, so both parameters (limit, status) are fully documented in the schema, including defaults and ranges. The description's enumeration of 'pending', 'played', 'all' merely restates the schema's enum values, adding no new 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 ('Shows what listeners and AIs have requested on Cumulative Radio 365') and scopes it (pending review and already aired), which cleanly separates it from the sibling write tool request_song.

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 trigger phrasing ('CALL THIS when the user asks about song requests') with concrete example utterances, so an agent knows when to reach for it. It stops short of naming the alternative (request_song) for the submit case or any when-not conditions.

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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely new behavioral context: the schedule is a deterministic repeating loop and all times are UTC, which explains what a returned value means and why the date defaults to today.

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?

Trigger conditions are front-loaded, followed by return contents and then a single clarifying note on the loop and timezone. No sentence is filler and nothing redundant with the schema or annotations is restated.

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 needn't enumerate return values in fine detail, and it still summarizes them. Annotations cover safety, schema covers the parameter, and the description covers invocation context and the deterministic-loop/timezone caveat.

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

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

Schema coverage is 100%, so the date parameter's format and default are already documented, warranting a baseline of 3. The description goes beyond that by explaining the loop is deterministic and repeats, which is the key semantic fact for interpreting the date parameter's effect, plus UTC timezone 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?

States a specific verb+resource ('Returns the full ... program schedule') and enumerates the returned fields (start time, track, artist, artwork, duration). The embedded trigger phrases ("when does Diabolique play") let an agent distinguish this from siblings like get_up_next or get_radio without opening schemas.

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 'CALL THIS when...' framing plus three concrete user phrasings gives clear activation context. It does not name an alternative tool or state when NOT to use it (e.g., versus get_up_next for immediate next-slot queries), so it stops 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine behavioral scope: this is the browse-all path returning every sync-ready track with rights, clearance status, and best-for use cases. It stops short of noting result-set size or pagination behavior for an unfiltered browse, which is the main residual 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?

Front-loaded with the trigger condition ('CALL THIS when...'), then alternatives, then the chaining step — a good decision order. The quoted user utterances are slightly verbose but do real work for intent matching; the description is not padded elsewhere.

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 annotations carry the safety profile. Purpose, exclusions, alternatives, and the next tool in the workflow are all present, leaving nothing an agent needs in order to call this 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 100% and both mood/genre filters are documented in the schema, so the baseline is 3. The description adds no extra meaning about how these filters interact with the browse-all behavior (e.g., whether supplying them narrows the 'full inventory' result).

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 — browse the full licensable sync inventory — and immediately scopes it against targeted search. It explicitly distinguishes itself from sync_search and find_tracks_for_brief, so an agent can route 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 explicit when-to-use ('show me everything I can license'), when-not ('not a specific search'), two named alternatives with their own use cases, and a downstream chaining step (submit_sync_brief). 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.

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context the annotations cannot: the shape of the 24-field response and the presence of a try_next navigation hint. It does not mention auth requirements or rate limits, but those are secondary for a read 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?

Front-loaded with the trigger condition ("CALL THIS when...") before the payload detail, which is the right order. The long enumeration of return fields is informative but somewhat padded since an output schema already exists.

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 single-input lookup with full schema coverage, full annotations, and an output schema, the description covers trigger, scope and return shape adequately. The only real gap is not naming the search siblings to use when no identifier is known.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description adds no syntax or format detail for id_or_title, and its wording ("exact title") is actually narrower than the schema, which also accepts partial titles.

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 (retrieve the full record) and resource (track), and enumerates the payload an agent gets back: credits, genres, moods, tempo, licensing status, links. It is clearly distinguishable from the sibling search/lookup tools because it requires an identifier rather than a query.

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?

"CALL THIS when you have a track ID or exact title" gives an explicit entry condition, and "Usually follows a search" implies the prerequisite workflow. It never names the alternative tool (search_catalog, semantic_search) to use when no ID/title is available, so routing depends on 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns the upcoming queue, but says nothing about freshness, rate limits, or behavior when the queue is empty — useful but modest 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?

Two sentences, trigger condition front-loaded, no filler. The quoted example phrasings earn their place for intent matching, though the return statement is slightly redundant with the purpose statement.

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 explaining return values is unnecessary, and the description covers trigger and high-level result. Nothing critical is missing for a trivial single-parameter read, though empty-queue behavior is unstated.

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 100% and the sole parameter ('count', 1-10, default 5) is fully documented in the schema. The description adds no format or default detail beyond that, so the baseline 3 applies.

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 ('what plays next on Radio 365') and frames the return as 'the upcoming queue', which clearly separates it from siblings such as get_radio, get_schedule, and get_track. An agent can match the intent 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?

'CALL THIS when the user asks what plays next' gives explicit trigger conditions, reinforced with concrete user phrasings. It does not name a competing sibling or a when-not-to-use case, so it stops 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety and repeatability are covered. The description adds the payload shape (links and embed URLs), but that overlaps with the existing output schema and says nothing about filtering behavior or result limits.

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

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

Two sentences, zero filler, and the invocation condition is front-loaded before the return payload. Every clause carries information an agent can act on.

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 returns, yet it does anyway without harm. For a two-optional-parameter read tool with full annotation and schema coverage, nothing essential is missing, though a note on filter interaction would round it out.

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 100% — both optional filters (type, artist) are documented in the schema itself with example values. The description adds no syntax, matching rules, or guidance on combining the filters, so baseline 3 applies.

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 clear resource (videos) and even the payload (YouTube links and embed URLs), so the agent knows what it gets back. However, it leans on trigger phrases rather than a crisp verb+resource statement, and gives no explicit contrast with siblings like get_track or semantic_search, though no sibling covers video content.

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?

"CALL THIS when the user wants video content" supplies a concrete activation condition reinforced by example utterances (music videos, trailers, visuals). It stops short of naming alternatives or a when-not condition, so an agent must infer that non-video media requests route elsewhere.

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 only declare that this is a non-read-only, non-idempotent, non-destructive write. The description adds substantial context beyond that: submission goes to CWI, auto-scoring against an editorial rubric (0-100) followed by human review, a rate limit of 3 per requester per 24h, and the shape of the response.

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 trigger condition and packed with distinct, useful facts; no filler sentences. It is a dense single paragraph rather than cleanly separated sections, which mildly hurts scanability but not economy.

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

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

Covers the trigger, confirmation requirement, processing pipeline, rate limit, and even return values (nomination ID, rubric score, queue position) despite an output schema existing. Nothing an agent needs to invoke 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 100% and all four parameters are documented there, so the baseline is 3. The description merely restates the argument names and their requiredness, adding no format or semantic detail beyond the schema.

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

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

States a specific verb (nominate/submit) and resource (a track for featured rotation), and the trigger phrases immediately disambiguate it from siblings like pitch_for_playlist or submit_for_airplay. An agent can identify the action and its target 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 explicit activation cues ('this song should be featured', 'nominate Shaka Zulu') and a precondition (confirm with the user before calling). It does not name a competing sibling or state when NOT to use it, so it stops 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?

Goes well beyond the annotations by disclosing that pitches go to human review, are NEVER auto-added, are rate-limited to 3 per requester per 24h, require user confirmation, and return a pitch ID plus a curator data package. These are materially useful behavioral traits not captured by readOnly/idempotent/destructive hints.

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 trigger condition in an imperative 'CALL THIS when...' clause, then layers in confirmation, outcome, rate limit, and parameters. Dense but every sentence carries distinct information 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?

Complete for a mutation tool: it covers the trigger, the confirmation requirement, the review outcome, rate limits, and the return package. An output schema exists, so the description need not detail return structure, and 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 100%, so the schema already documents all six parameters and required/optional status. The description reiterates which fields are required vs optional and frames why_fit as the fit rationale, but adds little syntax or format detail beyond the schema, so baseline 3 applies.

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 (pitch) and resource (song to a playlist) and includes an example utterance that pins the intent. It is clearly distinguishable from siblings like submit_for_airplay, submit_sync_brief, or nominate_featured.

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

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

Explicitly says 'CALL THIS when the user wants a song pitched to a playlist' and instructs confirming with the user first, which gives clear usage context. It does not explicitly name a sibling tool to use instead, so it falls short of the top bar.

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 only cover the generic write profile (readOnly=false, idempotent=false, destructive=false). The description goes well beyond: human-reviewed queue, no auto-play, confirm-before-calling requirement, return of queue position and estimated air time, and a concrete rate limit of 3 per requester name per 24h.

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 trigger phrase and examples, then the confirmation caveat, the anti-behavior (no auto-play), the return shape, and the rate limit. Dense but every clause carries a distinct, actionable fact 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?

With an output schema present plus full parameter coverage and annotations covering the write profile, the remaining agent questions — when to call, whether to confirm, whether it plays immediately, and how often it can be called — are all answered. Nothing needed to invoke correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the required/optional split in one line and clarifies that requested_by is the name/agent identity used for rate limiting (reinforcing why it matters). It adds modest grouping value, though the schema already carries most field 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?

States a specific verb and resource ('request a song', submits to CWI's human-reviewed queue) plus concrete examples of triggering utterances. It explicitly distinguishes the action from auto-play and from passive read tools like get_requests or get_up_next.

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 condition with example phrasings and a prerequisite (confirm with the user before calling). It does not name a competing sibling such as submit_for_airplay and say when that one is preferred, so it stops short of full 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?

Beyond the annotations (which only declare it is a non-read, non-idempotent, non-destructive write), the description discloses that it transmits the user's name and contact email to CWI, requires user confirmation first, returns event-detail confirmation, and enforces a rate limit of 3 per requester per 24h. These are material behavioral facts the annotations do not convey.

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

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

The critical trigger is front-loaded and the remaining facts (submission target, confirmation gate, return, rate limit, arguments) are packed into one dense paragraph with no filler. It is slightly run-on and would read better as short clauses, but nothing is 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?

For a mutation tool with an output schema, the description covers the missing pieces an agent needs: user-confirmation requirement, what data leaves the client, rate limiting, and the source of event_id. Return-value detail is unnecessary given the output schema, so nothing material is absent.

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 100%, so the schema already documents all four parameters including plus_ones default. The description restates the same argument list without adding format, syntax, or validation nuance, so it earns only the baseline.

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

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

The description opens with a specific action ('CALL THIS when the user wants to attend a CWI event') and gives concrete trigger utterances ('RSVP me for the listening party', 'sign me up'). The verb+resource combination (RSVP to an event) is clearly distinct from every sibling, which are all read/lookup or submission-to-different-pipeline 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?

It states exactly when to call (user wants to attend an event), a precondition for the key argument (event_id comes from get_events), and an operational gate ('confirm with the user before calling'). No alternative tool competes for this intent, and the trigger phrases remove ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds return-content detail (scored snippets, Spotify links, verified ISRCs, try_next calls), but since an output schema exists that content is largely redundant and no auth, rate-limit, or truncation behavior is disclosed. Adequate but adds limited behavioral value beyond structured data.

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 imperative ("CALL THIS") with concrete query examples, then the scope, then the alternative, then the return shape. Dense but every clause 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?

With an output schema present, return values need not be spelled out, and the description already covers scope, usage triggers, the sibling alternative, and follow-up behavior. 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by listing the fields q matches against (title, artist, genre, mood, tempo) and showing a tempo-style query example. This clarifies what a query string can target, adding real meaning over the generic schema example.

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 (keyword and filter search) and resource (CWI catalog) and enumerates the searchable dimensions (title, artist, genre, mood, tempo). It explicitly distinguishes itself from the sibling semantic_search, so an agent can route without opening either 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 explicit when-to-use triggers ("tracks by X", "downtempo around 90 bpm", "songs titled...") and an explicit alternative with its own trigger ("Use semantic_search instead if the user describes a feeling"). 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.

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

Annotations already declare this a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds the semantic-ranking behavior, but says nothing about result count behavior, truncation effects, or ranking fallback beyond what the schema states.

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?

One front-loaded sentence that leads with the activation cue ('CALL THIS when...') and ends with the differentiating behavior. The two examples are illustrative rather than wasteful, though a single example would have sufficed.

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 explained. The description covers when to invoke and what class of results come back; the remaining gap is the absence of an explicit named alternative for keyword searches.

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

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

Schema coverage is 100%, so 'q' (natural-language query, 500-char truncation) and 'limit' (1-20, default 5) are fully documented in the schema. The description's example queries reinforce the expected style of 'q' but add no syntax or constraint detail beyond it. Baseline 3 applies.

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 (search) and resource (music catalog) and clarifies the retrieval mode: matches 'ranked by meaning rather than keywords.' That contrast implicitly separates it from keyword-style siblings like search_catalog, but no sibling is named, so an agent must still infer the routing.

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 a clear triggering condition ('when the user describes music in plain words') with two concrete example phrasings, which is strong positive guidance. It stops short of stating when NOT to use it or naming the keyword-search alternative it is contrasted against.

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

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

Annotations declare this is a non-read-only, non-idempotent write with no destruction, but the description adds critical behavioral context beyond that: submissions go to human review and are NEVER auto-added, a confirmation step is required, and a submission ID plus next steps are returned. These are consequential traits the annotations cannot express.

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 trigger condition and kept to three dense sentences with no filler. The parameter list at the end is slightly redundant with the schema but remains compact and 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?

Covers intent, preconditions, behavioral outcome, and return expectations for a write tool, which is strong. An output schema exists so return-value detail is not required, though the mention of 'submission ID and next steps' is a helpful pointer rather than a 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 100%, so parameter meanings are already fully documented in the schema (including streamable link and contact format). The description summarizes the parameters with useful emphasis on the two required free-form fields (streamable link, email/handle) and marks genre/message optional, but adds little beyond the schema baseline.

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

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

The description states a specific verb (submits) and resource (the user's track and contact details to CWI) and is clearly distinguishable from siblings like pitch_for_playlist or submit_sync_brief. It even gives example user phrasings that map to this tool, leaving no ambiguity about intent.

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 trigger conditions are provided ('CALL THIS when the user is an artist wanting radio play') with concrete example utterances, plus a clear prerequisite ('confirm with the user before calling'). This is exactly the when-to-use guidance an agent needs.

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?

Discloses behavior beyond the annotations: tracks are never auto-licensed, a human responds with options/rights/clearance terms, CWI follows up by email, and a rate limit of 3 per requester per 24h applies. This is exactly the kind of non-obvious operational and side-effect context the annotations (readOnlyHint=false, idempotentHint=false) only hint at.

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 'CALL THIS when...' trigger, then side effects, receipt/response behavior, clearance context, rate limit, and arguments in a logical order. Dense but nearly every sentence carries distinct value; the master/publishing note is slightly tangential but still useful for clearance reasoning.

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?

Even though an output schema exists (so return values needn't be explained), the description still summarizes the receipt/tracking-ID outcome. With annotations covering the safety profile, the remaining description supplies triggers, side effects, rate limits, and clearance context — fully complete 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 description coverage is 100%, so the schema already documents all seven parameters with examples. The description's argument list only restates required/optional status and param names, adding no syntax or format detail beyond the schema — the correct baseline 3.

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 — 'Submits the user's brief and contact email to CWI's human sync team' — and grounds it in concrete trigger utterances (film/TV/ads/games needing music). It is readily distinguishable from sibling tools like find_tracks_for_brief or sync_search, which are search tools rather than human-submission 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?

Gives explicit when-to-use context via example user utterances and adds a prerequisite ('confirm with the user before calling'). It doesn't explicitly name the alternative tools (e.g. sync_search, find_tracks_for_brief) or state when not to route here, so it stops just 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return nature (direct-clearance licensing info) and the downstream workflow ('follow with submit_sync_brief to start licensing'). It omits pagination or result-count limits, keeping it short of 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?

Front-loads 'CALL THIS for...' with the core routing signal, then the alternative, then the return/next-step note. Every sentence does routing or workflow work; 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?

A five-parameter, output-schema-backed search tool is fully served here: when to pick it, which sibling to prefer otherwise, what it returns, and what to call next. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3. The description nonetheless illustrates how filters combine ('tense instrumental', 'BPM 90-100', 'no vocals'), which maps concretely onto q, bpm, and explicit and helps an agent construct queries. It stops short of enumerating every parameter, so not a 5.

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 (search) and resource (sync catalog) scoped to keyword/filter queries, with concrete query examples. It explicitly distinguishes itself from the sibling find_tracks_for_brief, so an agent can route correctly without opening either 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?

Explicit when-to-use ('when the user already knows what they want') plus a named alternative ('Use find_tracks_for_brief instead when the user describes a scene or mood') with the exact condition that selects it. 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.