ratchet

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

There is no output schema and annotations only carry readOnlyHint:false, so the description bears the full behavioral burden — and it is exhaustive. It discloses exactly what happens for each returned decision, that Ratchet does not collect money but only counts it, that only hashes of dimensions are stored, that raw payload content never persists, and how vendor_idempotency_key propagates. No ambiguous side effects are left undisclosed.

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?

Well-structured with bullets, decision lists, and code blocks, but noticeably verbose — budget_warning is explained twice, the deterministic idempotency-key rule appears twice, and several sentences restate the same guarantees. Every sentence mostly earns its place given the complexity, but trimming redundancy would tighten it without losing meaning.

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?

With no output schema, the description fully defines the return contract — every possible decision value ('execute', 'duplicate', 'in_flight', 'blocked', 'approval_required', 'denied') and its required follow-up. The complex nested objects (payload, compensation, dimensions) and nuanced fields (lease_seconds, group_key, compensates_effect_id) are each explained with concrete examples, leaving no gap an agent needs to guess about.

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 coverage is 100%, but the description adds substantial meaning beyond it: it tells when parameters are mandatory in practice ('ALWAYS SEND THIS when the action costs money', 'SEND THIS whenever the action targets a specific recipient'), explains the deterministic key requirement, how vendor shapes the key, how dimensions enable per-destination ceilings, and why omitting cost is refused with cost_required. This goes well past the baseline for full schema coverage.

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 an explicit verb ('Ask permission'), a specific resource ('side effect'), and the action's scope ('perform') — 'Ask permission to perform a side effect' unambiguously names what the tool does. It also implicitly separates itself from siblings like ratchet_report_effect (which reports the effect) so an agent can pick the right call.

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?

Gives explicit timing — 'Call this IMMEDIATELY BEFORE performing any side effect' — and explicit when-not-to-use behavior for each decision value (duplicate, in_flight, blocked, approval_required, denied). It names the sibling tools to call next (ratchet_report_effect, ratchet_resolve_effect, ratchet_unwind_group), giving clear alternatives rather than leaving them implicit.

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

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

Beyond the annotations, the description reveals important consequences: lease expiry records the effect as UNKNOWN, the report is refused, the hold is gone, and retrying is prohibited. This is rich behavioral context and does not contradict the annotations.

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 description is front-loaded with the primary call instruction, followed by concrete trigger examples and a compact failure-handling protocol. Every sentence contributes necessary operational information without filler.

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 safety-critical keep-alive tool, it covers when to call, why it matters, what happens on failure, and what to do next. The only notable gap is the untold semantics of the two required parameters, which keeps it just short of fully complete.

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 coverage is only 33%: extend_seconds is described, but the required effect_id and lease_token are not. The description never explicitly explains what these parameters mean or where an agent should obtain them, relying instead on general lease/effect jargon, so it does not fully compensate for the low schema coverage.

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 description states a specific action: periodically call to extend a lease during a long authorized action. It clearly distinguishes this from sibling lifecycle tools by naming ratchet_begin_effect as the recovery path and framing this tool as the keep-alive/extend operation.

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?

It gives explicit conditions for use ('when work turns out to take longer than the lease you asked for') with concrete examples, and explicit conditions for stopping ('If it fails with lease_expired or lease_lost, STOP'). It also names the alternative to call instead, ratchet_begin_effect.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations, including why breakers open, what resets_at null means (human-opened breaker), and what effect_type '*' signifies. This gives the agent enough understanding to interpret results safely.

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 description is front-loaded with the exact trigger condition and organized into scannable bullet points. Each bullet provides actionable, non-redundant guidance. The length is justified because the tool guides critical safety behavior around circuit breakers.

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 read-only, zero-parameter tool with no output schema, the description covers everything an agent needs: when to call, how to interpret key response fields, what actions to take, and what not to do. The additional safety context about human-opened breakers and wildcard effect_type makes it complete for safe invocation.

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?

The input schema has zero parameters, so the baseline is 4. The description does not need to explain parameters, but it does clarify important response semantics like resets_at and effect_type '*', which indirectly helps the agent understand what information the tool returns. There is no parameter ambiguity to resolve.

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 description clearly states this tool is for checking circuit breaker status after a begin call returns 'approval_required' or 'denied' with a breaker-related reason. It distinguishes this from siblings by focusing on the circuit breaker concept and its operational implications. The title also reinforces a specific, check-only purpose.

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 description explicitly says when to call: 'Call this when a begin returned "approval_required" or "denied" and the reason mentions a circuit breaker.' It also provides strong when-not guidance, such as 'Retrying will not help' and 'do not wait, and do not poll' when resets_at is null, plus explicit prohibitions against workarounds.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral facts beyond those annotations: it does not reserve a lease, does not consume plan allowance, and never grants permission. It stops short of describing the return payload or possible state values, which is a minor gap.

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?

Three focused sentences, front-loaded with the core purpose and non-behaviors. Every sentence adds information, and there is no filler or redundancy.

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 simple two-parameter read tool with strong annotations, the description covers when to use it, why, and what it does not do. The only notable gap is that no output schema exists and the description does not mention possible return states or not-found behavior, so an agent may not know what response to expect.

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?

The schema covers effect_type well with a detailed description and examples, but idempotency_key has no description. The tool description itself adds no parameter-level meaning beyond referring to an "action," so it does not compensate for the missing idempotency_key semantics. At exactly 50% schema coverage, this lands at a mid score.

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 description uses a specific verb and resource: "Look up the recorded state of an action." It also explicitly names the sibling tool it is not (ratchet_begin_effect), making the purpose immediately distinguishable from similar effect tools.

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?

It gives concrete use cases: resuming after a crash and answering whether an action went through. It also explicitly tells the agent when NOT to use it, pointing to ratchet_begin_effect for actual work and stating this tool never grants permission.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description reinforces that with 'without changing anything' and adds useful state-semantics context (undoable, undone, irreversible, unknown). This goes beyond simply restating the annotations, though it does not address auth or rate-limit behavior.

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?

Two tight sentences front-load the core behavior before the use case, and every phrase earns its place. The description is easy to scan and free of filler.

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 single-parameter, read-only inspection tool with no output schema, the description covers the tool's purpose, output categories, and canonical use case. It leaves minor gaps around group_key semantics and error behavior, but nothing critical for deciding to call it.

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?

The schema provides only a string type and no description for group_key, and the description never names or explains the parameter. An agent must infer that group_key identifies the unit of work from the tool name; the description does not define its form, how to obtain it, or any constraints.

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 description names a specific action and resource: it 'shows every step in a multi-step unit of work' and enumerates exactly which categories of step state are reported. This makes it easy to distinguish from sibling inspection tools like get_run or get_effect, which target different resources.

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?

It gives an explicit trigger context: use it to answer 'where did this workflow actually get to?' after a crash. It does not, however, contrast itself with sibling inspection tools or state when not to use it, so it stops short of full alternative routing.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds concrete behavioral detail about what policy fields are returned, including indeterminate handling.

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?

One focused sentence conveys resource, policy contents, and usage guidance without redundancy.

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 simple one-parameter read-only tool, the description fully enumerates the policy aspects returned and provides an actionable usage hint, making it self-sufficient despite the lack of an output schema.

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?

The single parameter effect_type is fully described with a namespaced format and concrete examples, matching the 100% schema coverage.

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 ('Shows'/'Read') and resource ('policy for an effect type'), and the detailed policy elements distinguish it clearly from sibling getter tools like ratchet_get_effect or ratchet_get_group.

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?

Explicitly instructs to 'Check this before designing a retry strategy', giving a clear use case for when to call this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds valuable extra context beyond those: it under-reports rather than flatters, it depends on caller-declared costs, and the number represents avoided vendor spend, not money paid to Ratchet. This goes well beyond the annotation defaults and gives the agent a clear mental model of the tool's behavior and caveats.

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 description is efficient and front-loaded: the first sentence states the core purpose, the second explains the under-reporting behavior, the third gives the critical dependency in an 'IMPORTANT' callout, and the fourth clarifies the financial meaning. Every sentence earns its place; there is no filler or redundancy.

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 zero-parameter tool with no output schema, the description covers all essential information: what is counted, the time window, the source of the data, the reliability caveat, and the interpretation of the result. An agent would know exactly when to call this tool and what to expect. It also anticipates the common misuse of misinterpreting the number as actual revenue.

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?

The tool has zero parameters, so the schema trivially covers 100% of them. With no parameters to explain, the baseline for this dimension is 4. The description does not need to add parameter details, and it correctly references a parameter on a sibling tool (estimated_cost_micros) which is not this tool's parameter. Nothing is missing here.

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 description uses a specific verb ('counts') and a clear resource ('duplicate actions refused in the last 30 days'), and states exactly what it measures (refusals and their would-be cost). It also clarifies the semantics of the number ('money not spent at your vendors, never money paid to Ratchet'), which distinguishes it from any payment-related tool. This is unambiguous and differentiates it from siblings like ratchet_get_usage.

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 description gives a critical prerequisite for meaningful use: 'pass estimated_cost_micros on ratchet_begin_effect or this reads zero'. It also clarifies the context (prevented loss) and the under-reporting behavior. However, it does not explicitly name an alternative tool or state when not to use this one, so it lacks the explicit exclusions seen in the highest tier.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds important behavioral detail: it separates succeeded, in-flight, failed, and unknown outcomes, and flags unknown outcomes as the only category that can hurt the caller. It also discloses the relative cost of listing the same effects, which is valuable for an agent optimizing context usage.

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 description is front-loaded with the core instruction, then explains return categories, safety semantics, and cost — all in a compact, well-organized block. Every sentence adds operational value, and the warning about unknown outcomes is placed where it matters.

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?

Despite having no output schema, the description tells the agent what categories of results to expect and how to interpret them. It covers when to call the tool, what it returns, what to avoid repeating, and why the unknown category is important — more than enough for correct invocation.

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 100%, and the description references the run id's origin ('the run id you passed to ratchet_begin_effect'), adding a small linkage beyond the schema. This is useful but does not substantially extend the parameter meaning; the baseline of 3 is appropriate.

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 and resource: 'recall the work already gated under a run id.' It clearly distinguishes itself from the broader listing tools by focusing on the run-level view and enumerating the exact outcome categories returned.

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 description explicitly says to call this FIRST when resuming a task after restart, handoff, or context compaction, and warns against doing anything that might repeat prior work. This gives an agent a clear trigger condition and operational precedence.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read behavior is covered. The description adds useful nuance: it reports 'remaining included effects for the month' and 'today's declared external spend,' implying temporal scoping and a possible difference between declared and actual spend. It does not contradict annotations.

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?

Two sentences with no filler. The first sentence front-loads the return contents, and the second immediately gives a practical use case. Every word contributes value.

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 parameterless read-only tool with rich annotations, the description is complete: it names all major return components and explains why an agent would call it. No output schema exists, but the listed data elements are sufficient for selection and invocation.

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?

The tool has 0 parameters and the schema description coverage is 100%, so parameter semantics are trivially satisfied. The baseline for a zero-parameter tool is 4, and the description adds relevant context about what the returned information is used for.

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 description clearly states the verb ('Returns') and the resource ('current plan, remaining included effects, prepaid credit balance, today's declared external spend'). It distinguishes this read-only usage/credit tool from the sibling circuit/effect/group tools through its specific focus on plan, credit, and spend data.

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 description includes explicit when-to-use guidance: 'Use it to warn a user before a long run exhausts an allowance or a budget.' It does not name alternative tools or state when not to use it, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: results are workspace-scoped, time-bound ('recent'), and it defines the operational meaning of 'indeterminate' as outcome unknown and still needing verification. There is no contradiction with the annotations.

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?

Two sentences, with the core action front-loaded ('Review recent effects'), followed by optional scoping and a concrete use case. No wasted words; every sentence earns its place.

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?

The essential invocation context is covered: what is listed, the workspace scope, available filters, and a concrete use case. Annotations cover safety and idempotency. With no output schema, the return shape is left implied, and siblings are not explicitly differentiated, but for a simple list tool this is largely sufficient.

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 only 25%, so the description must compensate. It adds meaning for state (including the indeterminate semantics) and run ('filter by run'). effect_type already has a schema description, and limit is self-evident. Some parameter detail is still left to inference, but the added guidance is meaningful.

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 clear verb ('Review') and resource ('recent effects for this workspace'), and frames a specific diagnostic use case ('find unresolved work'). It is unambiguous as a list/read tool, though it does not explicitly contrast with sibling tools such as ratchet_effect_receipts or ratchet_check_effect, so it stops short of perfect sibling differentiation.

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?

Gives an explicit when-to-use: 'Use it to find unresolved work' and recommends a concrete filter ('state indeterminate'). It also notes optional filters by state or run. It does not list when-not-to-use or alternative sibling tools, so it does not earn a 5.

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

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

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description adds substantial behavioral context: receipts are signed, signatures cover exact bytes in `body`, verification works offline against a published Ed25519 key, and the server does not need to be trusted. This meaningfully informs the agent about what the tool guarantees.

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 description is three focused sentences with no wasted words. The core behavior is front-loaded, then the cryptographic detail, then the practical use case. Every sentence earns its place.

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 read-only single-parameter tool with no output schema, the description sufficiently explains what is returned, what each receipt proves, how verification works, and when the tool should be invoked. Nothing essential is missing for an agent to call it correctly.

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?

The input schema has 100% coverage and already documents `effect_id` as 'The effect to fetch receipts for'. The description mentions fetching receipts for 'one effect', which aligns with the parameter, but does not add additional semantic detail beyond the schema.

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 description names a specific verb ('Returns'), a specific resource ('signed receipt for every decision made about one effect'), and a notable inclusion ('refusals included'). This clearly distinguishes it from sibling tools like ratchet_list_effects or ratchet_get_effect.

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 description explicitly states when to use the tool: 'Use this when a human asks you to PROVE an action was or was not authorised'. It contrasts with the alternative behavior of merely asserting something, though it does not name a specific sibling tool as an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it warns that unseen keys correspond to code paths that acted without asking and that retrying can cause duplicate side effects. It also gives an explicit operational instruction to send references only and never credentials.

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?

Three sentences with no wasted words: the operation, the practical risk, and the security constraint are each addressed. The most important semantic is front-loaded, and the guidance is directly actionable.

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 two-parameter, no-output-schema tool with strong annotations, the description covers the operation, the business rationale, and the risk model. The main gap is the undocumented 'effect_type' parameter, which prevents the description from being fully self-sufficient.

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 coverage is 50%: only 'keys' has a description, while 'effect_type' is undocumented. The description clarifies that keys are the vendor-reported idempotency keys, but never explains what effect_type means or what values it accepts. The description partially compensates for the missing schema coverage but leaves a required parameter meaningfully unexplained.

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 description uses a specific verb ('returns') and resource ('idempotency keys for actions a vendor says actually happened') and clearly separates the two outcomes: went through Ratchet vs. never seen. This distinguishes it from sibling tools like ratchet_list_effects or ratchet_get_effect, which inspect stored effects rather than reconcile external facts against them.

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 intended scenario is explicit: you have idempotency keys from a vendor and want to find actions that bypassed Ratchet. The description does not name alternative tools or state when not to use it, but the context is clear enough that an agent can infer this is for reconciliation rather than for inspecting a single effect or listing effects.

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

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

The description discloses critical behavioral consequences beyond the annotations: successful reports are replayed to duplicate callers, a false 'failed' can license a duplicate action, and an unreported uncertain outcome safely records 'indeterminate' via lease expiration. This is exactly the kind of safety-relevant context an agent needs.

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 description is front-loaded with the most important instruction, uses short imperative sentences, and every sentence carries weight. The formatting with line breaks makes the success/failure/unsure branches easy to parse.

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 tool with six parameters and no output schema, the description gives sufficient behavioral context to call it correctly. Minor gaps remain around effect_id and actual_cost_micros, but the core decision logic and required parameters are thoroughly covered.

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?

The description adds valuable semantics for the outcome parameter and the result object, explaining when 'succeeded' vs 'failed' is appropriate and that results are replayed verbatim. It also mentions the lease_token. However, it does not explicitly explain effect_id or actual_cost_micros, though the schema and context partially cover them.

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 description clearly states the tool's purpose: report the outcome of an effect after it has been executed, specifically after ratchet_begin_effect authorized it. It distinguishes itself from the begin/check/resolve siblings by focusing on post-execution reporting and by naming the exact triggering condition.

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?

Provides explicit when-to-use guidance: call immediately after the action, report 'succeeded' normally, report 'failed' only when certain the action did not reach the outside world, and do not report anything if uncertain. This gives the agent a precise decision procedure and even specifies the alternative behavior — letting the lease lapse.

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

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

Goes beyond annotations by explaining that this mutates the effect's disposition, that it must be based on verified facts, and that incorrect resolution has serious consequences. It does not detail reversibility, idempotency, or return behavior, but annotations are sparse and the description carries the safety-critical context well.

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?

Three sentences, all load-bearing, with the critical precondition front-loaded. No filler, no repetition of the schema, and every sentence contributes to correct invocation behavior.

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?

Covers the essential correctness context: when to call, what outcomes mean, how to provide evidence, and the danger of guessing. It leaves out return/error behavior and the purpose of the `result` field, but for a settlement action the provided context is largely sufficient for an agent to call it correctly.

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?

Clarifies the outcome enum by mapping each value to a real-world state ('succeeded' if the action occurred, 'failed' if not, 'cancelled' to abandon), and explains evidence as verification stored in the audit trail. However, schema description coverage is only 25% and the description does not explain the `effect_id` parameter or the nested `result` object, so it only partially compensates for low schema coverage.

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 ('resolve') and resource ('effect'), and defines the exact purpose: settling an effect whose outcome was left indeterminate. The description makes the tool's domain distinct from siblings like check, report, or begin by focusing on recording the verified real outcome.

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?

Gives an explicit precondition: use ONLY after checking the third-party system and now knowing what happened. It also gives a firm when-not: never guess, because incorrect resolution causes duplicate or lost actions. This is clear usage guidance even though sibling tools are not named.

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

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.

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.

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.

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.

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.

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.