analyze_track

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 the install/gating dependency, that full-mix capture is refused, and that cursor placement matters before calling. It does not cover failure modes beyond the refusal (e.g. what happens when capture is disabled or the track name is ambiguous).

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-loads the action and return payload, then follows with prerequisites and the cursor instruction. The parenthetical metric list is long but each item is meaningful, and there is no filler.

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?

No output schema exists, so the description must convey return value, and it does via the measured-data enumeration plus the diagnostic intent. Combined with the gating and cursor prerequisites, an agent has what it needs to invoke correctly; only edge-case behavior remains unstated.

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 100% and both parameters are documented there (track as case-insensitive unique substring, seconds default 10). The description adds no parameter-level detail, so the baseline 3 for a fully documented schema applies.

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 concrete verb and resource ('capture one verified-isolated track and return MEASURED mix data') and enumerates the returned metric families, so the agent knows this performs measurement, not playback or snapshotting. It does not name a sibling it is distinct from (e.g. profile_track, get_mix_snapshot), so differentiation is implied rather than explicit.

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 real preconditions: Post Mortem installed, capture enabled, edit cursor parked where the track is playing, and the explicit exclusion that full-mix fallbacks are refused. It does not state when to prefer this over sibling analysis tools such as profile_track, so context is clear but alternative routing is absent.

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