Skip to main content
Glama

ratchet

by com.ratchetgate

Say you are still working on an effect

ratchet_heartbeat_effect

Call this periodically during a long action you were authorised to perform, before the lease expires. It tells Ratchet you are alive and extends your hold. Use it when work turns out to take longer than the lease you asked for — a slow vendor, a large export, a retrying upload. Without it, the lease expires while you are still working, the effect is recorded as having an UNKNOWN outcome, and your report is then refused. If it fails with lease_expired or lease_lost, STOP. Your hold is gone and the outcome is already recorded as unknown. Do not keep going and do not retry the action — call ratchet_begin_effect to find out where things actually stand.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
effect_idYes
lease_tokenYes
extend_secondsNoHow much longer you need, from now. Clamped to the policy maximum.

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, which are minimal. The description adds crucial behavioral context: what happens without the call (UNKNOWN outcome, report refused), what failure codes mean, and that retrying is prohibited after failure. This goes far beyond the annotations and is essential for safe use.

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?

Three paragraphs, each earning its place: the action and purpose, the when/when-not context with consequences, and the failure-handling directive. No filler; every sentence adds operational guidance.

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 description is complete for an agent to invoke this correctly: when to call, what happens if it doesn't, what failure means, and what to do next. No output schema exists, but the description sets expectations for success and failure responses sufficiently. The policy maximum clamping behavior is covered in the schema anyway.

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

Parameters4/5

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

Schema coverage is only 33%, so the description compensates. It explains the semantics of the lease extension conceptually ('tells Ratchet you are alive and extends your hold') and clarifies that extend_seconds is relative to now ('How much longer you need, from now'). It does not restate effect_id or lease_token, but those are self-evident from context and the failure-mode language clarifies their lifecycle.

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 verb ('call this periodically'), a clear resource (heartbeat for a leased effect), and the precise purpose: extending a lease while work continues. It clearly distinguishes itself from ratchet_begin_effect and ratchet_report_effect by focusing on the in-progress renewal action.

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 says when to use it ('when work turns out to take longer than the lease'), and gives an explicit when-not-to: after lease_expired/lease_lost, stop and call ratchet_begin_effect instead. This is exemplary routing guidance with named alternatives.

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