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

Annotations mark the tool as destructive, and the description adds substantial behavioral detail beyond that: edits are validated together so nothing is written if any are invalid, writes are sequential across files, late failures name what was already applied, and old_string must be unique unless replace_all is set. This gives an agent an accurate model of failure and side effects.

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 dense but every sentence earns its place, covering purpose, mechanics, usage conditions, prerequisites, uniqueness rules, atomicity, ordering, edge cases, and follow-up. The most important differentiator is front-loaded in the first sentence, making the description scannable despite its length.

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 destructive multi-file editing tool, the description covers all essential operational context: when to use it, how to prepare inputs, what happens on validation failure, how writes behave across files, what cannot be edited, and what to do afterward. The presence of an output schema means return-value details are not required here.

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?

The schema already provides 100% coverage and detailed descriptions for all parameters, so the baseline is strong. The description enhances this by clarifying how to use old_string (copy exactly after read_files, add context or use replace_all when non-unique) and reinforcing that new_string "" deletes the match, but most core semantics are already present in the 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 opens with a precise statement of what the tool does: 'Change PART of a file without resending it — the counterpart to write_files.' This names the specific verb (change), the resource (existing files), and differentiates the tool from its closest sibling, write_files.

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 explicitly says when to use this tool: whenever the file exists and only a line, block, or URL changes, with a concrete token-waste rationale. It also gives prerequisites (read_files first, copy text exactly), exclusions (not for new files or binaries), and the follow-up step (then publish_app).

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