OffStereo

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

Despite annotations already indicating readOnlyHint=false, the description adds critical behavioral context: the two-phase preview-then-save flow, the requirement for explicit approval, the sign-in recovery mechanism, and the exact-once constraint. This goes well beyond the 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?

The description is long but information-dense; it front-loads the core purpose and then packs behavioral rules. No filler. Slightly long, but each sentence adds operational guidance, so it earns its length.

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

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

With an output schema present and 89% parameter coverage, the description fills the remaining gaps: the two-phase flow, approval requirement, retry semantics, and exact-once rule. For a 9-parameter tool with a complex lifecycle, this is comprehensive.

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 89%, but the description enriches the meaning of key parameters: it explains that requiredArtists carries every artist the user names, that allowSecondPlaylist is strictly gated on explicit request, and that service should only be set when the user names a provider. These are non-obvious semantics not fully captured by 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?

The description opens with a clear verb+resource statement ('Create one playlist') and immediately distinguishes two modes (natural-language idea vs explicit track list). It also clarifies the tool's scope versus siblings by specifying it's a single call per turn, which differentiates it from other tools that might add multiple items.

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

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

The description gives explicit usage rules: call exactly once, use previewOnly for preview, switch to previewOnly=false after explicit approval, pass service only when explicitly named, and allowSecondPlaylist only on explicit request. These are concrete when-to and when-not-to instructions.

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 annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description still adds valuable behavioral nuance: it states results 'remain relevant rather than padding a requested genre or archive search with unrelated rows', explains that playableOnly limits to ChatGPT-playable audio, and notes the result card already includes playback. These disclosures go beyond the annotation flags and help the agent set expectations. No contradiction with 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?

The description is dense but every sentence earns its place—it front-loads the core purpose, then packs usage constraints, alternatives, and parameter semantics without redundancy. The structure flows from high-level action to specific rules to edge cases, and the wording is tight 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?

For a tool with 8 parameters, 4 modes, and an output schema, the description is exceptionally complete. It covers invocation patterns, mode selection, parameter semantics, exclusions (dated history), and behavioral guarantees. Since an output schema exists, not detailing the return structure is acceptable; nothing an agent needs to call correctly is left ambiguous.

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?

Despite the schema covering 100% of parameters, the description enriches several: it clarifies that 'query carries the listener's full wording, exclusions, counts, and no-padding constraint', explains genres as 'every positively requested genre; [] when not genre-filtered', and links allowBuild/allowSave to preserving read-only semantics. This transforms raw schema fields into actionable instructions, raising the value above the 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?

The description opens with a precise verb–object pairing ('Discover genre-aware new releases, strong public-archive matches, or popular OffStereo shows'), naming the three concrete output categories and making the tool's scope immediately obvious. It also contrasts with sibling tools by explicitly routing dated music-history requests to music_today, so an agent can distinguish it without inspecting sibling 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 description gives explicit invocation rules: 'Call exactly once per listener request', instructs to consolidate all positive genres into one array, and forbids per-genre calls. It also names the alternative (music_today) for dated history and clarifies when to use a separate one-song card. These are concrete when/when-not guidelines, not just vague context.

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

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

All three annotations are false, contributing no behavioral hints, so the description carries the full disclosure burden. It does well by stating the conservative sourcing behavior ('only returns connections it can source and withholds uncertain matches rather than guessing'), which is genuinely useful context. No contradiction with 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 with no filler. The first front-loads the purpose and scope; the second packs the usage modes and the behavioral caveat into tight, purposeful language. Every clause earns its place.

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

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

An output schema exists, so return-value documentation is unnecessary, and the two usage modes plus the sourcing caveat give an agent what it needs to call the tool. A minor gap is the lack of guidance on what happens when both topic and artist/track are supplied, and whether any parameter is effectively required.

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 adds meaningful grouping semantics beyond the schema by tying artist+track together for track-level queries and topic for story-level queries, clarifying how the otherwise-independent parameters relate. It stops short of specifying precedence or exclusivity if both forms are passed.

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 ('Explore documented sample lineage') that is unambiguous and clearly distinct from all siblings, none of which touch lineage (they cover playlists, sessions, discovery, and owned items). The two modes (track-level and topic-level) are explicitly spelled out, leaving no ambiguity about what the tool does.

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?

Provides explicit parameter-selection guidance ('Pass artist + track for one song, or topic for one multi-song narrated lineage story'), which defines when each input combination applies. It does not, however, name alternative tools or state when NOT to use this tool over a sibling, leaving sibling routing 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 cover the safety profile with readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: the session must already be mounted, the refresh happens in place, and get_session does not open library stories or drive playback. The output schema covers return-shape details.

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

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

The description is three short sentences, each earning its place: the polling scope, the refresh action, and the sibling routing. It is front-loaded with the core purpose and contains no filler or redundancy.

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

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

For a one-parameter, read-only, idempotent polling tool with an output schema, the description covers purpose, usage context, parameter semantics, and alternative tools. Nothing needed 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 0%, so the description must compensate for the single sessionId parameter. It does by referring to existingSessionId and an already-mounted PlayableSession, making clear that sessionId must reference an existing active session rather than a story or arbitrary string.

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

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

The description states a specific action: it refreshes one PlayableSession in place for an already-mounted OffStereo card. It also distinguishes itself from siblings by assigning story-opening to make_playable(existingSessionId) and playback/contextual follow-ups to steer_session.

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

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

The description frames get_session as application polling for an already-mounted card, giving an explicit when-to-use context. It names make_playable and steer_session as the tools for opening and steering, respectively, which clearly routes the agent away from get_session for those cases.

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 significant behavioral details beyond the minimal annotations: the tool call opens a card without starting playback, the card owns live progress, single_track returns exactly one recording with no narration or library save, and story progressively creates a sourced story. It also advises assistant prose to avoid stale statements, which is non-obvious 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?

The description is lengthy but tightly packed; every sentence carries distinct guidance, and the core purpose is front-loaded. While not as terse as ideal, it remains structured and avoids redundancy, earning a slight penalty for length relative to the 10% weight.

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

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

For a tool with 15 parameters, 4 enums, a rich output schema, and many sibling tools, the description covers routing, parameter combinations, behavioral expectations, and assistant-specific instructions. An agent has all necessary context to call it correctly without external knowledge.

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

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

Schema coverage is 100% so baseline is 3, but the description adds meaningful interplay: explains artist+track pairing for single_track, album pairing for exact records, trackCount usage, how source URLs act as seeds, and the videoMode requirement for a title. This goes beyond the individual parameter descriptions.

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: 'Create one playable OffStereo card for a direct standalone-song or narrated-story request.' It also distinguishes from siblings by noting Discovery and Music Today already play their songs and that playlist requests use create_playlist, so an agent can clearly tell when this tool applies.

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?

Provides explicit when-to-use guidance: for direct standalone-song or narrated-story requests, keeps results from Discovery/Music Today in original cards unless dedicated controls are requested, routes playlist requests to create_playlist, assigns get_session to polling, and details how existingSessionId works. Conditions are spelled out precisely.

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?

It discloses much more than the destructiveHint annotation alone: archive is recoverable, restore is the inverse, Spotify playlist removal is non-permanent, Apple Music returns an unsupported handoff, and confirm=true records explicit confirmation. This genuinely informs the agent about side effects and external constraints.

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?

Every sentence carries distinct information: core scope, recoverable archive behavior, Spotify semantics, Apple limitation, and confirmation semantics. It is front-loaded with the main purpose and keeps the service-specific caveats to exactly the needed 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?

Given the destructive nature, service-specific behaviors, and confirmation requirement, the description covers the non-obvious aspects an agent needs to invoke this tool correctly. The presence of an output schema means return values do not need to be explained in the description, and no substantive gaps remain.

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

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

With only 60% schema description coverage, the description compensates by explaining the meaning of archive/restore/remove, the role of confirm, and service-specific behavior. The mapping of actions to itemType is somewhat inferential rather than explicit, but an agent can still understand which action applies to stories versus playlists.

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

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

The description opens with a clear verb and resource ('Manage the signed-in listener's own OffStereo stories or service playlists') and then details the available operations. It distinguishes the tool's scope from siblings, though it doesn't explicitly name alternative tools such as create_playlist or my_offstereo to sharpen differentiation.

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

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

The description gives concrete service-specific guidance: OffStereo story removal is a recoverable archive, Spotify removal is a library removal requiring confirmation, and Apple Music deletion is unsupported. It does not explicitly state 'use this instead of sibling X,' but the 'own items' scope and the service caveats provide a clear application context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond this: the response combines multiple types of music-history data, limit applies across the combined response, playableOnly restricts rows to ChatGPT-playable audio, and allowBuild=false plus allowSave=false preserves a read-only request. No contradiction with the annotations is present.

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

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

The description is compact and front-loaded, beginning with the most important instruction ('Call exactly once') before moving into parameter behavior. The sentence enumerating the combined payload is informative rather than filler, and there is little redundant phrasing.

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. The description covers all invocation-relevant context: exact call count, date modes, limit scope, playableOnly behavior, read-only flag combinations, and how this tool relates to other calls. An agent has enough information to call music_today 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%, so the baseline is 3 even without parameter info in the description. The description mainly restates what the schema already says, such as dateMode=today omitting date and limit being the combined maximum. It adds no fundamentally new parameter semantics 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?

The description leads with a precise directive ('Call exactly once for a 'today in music' or dated music-history request') and lists the combined payload components: anniversaries, birthdays, releases, chart context, and stories. It closes by positioning the tool as 'the only dated-music tool in the current schema,' clearly distinguishing it from siblings.

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

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

It gives an explicit when-to-use trigger and an explicit when-not-to-split instruction: use one combined call rather than separate history, releases, charts, or shows calls. It also provides parameter-level usage direction (dateMode=today vs explicit, limit caps, playableOnly filtering, and read-only flags), leaving little 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context like 'currently including' (implies the content may change) and 'Call once' (suggests it's not meant for repeated polling). This adds some value beyond annotations but does not describe the return format or pagination, which is acceptable given an output schema exists. The description is consistent with 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?

The description is two sentences with no fluff. The first sentence front-loads the core purpose and scope, and the second sentence reinforces its primary role. Every word earns its place, and it is easy to parse quickly.

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

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

For a simple read-only tool with one optional parameter and an output schema, the description is fully adequate. It tells the agent what the tool returns, its scope, and that it is the primary library tool. The existence of an output schema covers return structure, and the limit parameter covers pagination. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% (the only parameter 'limit' is described with a range). The tool description does not add any parameter-specific details beyond what the schema already provides. Since the schema fully documents the parameter, the baseline of 3 is appropriate; the description adds no extra semantic value.

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

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

The description states a clear verb ('return'), a specific resource ('OffStereo library overview'), and a defined scope ('completed, unarchived shows'). It also distinguishes itself by calling out 'primary personal-library tool', which differentiates it from sibling tools like discover or music_today. The purpose is unambiguous and actionable.

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

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

It says 'Call once' and labels itself as the primary personal-library tool, giving clear context that this is the go-to for a listener's own library. However, it does not explicitly state when to avoid this tool or name alternatives, such as when archived or in-progress shows are needed. The guidance is clear but lacks explicit exclusions.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the description doesn't repeat those. It adds crucial context that the episode is not in Spotify immediately and that the listener must complete the save on their own computer, which is a non-obvious behavioral trait. It also states that the tool returns an 'honest handoff,' providing expected output behavior beyond the schema.

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

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

The description is concise, three sentences that front-load the core action and immediately specify the key prerequisite and the non-obvious outcome. It avoids repetition of the schema and annotations, with each sentence providing new information. The structure is logical: action, key constraint, then clarification of an alternative use case.

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

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

Given the tool's complexity (a multi-step packaging process) and the single parameter, the description covers the essential aspects: what it does, the precondition (explicit request), the non-blocking handoff, and the exclusion of playlists or unfinished builds. The output schema exists, so the return structure is handled separately. Minor gaps include not specifying what 'honest handoff' returns in detail, but the output schema covers that.

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

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

The schema covers 100% of a single parameter (sessionId) with a minimal but clear description. The tool description adds context that the sessionId should be from the active or selected story, which is slightly more specific than the schema's 'from the active player or the listener's library.' However, since the schema is fully covered and the parameter is simple, the description adds only marginal value.

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

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

The description clearly states the verb (prepare), the resource (a finished OffStereo story to become a private Spotify episode), and the context (after the listener explicitly asks). It distinguishes itself from related actions like 'make_playable' by emphasizing the handoff to Spotify's helper and the condition of a narrated story, not a playlist or unfinished build.

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

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

The description explicitly says when to use this tool: 'after the listener explicitly asks' and 'for a narrated story, not a playlist or an unfinished build.' It also implies that the listener must finish the process with Spotify's own helper, setting a clear boundary. No alternative tools are named, but the context signals are strong enough to guide selection.

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

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

Annotations already indicate a non-readonly, non-destructive operation. The description adds meaningful behavior: unmatched songs are excluded and reported, and sign-in triggers a preserved request with one retry. These details go beyond the annotations and clarify side effects, with no contradiction.

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 sentences front-load the core purpose and then present conditions. No fluff or redundancy; it efficiently conveys the essential action and constraints.

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

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

The description covers the main action and constraints, and the output schema handles return values. However, it does not explain the pendingActionId parameter or specify prerequisites like an active session. For a tool with four parameters and no required ones, more detail is needed for an agent to call it reliably.

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

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

With 0% schema coverage, the description must compensate for parameter documentation. It explains the service parameter's conditional use and hints at sessionId via 'one listening session', but leaves name and pendingActionId unexplained. This is a significant gap given the schema provides no descriptions.

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

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

The description clearly states a specific verb (save), resource (matched music from one listening session), and result (private playlist in active music service). It implies a distinction from create_playlist by focusing on a session's matched songs, but does not explicitly name the alternative.

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?

Provides explicit guidance for the service parameter (only pass when the listener explicitly names Spotify or Apple Music) and mentions a safe retry on sign-in. However, it does not state when to use this tool versus siblings like create_playlist, leaving that decision 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: it updates the mounted card in place, appends queueTrack to the same widget so the current song can finish and auto-advance, and explains the difference between queueing ahead and immediate interruption. It also mentions that periodic cursor syncs omit acknowledgeDirectiveId. It stops short of describing failure modes or permission requirements, but the disclosed behavior is substantive.

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

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

The description is a single dense paragraph that front-loads the core purpose ('Control and contextual follow-ups for the active player') and then covers queueing specifics. While long, every sentence adds a distinct piece of information (card update behavior, queueTrack resolution, instruction variants, queue preservation). It could be more scannable with bullets, but it is not 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?

Given the tool's complexity (7 parameters, nested queueTrack object, and an output schema), the description addresses the main workflows: queueing ahead vs playing now, why-this-song behavior, lineage opening, and story return. It mentions the result updates the mounted card, and since an output schema exists, it need not detail the return format. It covers the essential scenarios 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?

With only 29% schema description coverage, the description carries significant parameter meaning. It explains sessionId identifies the active session, activeItemId and positionMs preserve exact continuity, and queueTrack must include exact artist and title for AI-DJ transitions. It also gives two valid instruction values. It does not explicitly address playbackState or acknowledgeDirectiveId, but the schema provides descriptions for those.

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

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

The description clearly identifies the tool as controlling the active listening session with a specific verb 'Control' and resource 'active player', followed by a concrete list of actions (pause, resume, skip, play next, append, adjust level, explain, open lineage, return to story). It distinguishes itself from sibling make_playable by explicitly stating that using queueTrack 'avoids a second make_playable call' and by calling out the difference from 'opening another one-song widget'.

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

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

The description provides explicit usage guidance: for AI-DJ transitions it instructs to pass queueTrack with exact artist and title, and gives two concrete instruction strings ('Queue this as the next song without interrupting the current song' vs 'Play this next now') with their behavioral consequences. It also notes that a why-this-song question preserves the queue, helping the agent decide when to use this tool versus alternatives like make_playable.

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