Idempotency Key Injection Prompt for Write Tools

This prompt is designed for integration developers who are wrapping payment, provisioning, or state-mutating endpoints behind an AI tool interface. The core job-to-be-done is ensuring that when an AI model calls a write tool, the execution layer can safely retry that request without duplicating the side effect. This is critical in distributed systems where network timeouts, model re-invocation, or execution-layer retry logic can cause the same logical operation to be submitted multiple times. The prompt instructs the model to generate a unique, traceable idempotency key and attach it to the tool call arguments, shifting the responsibility for safe retries from the model to the downstream API.

You should use this prompt when your tool definitions include operations like create_payment, provision_user, update_order_status, or any endpoint where a duplicate call would result in a double charge, duplicate resource, or corrupted state. The ideal user is an engineer building the integration layer between an AI orchestrator and backend services, who needs the model to participate in the idempotency contract. Do not use this prompt for read-only tool calls (e.g., get_balance, list_users) or when the downstream API already manages its own idempotency natively via a header or separate endpoint. Applying it to read operations adds unnecessary complexity and key-generation overhead with no safety benefit.

Before deploying, you must ensure that your execution harness can extract the generated idempotency key from the tool call arguments and pass it to the downstream API according to that API's contract (e.g., as an Idempotency-Key header or a top-level field). The prompt includes instructions for the model to use a predictable key format—typically a combination of an operation type prefix, a unique request identifier, and a timestamp—which makes the key both traceable and collision-resistant. You should also implement eval checks that verify key uniqueness across a test suite, confirm format compliance, and simulate replay scenarios to ensure the downstream system correctly returns the stored result rather than re-executing the operation. The next step is to pair this prompt with a tool call validation guardrail that rejects any write tool call missing an idempotency key before it reaches your backend.

This prompt template is designed to be pasted directly into your system or tool-use prompt for any AI workflow that wraps state-mutating endpoints—such as payment capture, provisioning, or database writes. It forces the model to generate a unique, formatted idempotency key before calling a write tool, declare whether the call is a new execution or a replay, and provide the execution layer with clear instructions on key lifecycle. The template uses square-bracket placeholders so you can adapt it to your specific tool names, key format, and risk level without rewriting the core logic.

textCopy
You are an integration agent responsible for calling write tools safely. Every write operation must be idempotent.

## TOOL SELECTION RULES
- Before calling any tool listed in [WRITE_TOOLS], you MUST generate an idempotency key.
- Read tools in [READ_TOOLS] do not require an idempotency key.
- If the user request does not clearly map to a single write tool, ask for clarification instead of guessing.

## IDEMPOTENCY KEY GENERATION
- Generate a key using the format: [KEY_FORMAT] (e.g., "evt_" + UUIDv4, or "idem-" + SHA256 hash of [IDEMPOTENCY_INPUTS]).
- The key MUST be unique per logical operation. Use these inputs to derive it: [IDEMPOTENCY_INPUTS] (e.g., user_id, operation_type, idempotent_payload_hash, timestamp).
- Do not reuse keys across different operations.

## TOOL CALL OUTPUT CONTRACT
When calling a write tool, produce a JSON object with this exact schema:
{
  "tool_name": "string",
  "arguments": { ... },
  "idempotency_key": "string",
  "is_replay": false,
  "key_lifecycle": {
    "generated_at": "ISO8601 timestamp",
    "expires_at": "ISO8601 timestamp or null",
    "storage_instruction": "One of: 'persist_until_ack', 'cache_ttl_24h', 'derive_only'"
  },
  "replay_detection_note": "Explain how you determined this is a new or replayed call."
}

## REPLAY DETECTION
- If the user provides an existing idempotency key in [REPLAY_KEY_FIELD], treat the call as a replay.
- Set `is_replay` to true and populate `replay_detection_note` with the source of the key.
- Do not generate a new key for replays.

## CONSTRAINTS
- [CONSTRAINTS]
- If the risk level is [RISK_LEVEL], require human approval before dispatching the tool call. Set `key_lifecycle.storage_instruction` to "persist_until_ack" and include an `approval_required` flag.

## EXAMPLES
[EXAMPLES]

To adapt this template, replace the square-bracket placeholders with your concrete values. [WRITE_TOOLS] should list the tool names that mutate state (e.g., create_payment, provision_instance). [KEY_FORMAT] defines the expected key structure, which your execution layer will validate. [IDEMPOTENCY_INPUTS] specifies which fields the model should hash or combine to produce a deterministic key for the same logical operation. [REPLAY_KEY_FIELD] tells the model where to look for an existing key in the user input. [CONSTRAINTS] can include rate limits, cost caps, or permission boundaries. [RISK_LEVEL] controls whether human approval is required—set it to high for payments or provisioning, low for internal state updates. [EXAMPLES] should include at least one new-execution example and one replay example with the correct output shape. After pasting this prompt, validate that your tool execution layer actually enforces idempotency using the generated key—the prompt alone does not guarantee safe retries.

This prompt is designed to sit inside a pre-execution hook in your tool-calling pipeline. When the model selects a write-capable tool (POST, PUT, PATCH, DELETE), the harness intercepts the tool call, runs this prompt to generate an idempotency key and execution metadata, and then attaches the result to the outgoing request. The prompt is not the tool call itself—it is a metadata injection layer that wraps the tool call before it reaches the execution runtime. This separation keeps the model's original tool selection logic clean while adding operational safety guarantees.

Implementation flow: (1) Model selects a write tool and generates arguments. (2) Harness classifies the tool as write based on a tool registry flag or OpenAPI spec method. (3) Harness calls this prompt with [TOOL_NAME], [TOOL_ARGUMENTS], [IDEMPOTENCY_KEY_FORMAT] (e.g., {service}-{entity}-{uuid}), and [KEY_TTL_SECONDS]. (4) The prompt returns a structured JSON object containing idempotency_key, key_format_valid, injection_timestamp, and execution_instruction (e.g., NEW_EXECUTION or REPLAY_DETECTED). (5) The harness injects the key into the tool call header or payload according to the target API's idempotency contract (typically an Idempotency-Key header or a top-level field). (6) The execution layer stores the key with a TTL, checks for duplicates before dispatch, and returns the replay status to the harness.

Validation and safety checks: Before the tool call executes, validate that the generated key matches the declared format using a regex validator. Check the key store for collisions—if a duplicate exists and the payload differs, abort and log a collision event for human review. If the duplicate exists with the same payload, return REPLAY_DETECTED and skip execution. Retry logic: If the write tool fails with a network error or timeout, the harness retries with the same idempotency key, not a new one. This is the core value of the pattern. Set a maximum retry budget (e.g., 3 attempts) and a deadline (e.g., 30 seconds). After exhaustion, escalate to a dead-letter queue with the full key and payload for manual reconciliation. Logging: Emit structured logs at each stage—key generation, duplicate check, injection, execution, and replay detection—so that every write operation is traceable end-to-end.

Model choice and latency: This prompt is lightweight and should run on a fast, cheap model (e.g., GPT-4o-mini, Claude Haiku, or a local fine-tuned classifier) because it adds latency to every write path. If your write volume is high, consider caching generated keys for identical tool-argument hashes within the TTL window, or pre-generating keys client-side using a deterministic hash of the request payload. Human review trigger: If the prompt detects a key collision with a different payload, or if the key format validation fails, route to a human review queue before executing. Do not silently regenerate a new key on collision—that defeats the idempotency guarantee. What to avoid: Never use this prompt for read-only tools; it adds unnecessary latency and key-store overhead. Never skip the duplicate check before execution. Never allow the execution layer to mutate state without first persisting the idempotency key.