patch_group

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

With no annotations, the description carries the full behavioral burden and does so well: all-or-nothing atomicity, the rationale (a half-applied change is worse than none), and the rollback semantics including reverse-order unwinding on failure. These are exactly the traits an agent needs before committing a multi-op mutation.

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, front-loaded with the atomic guarantee before the usage condition and the rollback detail; nothing is padding. The example clause is slightly long but earns its place by making the multi-file trigger concrete.

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 one-parameter batched mutation with full schema description coverage and no output schema, the essentials are present: transaction semantics, usage trigger, and failure behavior. Error-reporting detail (e.g. what is returned when an operation fails) is the only notable omission, and it is minor given no output schema exists to explain returns.

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 100% and the single 'operations' property already documents the op vocabulary (fix_symbol | fix_range | insert_symbol | create_file) and that order matters. The prose adds no parameter-level detail beyond that, so the baseline 3 for schema-dominated parameters is appropriate.

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 several operations as one transaction') and immediately scopes it as the multi-file batching counterpart to the single-op siblings. An agent can tell from the 'spans more than one file' condition that this is the grouped variant of fix_symbol/insert_symbol/create_file 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 gives an explicit trigger ('use whenever a change spans more than one file') and a concrete motivating example (new class + require_once + returning method), plus the failure consequence. It stops short of naming the alternatives (e.g. 'for a single edit use fix_symbol'), so the routing is inferable rather than spelled out.

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