als_read

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

Zero annotations are provided, so the description carries the full burden — and it delivers. It discloses the disk-vs-live distinction, and adds a genuinely useful data-model insight: automation lives in two places, with empirical stats (52/174 projects have clip envelopes vs 159/174 have track automation) warning an agent not to conclude a project lacks automation when only clip envelopes are absent. This is high-value behavioral context well beyond the schema.

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?

Clean, front-loaded structure: one-line summary, Args, Returns, then a clearly marked Note for contextual guidance. The Note section is the longest part but every clause carries routing or data-model value; no filler sentences. This is appropriately sized for a 4-parameter tool with a nuanced niche.

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?

Covers purpose, all parameters, the return container, and the niche use cases, and an output schema exists so return detail is not needed. The only real gap is failure behavior for a disk read — missing/corrupt file, unsupported .als version — which an agent will not be prepared for.

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 completely: the Args block documents all four parameters. Path gains accepted extensions (.als/.adg), track gains 'name or index' semantics, and both booleans get their behavioral effects ('parses clip notes and calculates note metrics,' 'formatted human-readable summary report'). Every parameter receives meaning beyond its title.

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 specific verb and resource: 'Read saved Ableton project (.als) or rack (.adg) structure directly from disk,' naming exact file types and the disk source. The 'Channel B' framing positions it against the live-connection LOM tools (get_session, get_track, get_clip) and its counterpart als_write, so an agent can tell it apart without opening schemas. Naming the two questions it answers — 'what is in someone else's project' and 'where an envelope's breakpoints actually sit' — makes scope unmistakable.

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?

Provides explicit routing: 'This is Channel B, a peer of the live connection rather than a fallback' says when-not to use it, and the two questions it alone can answer give concrete selection criteria for when to use it over the LOM. It names the alternative by class ('the LOM') rather than specific sibling tool names, which is the only gap.

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