undo_last_head_change

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

With no annotations, the description carries the whole burden, and it does disclose a meaningful behavioral trait: only *head-mutating* reflog entries count, so non-head-mutating entries are skipped. However it says nothing about permission/auth requirements, reversibility of the undo, or what happens when no head-mutating entry exists.

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 first sentence is tight and correctly front-loaded, but three of the four lines are promotional/upsell copy ('Everything in Free... Requires Kiln Pro... Upgrade: <url>') that does nothing to help an agent invoke the tool. Roughly half the payload is waste.

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 zero annotations, no output schema, and 0% schema coverage, the description leaves major gaps: what artifact_type and operator control, error behavior when no reflog entry qualifies, and any auth/tier prerequisites. The mechanism sentence is good but insufficient on its own.

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% across 3 parameters, so the description must compensate. It clarifies branch_id as the pointer being moved, but artifact_type and operator are given no meaning anywhere, leaving two of three parameters fully opaque.

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 opening sentence gives a specific verb ('snap back'), a precise resource (branch_id), and the exact mechanism (the old_head of the most recent head-mutating reflog entry). That mechanism is distinctive, but the description never names or contrasts against close siblings such as restore_from_reflog_entry, show_reflog, or rollback_design_version, so it stays at 4 rather than 5.

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?

'One-tap recovery' implies the scenario (undoing an accidental head move), but there is no explicit when-to-use, no when-not-to-use, and no routing to the alternative reflog/rollback tools listed as siblings. The inferrable context is the only guidance present.

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