Apply patch

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

Annotations already indicate the tool is mutating (readOnlyHint=false), idempotent (idempotentHint=true), and not destructive (destructiveHint=false). The description adds one useful implementation detail: it prefers the `patch` binary and falls back to a naive implementation. However, it does not explain failure behavior, conflict handling, or whether the fallback can partially apply changes.

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?

The description is a single front-loaded sentence with no filler. Every clause adds information, including the fallback behavior. It is appropriately sized for the tool's apparent simplicity.

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 mutation tool with minimal schema descriptions, the description is too thin to fully support correct invocation. It omits behavior of dry_run, failure handling, and any distinction against direct file editing tools. The presence of an output schema does not compensate for these gaps.

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%, so the description carries the full burden for explaining parameters. It clarifies that `patch` should contain a unified diff, but it says nothing about `path` semantics or the `dry_run` flag. This is only partial compensation for an otherwise bare schema.

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 states a specific verb ('apply'), a concrete resource ('a file'), and a precise input format ('unified diff'). This clearly distinguishes it from sibling file-editing tools like write_file or edit_file, which operate on raw content or line edits.

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?

The description implies a use case—applying a unified diff—but provides no explicit guidance about when to prefer this tool over alternatives such as edit_file, nor any exclusions or prerequisites. The agent must infer the appropriate context.

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