batch_actions

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description must carry the interesting behavior — and it does, disclosing that actions execute in order, that the whole batch collapses into a single undo step, and which tool categories are forbidden inside it. It does not say what happens when an action mid-batch fails (rollback vs. partial application), which is the one behavioral fact an agent most needs before batching a risky sequence.

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, no filler, and the highest-value fact (atomic, single undo step) is front-loaded before the constraint. Nothing is repeated from the schema or annotations.

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 batch executor with four parameters, no output schema, and zero schema documentation, the description is thin. It omits failure/rollback semantics, what the tool returns (per-action results? a single revision?), and any explanation of expectedRevision, leaving an agent unable to safely construct or interpret a batch beyond the nesting rule.

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% across four parameters, so the description must compensate and it largely does not. It never mentions the actions array's name/arguments item shape, nor requestId, sessionId, or expectedRevision — the last being an optimistic-concurrency token whose meaning is invisible from a bare integer field.

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?

The description names a specific verb and resource ('Apply ordered native tools') and adds the defining scope qualifier 'atomically as ONE undo step', which is what actually distinguishes it from calling the sibling tools directly or using run_script/apply_script_plan. It stops short of naming those siblings explicitly, but the exclusions in the second sentence do most of that work.

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?

There is an explicit negative rule ('run_script and transport/file tools cannot be nested here'), which is genuine routing guidance. However, there is no positive statement of when an agent should batch versus issuing individual calls, and no mention of apply_script_plan as the alternative for scripted work, so the choice is only half-specified.

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