Report the outcome of an effect you executed

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.