fx_scan_params

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

No annotations are provided, so the description carries the full burden — and it delivers richly. It discloses the caching behavior (keyed by plugin name, instant repeat scans from on-disk cache), the side effect of briefly writing and restoring every parameter's value during the sweep, and performance characteristics (can take longer on many-parameter plugins). No contradiction with annotations since none exist.

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 with the core purpose, followed by scope, behavioral notes, and args. Well-sectioned and every sentence earns its place. The spec-document reference (docs/superpowers/specs/...) is a minor addition that could be trimmed for an agent, keeping it from a 5, but nothing is genuinely wasted.

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 tool of this complexity — side effects, caching, performance variance, and a sibling it must be distinguished from — the description is thorough. It covers all behavioral caveats and usage boundaries. The one gap: no output schema exists and the exact return format (how range/units/curve shape are presented) is not stated, though it is strongly implied by the purpose.

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 description must fully compensate, and it does: it documents track_index as 0-based or -1 for the master track, and fx_index as a 0-based FX chain index. Both parameters are explained with precision beyond the bare integer type in the schema, including the special -1 master-track case.

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+resource+outcome: sweep a plugin's parameters to learn their real range/units/curve shape. Explicitly differentiates from siblings by declaring it is NOT a general 'understand this plugin' tool and is 'deliberately separate from fx_get_params rather than folded into routine reads.' An agent can tell exactly what this does and what it is not.

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?

Gives explicit when-to-use (on-demand fallback when genuinely unsure and about to guess), when-not-to-use (not routinely/proactively on every plugin), names the alternative (fx_get_params and general knowledge, e.g. FabFilter), and even gives concrete trigger examples (obscure/freeware plugin, surprising parameter behavior). This is exemplary routing guidance.

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