Analyze Roll

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

With no annotations, the description carries the full behavioral burden. It discloses the output structure and the dual mode (ASCII grid vs. notes_write list), which is useful. However it never states that this is a read-only analysis operation, nor any constraints on cost, scope, or side effects, so it only partially fulfills the burden.

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 main purpose is front-loaded, but the prose is dense and occasionally ungrammatical ('from the same step features the comparisons score'), forcing re-reading. It is reasonably sized for a 10-param tool but not cleanly structured.

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 values need not be explained, yet the description helpfully details the grid encoding anyway. The gap is on the input side: for a 10-parameter tool with zero schema coverage, several parameters remain unexplained, so the definition is not fully complete 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?

Schema description coverage is 0% across 10 parameters, so the description must compensate. It explains low/high (pitch range for splitting bass/chords/lead), rel_db (threshold under the loudest note), floor_db (absolute floor), and as_notes, but leaves source, bars, project, max_bars, and min_steps entirely undocumented in both schema and description.

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 and resource: rendering a piano-roll comparison score of a source, with an explicit output encoding ('#' note starts, '=' sustains). It distinguishes itself within the crowded analyze_* family by describing a grid/score output rather than pitch, chord, or melody summaries, though it never names a sibling directly.

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?

There is a hint of a workflow ('as_notes=True returns a notes_write list ... write it, then cmp to verify'), but no explicit guidance on when to choose this over analyze_notes, analyze_pitches, analyze_melody, or analyze_grid. The agent is left to infer the selection condition from the output format alone.

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