Idempotency Check Prompt for Retried Tool Calls

This prompt is for integration developers and reliability engineers who manage agent workflows that retry tool calls. The core job-to-be-done is preventing double-execution of non-idempotent operations—such as creating a duplicate payment, sending a second email, or provisioning a redundant resource—when a tool call fails and the orchestrator decides to retry. The ideal user is someone who already has a retry decision prompt in place but needs a safety gate before the retry is actually dispatched. Required context includes the original tool request payload, the error or timeout response, any partial state or side effects observed, and the proposed retry payload. Without this context, the prompt cannot assess whether the previous attempt left the system in a state that makes a naive retry dangerous.

Do not use this prompt when the tool operation is provably idempotent by contract (e.g., a PUT request with a client-supplied UUID, or an API that explicitly guarantees idempotency keys). In those cases, a standard retry decision prompt is sufficient and this check adds latency without benefit. Also avoid this prompt when the cost of double-execution is negligible or easily reversible—adding an idempotency gate for a read-only query or a cache-write is over-engineering. The prompt is most valuable in high-stakes domains like payments, provisioning, notifications, and database mutations where a duplicate operation creates a customer-facing incident or requires manual reconciliation. If the tool's side effects are opaque or the system cannot observe partial state, the prompt should default to a conservative 'do not retry' recommendation and escalate for human review rather than guessing.

After reading this section, you should know whether your retry workflow needs an idempotency safety gate. If it does, proceed to the prompt template section to copy the implementation-ready prompt. Before deploying, ensure you have a way to capture and pass the previous attempt's observable state—without that, the prompt cannot do its job. If your tool lacks observability into partial side effects, invest in that instrumentation first, then return to this playbook.

The prompt below is designed to be dropped into an agent's retry decision loop before re-invoking a non-idempotent tool. It forces the model to reason about what the tool already did, what state might exist from a partial execution, and whether replaying the same payload would cause double-execution, corruption, or inconsistency. Use this when the tool's documentation or API contract does not guarantee idempotency, or when the failure occurred mid-execution and you cannot determine the server-side outcome.

textCopy
You are an idempotency safety checker for retried tool calls in a production agent system.

Your job is to analyze a failed tool call and determine whether retrying it with the same or modified arguments is safe, or whether state reconciliation must happen first.

## INPUT
- Tool name: [TOOL_NAME]
- Tool description: [TOOL_DESCRIPTION]
- Original arguments: [ORIGINAL_ARGUMENTS]
- Retry arguments (may differ): [RETRY_ARGUMENTS]
- Error context: [ERROR_CONTEXT]
- Known partial state or side effects from the failed attempt: [PARTIAL_STATE]
- Idempotency guarantees from tool documentation (if any): [IDEMPOTENCY_GUARANTEES]
- Business impact of double-execution: [BUSINESS_IMPACT]

## OUTPUT_SCHEMA
Return a JSON object with these fields:
{
  "retry_safe": boolean,
  "risk_level": "none" | "low" | "medium" | "high" | "critical",
  "double_execution_risk": boolean,
  "state_corruption_risk": boolean,
  "recommended_action": "retry_as_is" | "retry_with_reconciliation" | "verify_state_first" | "abort_and_escalate",
  "reconciliation_steps": [string] | null,
  "verification_queries": [string] | null,
  "modified_arguments": object | null,
  "rationale": string,
  "confidence": 0.0-1.0
}

## CONSTRAINTS
1. If the tool creates resources (POST), assume retry may create duplicates unless the tool explicitly supports idempotency keys.
2. If the error is a timeout or network failure, the original request may have succeeded server-side. Flag this explicitly.
3. If [PARTIAL_STATE] contains evidence that the operation partially completed, reconciliation_steps must be non-empty.
4. If [BUSINESS_IMPACT] is "high" or "critical" and retry_safe is false, recommended_action must be "verify_state_first" or "abort_and_escalate".
5. Never assume idempotency without explicit evidence from [IDEMPOTENCY_GUARANTEES].
6. If confidence is below 0.7, recommended_action must not be "retry_as_is".
7. modified_arguments should only be populated if a safe modification (e.g., adding an idempotency key, deduplication token, or conditional check) can reduce risk.

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

Adapt this template by replacing the square-bracket placeholders with data from your agent's execution context. The [PARTIAL_STATE] field is the most critical input—if your system cannot provide any evidence about what the tool did before failing, set this to "unknown" and expect the model to default to conservative recommendations. The [EXAMPLES] placeholder should contain 2-3 few-shot examples covering common scenarios: a safe retry on a read-only tool, a dangerous retry on a payment or write operation with unknown server state, and a reconciliation-required case where partial state is known. The [RISK_LEVEL] placeholder should reflect your domain's tolerance: set to "high" for financial operations, "medium" for CRM updates, or "low" for internal logging tools. Wire this prompt into your retry orchestrator so it executes before every non-idempotent retry attempt, and log the full JSON output to your audit trail for post-incident review.

The idempotency check prompt is not a standalone safety net—it is a decision gate inside your tool execution harness. Wire it into the retry path immediately after a non-idempotent tool call fails or times out, but before any retry is issued. The harness must supply the prompt with three concrete inputs: the original tool request payload, the raw error or timeout context, and any partial state or side-effect evidence the system can observe (e.g., a created resource ID in the error body, a database record that appeared despite the timeout, or a log entry from an upstream system). Without this evidence, the prompt will default to a conservative 'do not retry' recommendation, which is the correct production posture.

Build the harness to call this prompt synchronously and block the retry until a decision is returned. Parse the output into a structured decision object with at minimum three fields: retry_safe (boolean), required_reconciliation_steps (array of strings), and rationale (string). If retry_safe is false, route to a human review queue or a fallback tool—never silently drop the operation. If retry_safe is true and required_reconciliation_steps is non-empty, execute those steps before retrying. Reconciliation steps might include checking for duplicate records, reversing a partial state change, or fetching the current resource state to compare against the original intent. Log every decision, the full prompt input, and the raw model output for auditability. For high-risk operations (payments, provisioning, destructive actions), add a hard requirement that retry_safe must be accompanied by explicit evidence references in the rationale before the harness allows the retry to proceed.

Choose a model with strong reasoning capabilities for this prompt—small or fast models often miss subtle side-effect indicators in error bodies. Set temperature to 0 to maximize determinism. Implement a strict output validator that rejects any response missing the required fields or containing ambiguous boolean values. If validation fails, default to retry_safe: false and escalate. Add an eval suite that tests the harness end-to-end with scenarios including: duplicate creation risk (the operation partially succeeded), state corruption risk (the operation wrote invalid data), clean failure (nothing happened, retry is safe), and ambiguous evidence (the error body hints at partial success but provides no resource ID). Measure both the correctness of the retry decision and whether the harness correctly blocked retries when the prompt output was malformed. The goal is a harness that fails closed, never open.