Inspect waveform editor metadata and supported operations

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context that opaque bytes are preserved and that unresolved cursor/grid/zoom/private references are identified, but it does not cover return format, pagination behavior, or permission requirements beyond what annotations imply.

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 two sentences, front-loads the main action, and avoids filler. The second sentence is a clear caveat, though the phrasing is somewhat jargon-heavy.

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 inspection tool with no output schema, the description conveys the exposed content and a key caveat about opaque bytes. However, it does not explain the collection structure (root vs nested detail collections implied by childLimit/childOffset) or any return format details, leaving gaps for a 7-parameter tool.

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%, so all seven parameters are already documented in the input schema. The description's phrase 'bounded raw metadata' loosely echoes the limit/offset bounding but adds no syntax or additional meaning beyond the schema.

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 ('Expose') and resource ('known display/time fields and bounded raw metadata'), and it names the reference types it identifies (cursor/grid/zoom/private). It does not, however, differentiate this tool from siblings like scf_inspect or scf_structure, which could inspect similar waveform editor data.

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?

There is no guidance on when to use this tool versus alternatives, nor any preconditions or exclusions. The caution 'do not infer their meaning from a round trip' is a usage note but not a selection guideline.

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