Skip to main content
Glama

ratchet

by com.ratchetgate

Check whether an action has already been done

ratchet_check_effect
Read-onlyIdempotent

Look up the recorded state of an action WITHOUT reserving a lease and without consuming your plan allowance. Use it to answer "did I already do this?" — for example when resuming after a crash, or when a user asks whether something went through. To actually perform work, use ratchet_begin_effect instead; this tool never grants permission.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
effect_typeYesNamespaced kind of side effect, e.g. "email.send", "payment.charge", "github.pr.create". Policy is configured per type.
idempotency_keyYes

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses that the tool does not reserve a lease, does not consume plan allowance, and never grants permission. These are meaningful behavioral details that help an agent understand the safety and side-effect profile of calling this tool.

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?

The description is three sentences, front-loaded with the core lookup behavior and free of fluff. Each sentence earns its place: the first defines what it does, the second gives concrete use cases, and the third directs users away from misusing it as a work-performing tool.

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

Completeness4/5

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

For a simple read-only lookup with a rich annotation set, the description covers purpose, usage, and side-effect boundaries well. Since there is no output schema, it could more explicitly describe the return value or status format, but the wording 'did I already do this?' sufficiently conveys the expected outcome.

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?

The schema documents effect_type well, but idempotency_key has no description. The description provides useful conceptual context ('did I already do this?') and implies the role of the idempotency key, but it does not explicitly define the parameters or their formats. Since schema coverage is 50%, the description partially compensates through the use-case narrative but still leaves some ambiguity around idempotency_key.

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 clearly states a specific operation: 'Look up the recorded state of an action' and adds exclusions ('WITHOUT reserving a lease and without consuming your plan allowance'). It also differentiates from ratchet_begin_effect by noting that this tool never grants permission. The title and description together make the tool's purpose unmistakable.

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 description explicitly names when to use this tool: 'resuming after a crash' or when a user asks 'whether something went through.' It also points to the alternative ratchet_begin_effect for performing actual work and explicitly states this tool never grants permission, giving clear selection guidance.

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

All ratchet toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.2/5.0
Disambiguation4/5

Most tools map to clearly distinct lifecycle phases (begin/report/resolve/heartbeat) and are strongly described, but recall, group_status, and list_effects all deal with looking up past effect or workflow state and could be confused when resuming work. The use-case guidance in the descriptions mostly disambiguates them, so this is a minor rather than systemic issue.

Naming Consistency4/5

All tools share the ratchet_ prefix and snake_case, which gives a strong predictable family feel. However, some names follow verb_noun (begin_effect, resolve_effect) while others are noun phrases (effect_receipts, group_status, prevented_loss), so the pattern is consistent in style but not in grammatical form.

Tool Count5/5

Fifteen tools is at the upper end of the ideal range, but the domain is broad enough to justify every entry: effect lifecycle, lease maintenance, state inspection, circuit breakers, policies, receipts, reconciliation, rollback, and usage. Each tool fills a distinct role with no obvious redundancy.

Completeness5/5

The surface covers the full idempotency and safety lifecycle: authorize, execute, report, heartbeat, recover from indeterminate outcomes, verify with receipts, reconcile vendor truth, roll back multi-step work, and monitor budgets and policies. There are no dead ends or missing operations that would strand an agent in this domain.

Resources