batch

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

With no annotations, the description carries the full burden and does well: it discloses atomicity ('ONE undo block'), single round-trip cost, clean failure behavior, and that one Ctrl+Z reverts everything. It does not mention dry_run or the return_partial_results/no-rollback mode, so the error-handling story is only partially told.

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?

Three tight sentences with the core guarantee (one undo block, one round-trip) front-loaded, followed by the input shape and the motivating use case. No sentence is 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 batching tool with no output schema and no annotations, the description conveys the essential contract (atomic undo, one round-trip, clean failure). It omits return-value expectations and the dry_run / partial-results paths, which would matter for an agent deciding how to interpret results, but nothing critical is missing.

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 80%, so the schema already documents dry_run, commands, stop_on_error, and return_partial_results; only undo_label is bare. The description's 'commands: [{type, payload}]' mostly restates the schema example rather than adding format or semantics, so the baseline 3 applies.

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 (run) and resource (several bridge commands) with the distinguishing scope: as ONE undo block and one round-trip. An agent can immediately tell this apart from siblings like raw_command or set_fx_param, which act on a single operation.

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 says to use it for multi-step edits and gives a concrete example ('several set_fx_param calls'), which implicitly routes the agent away from issuing those calls individually. It lacks an explicit when-not (e.g. single-command or read-only cases), so it falls short of a 5.

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