set_property

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 disclose that this is a mutation that can be reversed by omitting value, plus a non-obvious side effect (kDynamicGradualChangeDuration also applies to a hairpin joined to a dynamic). It does not say what happens on an invalid property name, whether writes are idempotent, or what the tool returns, leaving meaningful behavioral gaps for a write tool.

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 purpose and examples are front-loaded well, but the back half is dense and hard to parse, especially the run-on part explanation with nested parentheses and the stray '(> <)' marker. The content is largely earned, but the packing of three unrelated topics into one paragraph hurts scannability.

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 mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the generic-property concept, the reset semantics, and the hairpin edge case, but is silent on event_ids, flow, error behavior, and return values. It is adequate to attempt a call but not complete enough to call confidently.

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% across 5 parameters, so the description must compensate and only partially does: it explains value (omit to reset), implicitly defines name via the property examples, and gives a real explanation of part ('the hairpin's "sub" from read_markings when its group holds several hairpins'). event_ids and flow receive no explanation at all, leaving two of five parameters undocumented anywhere.

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 opens with a specific verb+resource ('Set any event property') and immediately grounds it with concrete examples (kNoteVelocity=100, kEventColour=#ffff0000), so an agent knows exactly what class of operation this is. It also implicitly distinguishes itself from describe_property, which it cites as the discovery counterpart, though it never states how it relates to narrower setters like set_pitch or set_tempo.

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?

'See describe_property' is a genuine routing hint for discovering valid property names, and 'Omit value to reset to default' gives a concrete usage rule. However, there is no guidance on when to use this generic setter versus the many specific siblings (set_pitch, set_duration, set_tempo), which is the main decision an agent faces.

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