check_voice_leading

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description goes further by stating the tool is 'entirely offline and read-only,' that 'nothing in the score is changed,' and that 'findings are advice and nothing here rewrites the music.' It also discloses that common-practice rules mean intentionally broken passages are still reported. This adds meaningful behavioral context beyond the annotations without contradicting them.

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 well-structured with clear sections: a front-loaded purpose statement, an offline/read-only note, a concise Returns section, and a Note with rule-scope and alternative routing. Every sentence adds value; there is no filler or repetition of schema 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?

For a read-only analysis tool with a single well-documented parameter, an output schema, and annotations covering safety, the description is complete. It explains what the return value means, covers edge behavior (purposeful rule-breaking), and routes the agent to the correct sibling tools. Nothing needed for correct selection or 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 100%, with the single 'score' parameter fully described as a ScoreSpec object and with a pointer to score_schema for exact shape. The tool description reinforces that the input is a ScoreSpec but does not add substantial parameter semantics beyond the schema. Baseline 3 is appropriate since the schema carries the descriptive load.

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: 'Audit a ScoreSpec for parallel fifths and octaves, overlaps and spacing.' It clearly identifies the tool's purpose and distinguishes it from related siblings like check_counterpoint and analyze_harmony by naming exactly what this tool checks.

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 guidance on when to use this tool: for part-writing of any number of voices, with chorales or string quartets as natural inputs. It also gives two concrete alternatives: check_counterpoint for strict two-part species exercises and analyze_harmony for chordal analysis rather than voice movement. This is exemplary usage routing.

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