polynodes_crush_switch

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the agent knows repeated calls are safe and nothing is destroyed. The description adds the on/off semantic but doesn't note it as a confirmation-only operation beyond 'JSON confirmation.' With annotations carrying the safety profile, moderate credit is appropriate.

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?

Very short but structured as Args/Returns, front-loading the purpose. The 'Returns: JSON confirmation' is low-value given an output schema exists. Minimal but not wasteful; however the arg description is nearly empty.

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?

Output schema exists, so return-value explanation isn't needed. For a single-parameter toggle with good annotations and documented value bounds, the description is adequate but thin — it doesn't state scope (per-node vs global) or how it interacts with the other crush tools.

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 listed as 0% at the top level, but the nested SwitchInput definition does document 'state' with '0.0 = off, 1.0 = on' and min/max bounds. The description's 'params: state' adds nothing beyond that. Baseline 3 because the nested schema actually documents the parameter well.

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?

Clear verb+resource: toggling Bitcrusher/Decimater on/off. Sibling tools like polynodes_crush_bit_level and polynodes_crush_range are related but not the switch, so the purpose is distinguishable. The typo 'Decimater' is a minor blemish but doesn't obscure the meaning.

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 implies usage via the on/off framing, but there is no explicit statement of when to use this versus the related crush parameter tools (bit level, range). For a switch tool among many siblings, more routing guidance would help.

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