run_lua

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

No annotations are present, so the description carries the disclosure burden. It adds useful behavior: the `reaper` global is in scope and returning a value sends it back. However, it does not mention side effects, error behavior, or whether execution can mutate the project.

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?

Two sentences, front-loaded with the core action, and every clause earns its place. The sentence about round-trips is the only non-essential but still useful guidance.

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 single-parameter code-execution tool with no output schema, the description covers the environment, the output mechanism, and the intended use case. The main gaps are error handling and explicit side-effect warnings, but an agent has enough to invoke it effectively.

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 has one `code` string with no description (0% coverage), so the definition must add semantics. It clarifies that `code` is a Lua snippet, that `reaper` is available inside it, and that `return` is the output mechanism. This is meaningful but still omits examples or return serialization details.

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 action ('Run'), a precise resource ('Lua snippet inside REAPER'), and a scoping detail ('reaper in scope'). The 'multi-step work... round-trips' line separates it from single-call siblings like reaper_call.

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?

Explicitly frames use as 'Best for multi-step work that would otherwise be many round-trips,' so an agent knows when to prefer it. It does not name sibling alternatives or state when not to use it, but the context is clear enough.

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