Lineupify

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: external Deezer/Last.fm dependencies, Last.fm tags only 'when a key is set', tempo being sampled, up to ~20 s first-run latency, and result caching.

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 dense sentences, no filler, with the metric list and input forms up front. The opening fragment 'Numbers about a playlist' is slightly awkward and the return/latency notes are packed into a run-on clause, 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?

With no output schema, the description correctly still tells the agent what comes back ('plain data lines; render them as a table or chart'), which resolves the main ambiguity for a metrics tool. Combined with the metric enumeration, supported input forms, latency, and caching behavior, an agent has everything needed to call and use it.

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

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

Schema coverage is 75% and the schema itself documents that 'playlist' accepts many identifier forms. The description adds meaning the schema does not: the genre source (Deezer plus Last.fm gated on a key) and that tempo is sample-based. It only weakly implies what 'refresh' does via the caching note, leaving one parameter under-explained.

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 concrete resource (playlist, library, or draft) and enumerates the specific metrics produced: length, artist concentration, decade spread, explicit share, genres, tags, tempo distribution. An agent can tell this apart from sibling tools like compare_playlists or compare_taste, which operate on multiple inputs rather than summarizing one.

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

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

Usage is implied by the content rather than stated: the mention of cache and first-run latency hints at when a refresh is needed, but there is no explicit 'use this when...' versus 'use compare_playlists instead'. No exclusions or alternatives are named.

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 and openWorldHint=true, and the description is consistent with that read-only profile. It adds real behavioral context beyond the annotations: what is computed (shared artists, identical tracks, pairwise overlap, per-side distinct), that results are explained in words, and that the natural next action is create_draft with a blend seed. It does not cover limits or auth, but the added workflow and output-shape detail 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?

Two sentences, front-loaded with the core purpose and cardinality before the output breakdown and the optional follow-up action. Dense but every clause carries information; no filler. Slightly long for a single-tool blurb but justified by the comparison's complexity.

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

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

With no output schema, the description compensates by specifying the shape of the result (shared artists, identical tracks, pairwise overlap, distinct-to-each-side) and the recommended follow-up. Combined with read-only/open-world annotations and the detailed item-level source list, an agent has enough to call it correctly and act on the result.

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?

Top-level schema description coverage is reported as 0%, so the description must carry meaning, and it does: it enumerates accepted source types (playlist links/names, drafts, 'library', 'me') and the 2-4 cardinality. Notably it adds 'me' as a valid source, which the item-level schema text does not mention, genuinely extending 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 states a specific verb (Compare) and its operands (2-4 playlists, drafts, library, or 'me'), then enumerates exactly what the comparison yields: shared artists, identical tracks, pairwise overlap, and per-side distinct items. It is far more than a restatement of the title, though it never names sibling tools such as compare_taste or merge_playlists to sharpen the boundary.

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

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

Usage is implied by the input description ('Compare 2-4 sides') and the closing suggestion to follow up with a create_draft blend seed, which shows the intended workflow. However, there is no explicit when-to-use/when-not or an alternative tool named, so an agent must infer that this is the multi-source comparison rather than the single-user compare_taste.

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, the description defines what 'known' means (top artists over last 4 weeks / 6 months / all time, or followed) and discloses the reorderKnownFirst side effect of reordering the draft. This adds genuine behavioral context not present in annotations, though it omits auth requirements and 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?

Two sentences, front-loaded with the core action, then the optional parameter effect and example use cases. Every clause carries information, though the quoted user questions add length that is slightly more illustrative than essential.

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

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

With no output schema, the description carries the return burden and adequately conveys the result: each artist flagged as known or new, optionally reordered. It is nearly complete for a two-parameter tool, with only return-format/pagination details left 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 0%, so the description must carry the burden. It explains reorderKnownFirst ('puts familiar artists first') well, but draftId receives no explanation in the description or schema, relying on the surrounding context that the tool operates on a draft.

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 and resource: 'Mark each artist in a draft as known... or new to them.' This clarifies the ambiguous name 'compare_taste' and distinguishes it from analysis siblings like analyze_playlist or refresh_taste by emphasizing the per-artist known/new classification on a draft. It lacks an explicit tie-break against those nearest siblings, keeping it just below 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?

It supplies clear usage context with example questions ('which of these acts do I already like?', 'is this festival for me?'), which tells an agent when this tool applies. However, it never names an alternative tool or states exclusions, so routing versus refresh_taste/analyze_playlist 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 only declare safety hints (non-read-only, idempotent, open-world, non-destructive), while the description adds the genuinely non-obvious behavior: the call is async and returns a login URL rather than completing auth, a follow-up status call is required, force is needed on ~6-month token expiry, and the tool is blocked during draft construction. That is substantial disclosure 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?

Dense, front-loaded sentences ordered as action, follow-up, optional params, edge case. No filler; every clause carries operational 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 no output schema, the description still tells the agent what is returned (a login URL) and what to do next (call status), plus the refusal condition. Nothing needed to invoke the tool 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 50%: clientId is documented in the schema, but force has none. The description fully compensates by explaining force's purpose (switch accounts / re-login) and adds the combining benefit of clientId ('saved before the login starts, no separate setup'), though the clientId format detail is already in 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+resource ('Start the Spotify login') and immediately clarifies the exact mechanism ('Opens the browser and returns the login URL immediately'). This distinguishes it from siblings like status (which confirms) and disconnect, so an agent can pick correctly 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?

Explicitly routes the agent: call this to start, then call status to confirm; pass clientId to avoid separate setup; pass force:true to switch accounts/re-login every 6 months. It also states a when-not condition ('Refused while a draft is building'), leaving nothing 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 cover mutation and open-world behavior, but the description adds the operational detail they cannot: ~15s synchronous return with background continuation and a "building" status, the polling cadence, the guarantee that nothing is published until create_playlist, and the full defaults block (5/3/2 tiers, 250 max tracks, interleave, private). It even flags a cost (skipCovers = one Deezer lookup per track).

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

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

Front-loaded with purpose and usage, and almost every clause carries information an agent needs. The cost is that it is one dense ~250-word block mixing seed types, free-text handling, constraints, async behavior, and defaults, which makes targeted re-reading harder than a lightly segmented version.

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 27-param, no-required, nested-schema tool with no output schema, the description covers the workflow, async/polling contract, publishing gate, and defaults that an agent needs to invoke it correctly. Remaining gaps are minor (error/unresolved-artist handling is delegated to stopIfUnresolved in the schema) and acceptable given schema coverage.

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?

At 70% schema coverage the description meaningfully supplements the schema by enumerating the constraint knobs (tracksPerArtist, maxDurationMin, excludeExplicit, yearRange, bpmRange, skipCovers, excludeTracksFrom) and explaining seed semantics that the schema only hints at (limit as songs-per-seed-song, excludeSeedArtists for "other artists only"). It does not touch several params (days, order, sources, discoveryOnly, strictBpm/strictYear, stopIfUnresolved), which the schema largely documents itself.

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?

Opens with a specific verb+resource ("Build a draft playlist from artists and/or seeds") and immediately scopes it against siblings: nothing is written until create_playlist, and long builds are polled via get_draft. An agent can distinguish this from create_playlist, edit_draft, and get_draft without opening a 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 branches: Spotify login vs provider "deezer" with no account, and a concrete procedure for free-text requests (propose 15-30 artists yourself and add a matching genre seed). It also names the follow-up tool and condition (poll get_draft waitSeconds: 25 when status is "building").

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 (readOnly=false, idempotent=false, destructive=false) by disclosing the user-visibility gate, two distinct refusal conditions, and the fact that a repeat call fails rather than overwriting. It also states the return value (URL) despite there being no output schema, which the agent would otherwise have to guess.

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

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

Purpose and return value are front-loaded, and no sentence is wasted. The middle sentence, however, chains three separate conditional rules into one dense line, which slightly slows parsing compared to a short bulleted form.

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 non-idempotent write with no output schema and no parameter descriptions, the description supplies the missing pieces: prerequisites, failure modes, sibling alternatives, and the return value. Nothing an agent needs to call it correctly 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 0%, so the description must carry all four parameters — and it does: draftId (the draft to publish), confirm (bypasses the get_draft requirement), allowPartial (permits publishing while building), and mode ('new' for a second copy). Each parameter's meaning is derivable from the prose.

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 ('Publish a ready draft as a new playlist in the connected Spotify account'), names the return value, and implicitly distinguishes itself from update_playlist and get_draft by routing those cases explicitly. An agent can separate it from every sibling without opening a 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 preconditions (draft shown via get_draft OR confirm: true), an explicit refusal case (refuses while building unless allowPartial: true), and a named alternative for the already-published case (update_playlist, or mode: 'new' for a copy). When-to-use, when-not-to-use and the alternatives 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful scope information beyond that: the deletion acts on the local draft file and leaves an already-published Spotify playlist intact, which prevents an agent from assuming a broader blast radius.

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, zero filler, with the core action front-loaded and the scope caveat immediately after. 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 single-parameter destructive tool whose annotations already carry the safety signal and which has no output schema, the description supplies the one thing that matters most: what is and is not destroyed. Missing detail on the draftId and on failure/reversibility keeps it short of full completeness.

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?

Only one parameter (draftId) with 0% schema description coverage, and the description never mentions it. The name is largely self-explanatory, but the description adds no format, source, or retrieval hints (e.g. where a draftId comes from), so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Delete a draft') and scopes it to 'from disk', which separates it from anything that would affect published artifacts. It does not explicitly name a sibling, but the operation is unambiguous among the draft-management tools.

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

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

Usage is only implied by the operation itself; there is no statement of when to delete versus edit/export a draft, nor any preconditions (e.g. whether a draft must be unpublished). The single clause about the Spotify playlist not being touched gives partial scoping but is not framed as 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 destructiveHint/idempotentHint annotations: it enumerates exactly what is deleted (tokens.json, then config, caches, drafts, exports under purge), the two-key confirm requirement, the refusal conditions, and the fact that Spotify-side access is not revoked and must be handled by the user at an external URL.

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?

Dense but front-loaded, with the base behavior stated first and the destructive purge path second. The parentheticals (deletes tokens.json, the tool says so) are compact and earn their place, though the single long sentence requires careful parsing.

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 what is destroyed, the confirmation gate, refusal preconditions, and the out-of-band Spotify revocation step, which is what an agent needs for a destructive tool with no output schema. Nothing material is left 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 coverage is 100%, so the baseline is 3, and the description adds real meaning: purge's scope is spelled out (config, caches, drafts, exports) and confirm is constrained to a genuine in-conversation user agreement, explicitly not text embedded in posters, playlists or lineups.

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 the specific verb and resource precisely: it forgets the saved Spotify login by deleting tokens.json, and explains the extended purge variant. An agent can distinguish this from siblings like connect or setup 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 conditions for the destructive purge path (confirm: true, only after the user has agreed in-conversation) and states when the tool refuses (draft building, foreign files in the data folder). It does not name an alternative sibling, but the when/when-not guidance is otherwise strong.

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=false, destructive=false, idempotent=false. The description adds substantive behavior beyond them: edits apply atomically as a batch, optimistic concurrency via expectedRevision prevents edits against an unseen list, and the allowed-op set narrows while the draft is still building. Return shape/revision feedback is not described.

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 atomic-edit purpose and the op catalog, then adds the two critical constraints (expectedRevision, building-state restriction) in follow-on sentences. Dense but every clause carries information; the op list is long but earns its place as the primary semantic content.

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 no output schema, the description covers atomicity, concurrency control, and state-dependent op availability — the main things an agent needs to call it correctly. It does not state what the call returns (e.g., updated revision), which is a minor gap given there is no output schema to cover it.

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

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

Top-level schema coverage is 0%, so the description must compensate, and it does: it explains expectedRevision's purpose (guard against stale edits) and maps each ops[].op value to its meaning, including the set_artist_source 'fix a wrong artist match' case. Per-op field-level details (from/to, seed, mode) are left to the schema, so it is not exhaustive.

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 (edit) and resource (draft) and enumerates the exact operations the tool performs, which cleanly separates it from siblings like update_playlist, get_draft, and export_draft. An agent can tell what this does 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 concrete routing guidance: track ids come from get_draft view=tracks, and expectedRevision must come from the last get_draft. It also states the state-dependent restriction (only exclude_artist, set_artist_track_count, set_artist_source, filter, set_meta while building). It never contrasts itself against update_playlist, so it stops short of full when-not 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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description still adds real behavior: the default artist/track counts, the automatic exclusion of tracks already in the playlist, and the fact that the result is a draft rather than a published playlist. It doesn't mention that each call produces a new draft or any provider/auth requirement (left to 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?

Two sentences, no filler, with the core behavior and defaults front-loaded before the relationship to create_draft. Every clause carries information an agent needs.

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 20-parameter, non-idempotent mutation tool with no output schema, the description covers the essential behavior and the two defaults an agent must know, and the many filter options are self-documented in the schema. The main gap is that it doesn't signal that repeated calls yield distinct drafts, which matters given idempotentHint=false.

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 70%, in the middle band, and the description adds genuine meaning for a few key knobs: tracksPerArtist default of 2 (not stated in the schema), the 30-artist cap, and the exclude-existing behavior. It says nothing about the remaining undocumented params (name, public, maxTracks, excludeArtists, tracksPerTier), so it only partially compensates.

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 ('Build a draft of more songs by the artists of an existing playlist') and immediately pins down scope with the defaults (2 per artist, 30 most frequent artists) and the exclusion rule. It also names the sibling it relates to ('shortcut for create_draft'), so an agent can distinguish it from create_draft and merge_playlists 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?

The description frames the tool as a shortcut for create_draft with a playlist seed plus excludeTracksFrom, which implicitly tells the agent when to reach for this rather than the general draft builder. It stops short of an explicit when-not (e.g. 'use create_draft instead if you are seeding from tracks rather than a playlist'), so a small inference remains.

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 non-readonly, idempotent, non-destructive, closed-world, and the description adds real behavioral detail beyond them: save:true writes to ~/.lineupify/exports/ and explicitly 'never elsewhere'. It does not explain what overwrite does or what happens to an existing file, which is the remaining behavioral 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?

Two dense sentences that lead with the formats, then the transfer rationale, then the save behavior. No filler, though the transfer-tool sentence is somewhat long and could be trimmed.

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

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

For a 4-parameter export tool with no output schema and full annotation coverage, the description covers formats, the practical use case, and the file-write destination. The missing pieces are the overwrite parameter's behavior and whether save:false returns content inline, which are modest gaps.

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 carry the load. It explains the semantics of the format enum values ('links' = one track URL per line, 'text' = 'Artist - Title' per line) and the save flag's destination, but says nothing about overwrite and gives no format for draftId. Roughly half the parameters are clarified.

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 (return/export) and resource (the draft) and enumerates the five output formats, so an agent knows exactly what it produces. It is distinguishable from read-oriented siblings like get_draft by the export framing, though it never names a sibling to sharpen the contrast.

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 concrete guidance on format selection: 'links' and 'text' are what TuneMyMusic/Soundiiz accept, which explains the transfer workflow. It stops short of stating when to prefer this over get_draft or what to do if no draft exists, but the context is 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?

Annotations already declare readOnlyHint=true, and the description adds real behavioral context: waitSeconds polls for progress mid-build, the tracks view is paged, and the tool 'also resumes an interrupted build' — a side effect beyond a pure read that the annotations do not convey. Return-format details are absent, but the added side-effect disclosure is meaningful.

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?

Dense but front-loaded: the view taxonomy comes first, then wait behavior, then the draftId default. Every clause carries information; the only mild cost is that four views are packed into one long sentence.

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

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

With no output schema and low schema-description coverage, the description does most of the heavy lifting by defining each view's payload and the wait/resume behavior. The gap is pagination semantics (limit/offset ranges and defaults) and what the summary view returns, but overall it is sufficient to call 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 only 20%, so the description must compensate and does so partially: it explains the view enum semantics, the waitSeconds cap, and the draftId default. It says nothing about limit/offset beyond the word 'paged', leaving pagination behavior half-documented.

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+resource (show a draft) and enumerates the four distinct views, each with a gloss. It also separates itself from edit_draft by noting the tracks view returns 'stable ids for editing' rather than performing edits, so an agent can place it among its 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?

Gives clear conditional guidance: omit draftId for the most recent draft, pass waitSeconds while a draft is building, choose the view by what you need. It stops short of naming alternatives (e.g., list_drafts for enumerating drafts, edit_draft for mutation), so it is strong context without 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 declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds genuinely new behavioral context — result ordering (newest first) and the fields each entry carries — but says nothing about result size, pagination, or what happens when no drafts exist.

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 tight sentence with zero filler, front-loaded with the verb and resource followed by the two most decision-relevant result facts (ordering and included fields). 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?

For a no-parameter, read-only enumeration tool with no output schema, the description supplies the essentials: what is returned and in what order. The only omission is pagination/size behavior, which is a minor gap given the bounded, non-open-world scope implied by openWorldHint=false.

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

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

The tool takes zero parameters, so the schema has no semantics to add and the baseline is 4. The description correctly avoids inventing parameters and instead uses the space to describe the result shape.

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 (List) and resource (saved drafts) and adds two useful output attributes: ordering ('newest first') and returned fields ('status', 'whether they were published'). It distinguishes itself implicitly from get_draft (singular) and the create/edit/delete/export_draft siblings by being the enumeration tool, though it never names those siblings explicitly.

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

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

Usage is implied by 'List saved drafts' — an agent can infer this is for enumerating all drafts rather than fetching one. However, there is no explicit guidance about when to prefer this over get_draft, nor any exclusion or prerequisite (e.g. whether drafts must exist).

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 non-read-only, non-destructive, non-idempotent, open-world, so the safety profile is covered. The description adds real value beyond that: it discloses the dedup key set (URI, ISRC, title+artist) and clarifies the result is an unpublished draft, not a live playlist. It doesn't state error behavior or whether duplicates across input drafts are counted, keeping this below 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?

Three compact sentences, front-loaded with the action and its output, then the dedup rule, then routing to siblings. Every clause earns its place and none repeats schema-only facts.

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

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

No output schema exists, so the description must convey the return artifact, and it does ("one ready draft") plus the publish path. Dedup semantics are stated. It could go further on order/defaults and on whether the source playlists are modified, but for a 7-param merge tool this is close to sufficient.

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 only 14%, so the description must carry more of the burden than it does. It clarifies the playlists parameter (1-6, links or names, drafts or "library"), but says nothing about name, public, maxTracks, excludeExplicit, description, and only implicitly about order. Most parameters remain undocumented in both places.

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 (combine/merge), the resource (1-6 Spotify playlists, drafts, or library), the count bound, and the output artifact (one ready draft). It also names the sibling it is not (expand_playlist), so an agent can discriminate without opening the schema.

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

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

Explicitly routes the agent: "Then create_playlist to publish" describes the follow-up step, and "For 'add more songs by these artists' use expand_playlist instead" names the alternative and the 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the meaningful behavior that it strips dates, stage names and ticket lines from the input. The one ambiguity is that it says it drops 'stage names' while also producing 'days and stages', which is slightly self-tensioned, but not a contradiction of 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, front-loaded with the core transformation before the optional alternative. The second sentence packs the skip-path and the tier vocabulary together, which is dense but each clause is load-bearing; 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 no output schema, the description carries the return-shape burden and does describe the produced structure (artist list with tiers/days/stages). It stops short of specifying the exact output format, but for a single-parameter read-only parser it is sufficiently complete.

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

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

Schema description coverage is 0% on the single 'text' parameter, but the description compensates by characterizing the expected input as 'raw poster text (as read from an image or pasted)', which is exactly the semantics an agent needs. It doesn't state the length bounds (already in schema), so it's not a full 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?

The description states a specific transformation: raw poster text in, a clean artist list with tiers, days and stages out, explicitly dropping dates/stage names/'tickets' lines. This is a distinct verb+resource that an agent can separate from create_draft and the other playlist 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 goes beyond naming a use case and gives an explicit conditional alternative: 'when you can already see the poster, you may skip this and pass structured artists straight to create_draft.' It even supplies the tier vocabulary (headliner/sub/undercard) needed to take that alternative path, leaving nothing 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 read-only and open-world profile, so the bar is lower, and the description still adds real behavioral context: a 12-hour cache with a refresh escape hatch, and the hard limitation that Spotify-made playlists (Discover Weekly, Blend, Top Hits) cannot be read by new apps. That access restriction is exactly the kind of non-obvious constraint 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?

Three dense sentences, front-loaded with the action and inputs before moving to views and caching caveats. No filler and every clause carries operational 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?

There is no output schema, so the description carries return-value burden, and it partly does so by naming the fields each view returns (artists/decades/counts; year, ISRC, URI; artist counts). Pagination mechanics for the tracks view are the main unaddressed 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 40%, so the description must compensate. It does clarify the 'playlist' input forms and the 'view' options, but 'limit' and 'offset' (paging) are never explained beyond the schema's bare 'default 50' and the description's single word 'paged'. Partial compensation only.

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

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

Opens with a specific verb+resource ('Read any playlist into a structured list') and enumerates the full range of accepted inputs (Spotify/Deezer link, library name, draft id, "library"). It does not explicitly contrast itself with siblings like analyze_playlist or expand_playlist, which is the only thing keeping it off 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?

The three views, the 12-hour cache, and the refresh flag give clear context for how to call the tool, but there is no guidance on when to choose read_playlist over analyze_playlist, expand_playlist, or compare_playlists. Usage is implied rather than stated.

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=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real value beyond them: it discloses the auth requirement (user-library-read), the reconnect remedy, and the library-exclusion behavior that defines the 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?

Three tight sentences, front-loaded with the core behavior and defaults before the create_draft relationship and the permission note. Dense but no filler; a slightly longer version could have separated the permission caveat more cleanly.

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 20-parameter draft-creation tool with no output schema and nested objects, the description covers purpose, key defaults, auth requirements, and the sibling relationship adequately. It does not describe what the draft response looks like or the interaction between the shortcut and the many optional filters.

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 70%, so the schema already documents most parameters (bpmRange, yearRange, provider, skipCovers, etc.). The description contributes only two defaults (2 songs per artist, 30 artists) and the excludeTracksFrom shortcut, leaving many of the 20 parameters unexplained 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 and resource (build a draft from the user's top/followed artists) and immediately differentiates itself from the sibling create_draft by framing itself as a shortcut with fixed seed behavior. An agent can tell it apart from create_draft 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?

Names the general-purpose alternative explicitly ('Shortcut for create_draft with a taste seed plus excludeTracksFrom: ["library"]') and states the prerequisite permission plus the reconnect remedy. It lacks an explicit 'don't use this when...' clause, but the routing condition is 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-network behavior are covered. The description adds genuinely useful downstream context (output is URIs destined for edit_draft add_track), but says nothing about result ordering, return shape beyond URIs, pagination, or provider auth requirements.

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 tight sentences, front-loaded with what the tool does, then the fallback condition, then the filter example and the return contract. 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 no output schema, the description correctly states what comes back (URIs) and where they go. For a 3-parameter, no-auth-documented search tool this is nearly sufficient; only the limit parameter and provider-connection prerequisites remain 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 only 33% — provider carries a description while query and limit are bare. The description compensates by showing the filter syntax ('track:Marea artist:Fred again'), which is real value beyond the schema, but it never explains the limit cap of 10 or clarifies that query accepts free text versus filter operators.

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 (track) and names the concrete consumer of the result ('Returns URIs for edit_draft add_track'). It also distinguishes its two providers and the condition selecting the Deezer fallback, so an agent can tell this apart from other tools in the lineup/draft family.

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

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

Gives clear context: use it to find a track to add manually, use Deezer when working a Deezer draft or when Spotify is not connected, and the schema note 'Match the draft you will add to' reinforces the routing. There is no explicit exclusion against sibling tools such as parse_lineup or expand_playlist for bulk discovery, so it stops short of a full when/when-not rule.

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 indicate destructiveHint=true and idempotentHint=true, and the description adds critical behavioral details: JPEG only, size limit, local file requirement, and authentication state handling. It also clarifies that a pasted image is not a file, which is valuable 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 front-loaded with the main action and constraints, and each sentence provides necessary information. However, it is somewhat dense and could be slightly more structured, but it remains efficient.

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 complexity of the operation (external API, file handling, authentication nuances) and no output schema, the description covers all necessary details for an agent to invoke correctly: prerequisites, file requirements, and error handling for permissions.

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 50%, with imagePath fully described in the schema. The description adds meaning by emphasizing that imagePath must be a full local path and that the file must be JPEG with size constraints, which are not in the schema. DraftId is not elaborated in the description, but its purpose is clear from 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 (Replace) and resource (cover image of the playlist a draft was published to) with clear scope. It distinguishes itself from siblings like create_playlist by clarifying that the draft must already be published.

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 prerequisites ('Requires the draft to be published (create_playlist first)') and the condition to reconnect if permissions were granted before the image-upload permission existed. It also instructs on how to handle a pasted image.

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 is a non-destructive, idempotent write. The description adds real behavioral context beyond that: the required redirect URI must be exactly http://127.0.0.1:8765/callback, and redirectPort=0 resets to 8765, implying persistence and overwrite semantics. It doesn't say where the value is persisted or what the response looks like, but the added constraints are 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?

Front-loads the primary action and the critical constraint (client ID format, exact redirect URI) before moving to the optional parameters. Dense but every clause carries information; only the parenthetical redirect-URI detail slightly interrupts the flow.

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 3-parameter, no-output-schema setup tool with annotations covering the safety profile, the description supplies the format constraints, the exact redirect URI requirement, and the port-reset behavior an agent needs. It stops short of describing persistence location or any auth requirement, but nothing essential for correct invocation 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 carries the full burden, and it does: clientId is defined by format and source (32 hex chars, dashboard app page), lastfmApiKey is scoped to a second ranking source, and redirectPort is explained as only-needed-when-different with a 0-resets-to-8765 special case. All three parameters gain meaning not present in 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 and resource ('Save the Spotify client ID') and adds concrete detail about the value (32 hex chars from the developer dashboard). It does not explicitly distinguish itself from siblings like status or connect, but 'setup' is unambiguous enough for an agent to identify it.

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 the motivation ('so it is not needed in the MCP config') and conditions for the optional params ('for a second ranking source', 'only if the user registered a different port'), which implies when to use them. However there is no explicit guidance on when to call setup versus status/connect/disconnect, leaving the workflow ordering 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 and openWorldHint=true, so safety is covered by structured data. The description still adds real behavioral context beyond that: it clarifies this is an aggregate diagnostic that reports connection state, pending logins, and cache size, which tells the agent what kind of read to expect. It omits any note on cost or rate limits but none are implied for a local status read.

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 imperative 'Call this first' so the ordering guidance lands immediately, followed by the enumerated contents. Every clause earns its place, though the final clause about a waiting browser login is a slightly verbose restatement of the pending-login idea.

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

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

With no output schema, the description carries the burden of describing return contents, and it does so by enumerating the reported fields. A read-only, zero-parameter diagnostic is adequately covered, though it could say more about what the agent should do with 'setup needed' beyond the adjacent setup 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?

Zero parameters, so the baseline of 4 applies and there is no parameter surface for the description to explain.

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 (shows) and enumerates concrete resources it reports: Spotify connection and identity, setup need plus exact steps, default options, in-progress drafts, cache size, and pending browser logins. This is more specific than a generic status tool, though it does not explicitly contrast itself against the sibling 'setup' tool it partially overlaps with.

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' gives a clear ordering directive that tells the agent when to reach for this tool relative to all 21 siblings, and it hints that 'setup' is the follow-on when setup is needed. It stops short of stating exclusions or naming the alternative tool explicitly, so it is strong context but not full when/when-not 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 destructive/idempotent/openWorld, yet the description adds behavior not covered there: a concurrency conflict check against Spotify, refusal semantics, and the requirement to confirm with the user before forcing. That is exactly the kind of context the description should carry beyond structured 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?

Two sentences, zero padding, and the workflow purpose is front-loaded ahead of the edge-case/force caveat. 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?

For a destructive mutation with no output schema, the description covers purpose, trigger, and the drift-refusal path well; annotations carry the safety profile. It stops short of saying what the result looks like or what 'details' (name/description) are overwritten, a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate. It explains force fully (bypasses the drift refusal, should be user-approved) but says nothing about draftId beyond implying it identifies the published draft, leaving one of two params undocumented.

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

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

The description gives a specific verb ('replace the tracks and details') and a precise resource ('the playlist this draft was published to'), and it ties itself to the edit_draft sibling instead of leaving the workflow ambiguous. An agent can distinguish it from create_playlist, read_playlist, and edit_draft 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?

It clearly states the triggering context ('so edits made with edit_draft reach Spotify') and the precondition for failure, but it doesn't explicitly contrast with siblings like create_playlist or set_playlist_image. The workflow guidance is strong enough that an agent knows when to call it.

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