get_clip_automation

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

With no annotations the description carries the full burden, and it does so well: it declares 'Side effects: none,' discloses that results are sampled at 'resolution' beats because the LOM exposes no breakpoint list, and warns that a duplicate parameter name yields AMBIGUOUS_MATCH unless device_index is supplied. Return shape is described only loosely ('sampled curve'), which is the main remaining gap.

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 purpose is front-loaded in the first sentence, followed by labeled 'Side effects' and 'Edge cases' blocks and a compact example. Most sentences earn their place; the 'intent compared against reality' clause is slightly rhetorical but still useful framing.

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 5-parameter read tool with no annotations and no output schema, the description covers side effects, sampling semantics, disambiguation, and an invocation example. It is complete enough to call correctly; only an explicit return-format description is missing, which is acceptable given the sampled-curve framing.

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 0%, so the description must compensate, and it largely does: it clarifies resolution (sample spacing in beats), device_index (disambiguation under AMBIGUOUS_MATCH), and parameter_name (may be shared across devices). The positional example (38, 0, 'FILTER', resolution=0.5) implicitly documents track_index and clip_index order.

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: 'Read back one clip envelope as a sampled curve.' The read framing cleanly distinguishes it from siblings that write automation (create_clip_automation, create_clip_automation_curve) and from clip-metadata readers like get_clip_info or get_clip_notes.

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 gestures at usage via 'returns the written shape so intent can be compared against reality,' which implies a verification use case, but it never states when to prefer this over get_parameter_value, get_clip_info, or the read counterpart of the automation tools. Usage is implied rather than explicit, and there are no exclusions.

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