Skip to main content
Glama
thearchitect0x-glitch

ratchet-mcp

by thearchitect0x-glitch
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Roll back a multi-step unit of work

ratchet_unwind_group

Undoes a group of completed effects in reverse order after a failed multi-step workflow, providing the exact compensation steps and gating each undo to prevent double execution.

Instructions

Call this when a multi-step workflow fails partway and the steps that already succeeded must be undone — a booking made but not paid for, a resource created but not configured. Returns the exact compensations to perform, in the order to perform them, which is the REVERSE of the order they succeeded in. Undoing forwards can strand a step that depended on an earlier one. Ratchet does NOT perform the compensations. For each step: call ratchet_begin_effect with the step's suggested_idempotency_key and compensates_effect_id, do the real undo, then call ratchet_report_effect. Gating the undo is what stops a retry from refunding twice. Read unresolved first. If any effect in the group has an unknown outcome, STOP and resolve it before undoing anything around it. Read irreversible too: those steps succeeded and declared no way to undo themselves, so a human has to decide what to do about them. Say so plainly rather than implying the rollback was complete.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
reasonNoWhy it is being rolled back. Stored for the operator.
group_keyYesThe unit of work to roll back, e.g. "booking:trip_8812".

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description discloses critical behavior: it returns a plan rather than executing the undos, requires a specific interleaved compensations protocol, and explains the reversal order rationale. It also exposes edge-case behavior around unresolved and irreversible effects, and warns against implying a complete rollback when it is not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence adds essential operational value: when to use, what it returns, what it does not do, the required follow-up calls, and the important caveats. The description is dense but not padded, and the trigger condition is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition is complete for a complex coordination tool with no output schema: it explains return semantics (compensations in reverse order), the required interaction with sibling tools, the reason for the order, and the unresolved/irreversible fields the agent must inspect. No critical operational detail appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents group_key and reason. The description does not add meaningful parameter-specific detail beyond referring to 'group' and 'steps,' so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific trigger ('multi-step workflow fails partway') and a clear function: return the exact compensations to perform in reverse order. It also distinguishes this tool from its siblings by explicitly saying 'Ratchet does NOT perform the compensations' and referencing ratchet_begin_effect/ratchet_report_effect as follow-up calls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The first sentence tells the agent exactly when to call this tool, and the description provides the full follow-up sequence: call ratchet_begin_effect, perform the undo, call ratchet_report_effect. It also gives explicit conditional guidance: read unresolved first and stop if an effect has an unknown outcome, and surface irreversible steps to a human.

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

Deploy Server

Other Tools