get_midi_clip_notes_extended

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read' is consistent with that. The description adds useful behavioral context beyond annotations: stable note IDs, per-note fields, and that Arrangement responses include timeline identity.

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 entire description is one efficient sentence that front-loads the action and resource, lists key output fields, and notes Arrangement-specific behavior. There is no filler or repeated schema content.

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 two-parameter tool with annotations covering safety, the description names the key output concepts and the Arrangement-specific timeline identity. The phrase 'other per-note fields' is somewhat vague, but the schema carries the parameter load and the description provides enough to select and invoke the tool correctly.

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 100%, with clipId and trackId already well documented. The description reinforces that the clip can be a Session or Arrangement clip and mentions output fields, but it does not add meaningful per-parameter detail beyond what the schema provides.

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 uses a specific verb ('Read') and identifies the resource (one exact Session or Arrangement MIDI clip) along with the distinguishing fields it returns: stable note IDs, probability, release velocity, deviation, and other per-note fields. This clearly separates it from the sibling get_midi_clip_notes and other clip-related tools.

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 states that the tool reads extended note fields from a single clip, including Arrangement clips, which implies when it should be used. However, it never explicitly names get_midi_clip_notes as the simpler alternative or says 'use this when you need extended per-note fields,' leaving selection partially to inference.

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