uncommit_write

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

With no annotations provided, the description carries the full burden and does so well: it discloses atomic restoration, deletion of files created by the commit, no re-staging/re-commit need, refusal on file drift, and the force override. These are the critical behavioral traits an agent needs before invoking a destructive undo.

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 definition is compact and front-loaded: the core undo behavior appears first, followed by the refusal condition and mode requirement. Every sentence adds operational guidance with no filler.

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 two-parameter mutation tool with no annotations and no output schema, the description covers the critical invocation conditions: atomic restore behavior, mode gating, drift refusal, and the alternative path in propose mode. Return values need not be explained because no output schema exists.

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 only 50%: force is documented in the schema and reinforced by the description, but commit_id has no schema description and the description does not explicitly explain its role. The description adds useful context around force and the workflow, but does not fully compensate for the undocumented required parameter.

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 and resource: undo a committed write and restore pre-commit content atomically. It distinguishes this from related write-path tools by explaining the no-recommit behavior and naming siblings used in propose mode.

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 explicit when-to-use and when-not-to-use guidance: requires write_mode 'write', and in 'propose' mode directs the agent to revert_write + commit_write instead. It also states the file-drift condition and the force override.

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