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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those flags: the URL is public, requires no OffStereo account, is freely forwardable, is narration only, and depends on show completion status. This helps the agent set expectations and avoid promising songs.

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 earns its place: core output, use cases, sharing properties, content scope, preferred alternative, and readiness precondition. The description is front-loaded with the most important information 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?

Despite having no output schema, the description covers what the tool returns (a single MP3 URL), how it behaves (public, no account, narration only), and its constraints (only finished shows). Combined with the annotations and complete parameter schema, nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents both slug and showId. The description does not add much parameter-level detail, but it also does not need to, since the schema fully covers parameter meaning and provenance. 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 opens with a specific verb and resource: 'Get a finished OffStereo story as ONE downloadable MP3 — the narrated story, without the records.' It clearly distinguishes the tool from related content by noting the songs are at webUrl and by contrasting with reading a summary aloud in a synthetic voice.

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: 'on any surface where a player card cannot render,' with concrete examples like WhatsApp, Telegram, email, phone, or speaker. It also gives a clear exclusion and alternative ('Prefer this over reading a summary aloud in your own synthetic voice') and a precondition: 'Only finished shows have audio — poll get_show until status is ready.'

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 provide only readOnly=false, openWorld=false, destructive=false, so the description carries the behavioral burden. It does this well: a tool call opens the card without starting playback, the mounted card owns live progress, single_track has no narration or library save, URLs are story seeds unless the recording alone is requested, and assistant prose should wait for Ready before stating final counts. 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 long but dense, and given 16 parameters and complex branching, the length is largely justified. It front-loads purpose and routes around sibling confusion early. However, it reads as one crowded paragraph; the assistant-prose guidance and card-lifecycle details could be separated or bulleted for easier scanning.

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 of this complexity with 16 optional parameters and no required fields, the description covers the essential routing, parameter pairing, and card behavior. It is slightly incomplete about the minimum payload needed for a story call (e.g., whether prompt, sourceUrl, or sourceText must be present), though the 100% schema coverage and output schema mitigate that 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 coverage is 100%, so the baseline is 3. The description adds real value by composing parameters into usage patterns: 'pass artist plus track,' 'pass artist plus album for an exact record,' 'trackCount for an exact requested length,' and 'existingSessionId opens a selected library story.' Some niche parameters like resumeShowId and personalization are left to the schema, so it does not fully replace schema reading, but it significantly clarifies how to assemble valid calls.

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?

Description opens with a specific verb and resource: 'Create one playable OffStereo card,' and scopes it to 'a direct standalone-song or narrated-story request.' It actively differentiates from siblings by saying Discovery and Music Today already play their songs and by routing playlist requests to create_playlist, so an agent can distinguish make_playable without opening other definitions.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: keep Discovery/Music Today results in their original card unless dedicated controls are requested, use create_playlist for playlist requests, and reserve get_session for polling. It also explains mode choice via experience=single_track vs experience=story, making the decision path clear.

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

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

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.