song_diff

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

With no annotations, the description carries the burden and does substantial work: it discloses comparison direction (older to newer by file time), the implicit source of the default operand (newest autosave in the History folder), and that ordering flips the meaning of the answer when the save is newer than the autosave. It does not state read-only safety explicitly or what happens when no autosave exists, so it stops at 4.

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 core comparison semantics and the default are front-loaded, and the long parenthetical enumerations of tracks/mixer fields earn their place by previewing the diff surface. The opening sentence is dense and list-heavy, but no sentence is redundant.

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 takes on the job of signaling what comes back — and the enumerated diff domains (tracks added/removed/renamed, mixer fields, automation envelopes) serve as an effective preview of the result. Combined with the default-resolution rules, an agent can call this correctly; only error/edge-case behavior (no autosave present, mismatched songs) is left unspecified.

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 — and it does, defining `song` as one side of the comparison and `against` as the other, plus a concrete default for `against`. It also tells the agent both accept either a title or a .song path and that song_history produces usable paths, which is real meaning beyond the bare string types. Minor gap: it never says which parameter is required.

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 framing — 'What changed between two saves of a song' — and then enumerates exactly which domains are diffed (tempo, meter, markers, sections, tracks, mixer, automation). This is clearly distinguishable from siblings like song_read (reads one save) or song_history (lists saves) because it is explicitly a comparison between two artifacts.

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 strong usage context: the default for `against` is the newest autosave in the History folder, and it explains the practical question it answers ('what have I changed since I saved?'). It also points to song_history as a source of valid path arguments. It lacks an explicit 'use X instead when…' exclusion against near-neighbors such as live_changes, which keeps it short of a 5.

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