song_plan

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

With no annotations, the description carries the full burden and does so well: draft opens a NEW project tab, writes tracks, sounds, regions, drums, guitars, bass, and layers, reports each step separately, and never saves the project. It also discloses the approval invalidation rule and the 4/4 and single-tempo 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?

The description is front-loaded with purpose and remains information-dense without wasted sentences. Its semicolon-heavy, run-on action list makes it less scannable than it could be, but the density is justified by the number of actions and side effects.

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 complex multi-action tool with no annotations and no output schema, the description covers the key workflow, approval rules, side effects, and constraints. It could more fully specify what check returns or how errors are reported, but it is otherwise complete enough for an agent to select and invoke the 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?

Schema coverage is 67%, and the description meaningfully supplements the action enum by explaining what check, show, approve, and draft do. The sheet parameter's path meaning is covered by the schema, and seed is described in the schema as a draft humanizing seed, though the description does not elaborate on it.

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

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

The description names a specific resource, a song sheet JSON, and clearly defines the tool as a multi-action song planner for checking, showing, approving, and drafting that sheet. It distinguishes this workflow from generic DAW tools by centering on the sheet's title, tempo, key, parts, and sections.

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?

Each action has explicit usage conditions: check reports every problem at once, show produces a readable sheet for a person, approve is allowed only after explicit approval of the whole sheet, and draft refuses an unapproved sheet. It also states that any later edit cancels approval, which is a critical when-to-use rule.

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