polynodes_set_envelope_time

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, so safety and idempotence are covered structurally. The description adds little: it doesn't clarify what state changes, whether it needs an active agent, or session requirements. 'JSON confirmation' is redundant given an output schema exists.

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?

Front-loaded verb+resource with the range up front, and the Args/Returns blocks are short. Slightly padded by the redundant 'Returns: JSON confirmation' line.

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 mutation tool with no descriptive schema coverage, the description leaves critical gaps: it doesn't define the value semantics or map to the macro/meso/micro level enum, and defers return info to a redundant line. An output schema exists, so return-value explanation is unnecessary, but the description still under-delivers on behavioral and parameter context.

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 schema relies on titles alone, and the description must compensate. It only restates 'level and value' and the 0.01-0.5 range without explaining valid strings, units, or what envelope time means in this DSP context. It adds almost nothing beyond the schema titles.

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 ('Set attack/decay envelope time') and scopes it to macro/meso/micro agents. It distinguishes itself reasonably from siblings like set_gain, set_dry_wet, and set_filter_freq by naming the envelope-time function, though the 'attack/decay' framing is ambiguous versus a per-level value.

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?

No guidance on when to use this versus other parameter-setting siblings, no prerequisites, and no exclusions. The agent must infer usage entirely, and the description does not route to any alternative.

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