group_tracks

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

With no annotations, the description carries the full burden and does well: it discloses that the draft is saved with an ID like "d3", that nothing is written to Spotify, and that preview_only returns counts instead of saving. It omits what happens if a draft is already open or how repeated runs interact with existing drafts, which is the main remaining gap for a state-mutating tool.

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

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

Front-loaded with the purpose and a workflow line, then an Args block that is scannable. It is longer than typical but nearly every line carries non-obvious semantics; the minor cost is some restating of parameter names that a structured schema would normally hold.

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 7-parameter tool with no annotations and no output schema, the description covers purpose, workflow, all parameters, and the key return cases (pool counts, group/unmatched counts, unmatched reasons, draft ID). It stops short of describing the draft dashboard contents or re-run/replace behavior, which an agent might still need.

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 leaves mode, by, genres, include_done, preview_only, and also_by_decade undocumented and defines no enums, so the description is doing the real work: it enumerates mode values, explains `by` only applies in category mode, defines genres-mode grouping, the also_by_decade split, and the fallback that returns a genre list with nothing saved. The only shortfall is the sparse nested filters documentation, which the schema itself partly covers.

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 — 'Group the loaded tracks into a draft of new playlists' — plus the visible side effect of opening the draft dashboard. An agent can distinguish this from siblings like edit_draft, show_draft, and organize_progress 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 an explicit three-step workflow: narrow the pool with `filters`, call with preview_only=true to see counts, then run it. It also states an exclusion rule (tracks already 'done', see organize_progress, are skipped unless include_done=true), which routes the agent to the right sibling and the right flag.

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