apply_patch

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds behavior they cannot express: the operation is atomic and nothing is written unless every hunk applies, the result reports compiler/linter problems, and a checkpoint id is returned for undo. Atomicity and undo are exactly the non-obvious traits an agent needs before mutating many files.

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?

Front-loads the atomicity guarantee and preference statement in the first sentence, then spends the remainder on the format example, which earns its space for a grammar-driven parameter. It is long, but nearly every line carries required syntax or behavior.

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?

With no output schema, the description correctly describes what comes back (diagnostics plus checkpoint id) and covers the destructive/atomic semantics. It omits how failures are surfaced and how this relates to edit_file/write_file, which are the remaining gaps for a multi-file mutation tool.

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 67% and documents cwd and check, but leaves the required 'patch' parameter undescribed. The description compensates by specifying the exact patch grammar (Begin/Update/Add/Delete/Move/End, +/-/space prefixes, optional anchor) and the context-line convention, which is what makes the required parameter usable.

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 (apply) and resource (multi-file patch) plus a distinguishing trait: atomic, all-or-nothing. Combined with 'Preferred way to change code', an agent can separate it from nearby file-mutation siblings like edit_file and write_file.

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 positions itself as the preferred mechanism for changing code, which is real usage guidance. It stops short of naming the alternatives (edit_file, write_file) or stating when a single-file edit is preferable, so it is clear context without exclusions.

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