run_action

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

With no annotations, the description carries the full burden and does substantial work: it discloses undo-block wrapping, that save/render actions are gated identically to save_project and render, that Quit is refused, and that a dialog-opening action blocks the bridge. The main omission is what a successful call returns or how errors surface.

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?

Four sentences, each carrying distinct information, with the core invocation and identifier sourcing front-loaded before the behavioral caveats. No restatement of the tool name and no filler.

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 4-param, unannotated, output-schema-less tool, this covers invocation, addressing, safety gates, and the blocking-dialog hazard. The remaining gap is return/error semantics and the valid section values, both of which an agent would want before calling.

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 coverage is only 25% (dry_run alone), so the description must compensate, and it does for the three undocumented params: it gives the format of command_id (numeric) and named_id (the _SWS_/_RS_ prefix convention) and the meaning of section. It does not enumerate the accepted section string values, and dry_run is left entirely to the schema.

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?

Opens with a precise verb+resource ("Run one REAPER action") and immediately distinguishes the two addressing modes, command_id vs named_id, with the source of each (a number from list_actions, an _SWS_/_RS string). An agent can tell this apart from raw_command or run_script without opening any schema.

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?

It tells the agent where to obtain a valid identifier (list_actions) and which sections are valid targets, which is the practical 'when to use this' context. It stops short of explicitly contrasting itself with raw_command or run_script, so the sibling choice still requires inference.

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