discard_rewrite

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

With no annotations, the description carries the full behavioral burden, yet it only says a proposal is discarded. It does not state whether the discard is reversible, whether confirmation is needed, what happens if the rewrite was already applied or doesn't exist, or what permissions are required for this destructive operation.

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?

A single short sentence with the scoping qualifier up front and no filler. Nothing is wasted; it is simply brief because the description is thin, not because it is padded.

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 no annotations, no output schema, and an undocumented parameter, the description is too sparse. It omits reversibility, error cases (already applied / not found), and any tie-in to the proposal lifecycle (propose_rewrite, list_rewrites, apply_rewrite) that an agent needs to invoke it safely.

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?

There is one required parameter, rewrite_id, with 0% schema description coverage, so the description must compensate. It never mentions the parameter or what value is expected (an id from list_rewrites / propose_rewrite), leaving the identifier semantics implied at best.

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 (discard) and resource (a proposed rewrite), and the parenthetical '(not applied)' scopes it away from applied rewrites, implicitly separating it from revert_rewrite. It does not name the sibling explicitly, but the scope qualifier is enough for an agent to distinguish it.

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 phrase '(not applied)' implies usage: call this only for proposals that have not been applied, and use revert_rewrite for applied ones. That condition is implied rather than stated, and no prerequisites or exclusions are given explicitly.

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