Use this prompt when you are a reliability engineer, platform developer, or SRE documenting which tools in your AI system are safe to retry and under what specific conditions. The job-to-be-done is producing a machine-readable and human-auditable idempotency annotation for a single tool's description. This annotation must answer three questions: can this tool be safely retried after a timeout or failure, what unique key should the system use to detect duplicates, and what is the blast radius of an accidental double execution? The ideal user has the tool's source code, API contract, or existing runbook available as [CONTEXT] and needs a structured output that can be fed directly into a tool registry, gateway configuration, or agent safety policy.
Prompt
Idempotency Flag Description Prompt
When to Use This Prompt
Define the reliability engineering job, the required inputs, and the operational constraints for generating idempotency annotations.
Do not use this prompt for classifying the idempotency of an entire agent workflow or a multi-step orchestration. It is designed for a single tool definition at a time. It is also not a substitute for actually testing idempotency behavior in a staging environment; the prompt produces documentation and guidance, not a runtime guarantee. If the tool's internal behavior is unknown or the source of truth is unavailable, the prompt should be instructed to flag the tool as 'UNKNOWN' and require human review rather than guessing. This is a high-stakes classification because mislabeling a non-idempotent write operation as safe to retry can cause duplicate charges, double-sent messages, or corrupted state.
Before using this prompt, gather the tool's current description, its parameter schema, and any known side-effect documentation. The prompt works best when [CONTEXT] includes explicit information about the tool's HTTP method, the presence of an idempotency key header or argument, and the system's existing retry policy. After generating the annotation, you should validate it against a set of test cases for duplicate-call safety and integrate the output into your tool registration pipeline. The next step is to run the annotation through a peer review or an automated eval that checks for consistency with other tools in the same catalog.
Use Case Fit
Where the Idempotency Flag Description Prompt works, where it fails, and what you must provide before using it in a production reliability workflow.
Good Fit: Documenting Retry Safety for Write Operations
Use when: you need to annotate tool descriptions so models and retry middleware understand which operations are safe to repeat. Guardrail: require explicit idempotency key documentation and side-effect classification before the prompt runs.
Bad Fit: Runtime Idempotency Enforcement
Avoid when: you need actual idempotency key generation, duplicate detection, or request deduplication at runtime. Guardrail: this prompt produces documentation and annotations, not runtime logic. Pair it with middleware that enforces idempotency keys.
Required Input: Complete Tool Schema with Side Effects
What to watch: the prompt cannot classify retry safety without knowing what each tool does. Guardrail: provide the full tool schema including HTTP methods, endpoint paths, and side-effect descriptions. Missing side-effect context produces unreliable idempotency flags.
Operational Risk: Stale Annotations After Tool Changes
What to watch: idempotency flags become incorrect when tool behavior changes but annotations are not regenerated. Guardrail: version the idempotency annotations alongside the tool schema and re-run this prompt on every schema change. Treat stale flags as a production incident risk.
Operational Risk: Overly Permissive Retry Classification
What to watch: the model may classify a tool as idempotent when it has hidden side effects such as sending notifications or incrementing counters. Guardrail: always require human review of idempotency classifications for write operations. Add a mandatory approval step before publishing annotations.
Good Fit: Pre-Deployment Safety Review
Use when: you are preparing tool schemas for production deployment and need retry safety documented before any traffic hits the system. Guardrail: integrate this prompt into your CI/CD pipeline as a schema review gate. Block deployment if idempotency annotations are missing or unreviewed.
Copy-Ready Prompt Template
A reusable prompt for generating idempotency annotations and retry guidance for tool descriptions.
This prompt template is designed to produce a structured idempotency analysis for a given tool definition. It takes the tool's name, description, parameters, and side effects as input and outputs a clear classification of whether the tool is safe to retry, along with the conditions, required idempotency keys, and recommended retry strategy. The output is intended to be embedded directly into a tool description or stored as a machine-readable annotation for an API gateway.
textYou are a reliability engineer documenting the idempotency characteristics of an API tool for an AI system's tool catalog. Analyze the following tool definition and produce a structured idempotency annotation. ## Tool Definition - Name: [TOOL_NAME] - Description: [TOOL_DESCRIPTION] - Parameters: [TOOL_PARAMETERS_SCHEMA] - Side Effects: [SIDE_EFFECT_DESCRIPTION] ## Output Schema Return a JSON object with the following fields: - `idempotency_classification`: "safe_to_retry" | "unsafe_to_retry" | "conditionally_safe" - `idempotency_key_source`: A description of which parameter(s) or combination of parameters serve as the idempotency key. Use "N/A" if not applicable. - `retry_conditions`: A list of conditions under which a retry is safe. For example, "Only if the previous call returned a network error and no state change occurred." - `max_safe_retries`: An integer representing the recommended maximum number of retries. - `retry_strategy`: "immediate" | "exponential_backoff" | "linear_backoff" - `explanation`: A concise, one-paragraph justification for the classification. ## Constraints - If the tool performs a non-transactional write operation (e.g., sending an email, creating a charge), it must be classified as "unsafe_to_retry" unless an explicit idempotency key is provided in the parameters. - If the tool is a read-only operation, it should be classified as "safe_to_retry". - Do not invent parameters. Only reference parameters present in the provided schema. - If the classification is "conditionally_safe", the `retry_conditions` field must not be empty.
To adapt this template, replace the square-bracket placeholders with the actual details of your tool. The [TOOL_PARAMETERS_SCHEMA] should be a concise JSON Schema representation of the tool's arguments, as this is what the model will use to identify potential idempotency keys. For high-risk financial or healthcare tools, always route the generated annotation for human review before it is committed to the tool catalog. A common failure mode is the model classifying a tool as "safe_to_retry" because it overlooks a nested side effect, such as a write to an audit log. To catch this, pair this prompt with an eval that tests the classification against a known set of dangerous side-effect descriptions.
Prompt Variables
Required inputs for the Idempotency Flag Description Prompt. Provide these variables to generate safe retry annotations for tool schemas.
| Placeholder | Purpose | Example | Validation Notes |
|---|---|---|---|
[TOOL_NAME] | The exact function or tool name as it appears in the schema | create_invoice | Must match the tool catalog exactly; case-sensitive check required |
[TOOL_DESCRIPTION] | Current description of what the tool does and its primary effect | Creates a new invoice in the billing system and returns the invoice ID | Must be the live description from the schema, not a paraphrase; null not allowed |
[TOOL_PARAMETERS] | JSON Schema or list of all parameters the tool accepts | {"amount": {"type": "number"}, "customer_id": {"type": "string"}} | Validate as valid JSON Schema; must include all parameters, not a subset |
[SIDE_EFFECT_CLASSIFICATION] | Classification of the tool's side effects: read_only, idempotent_write, non_idempotent_write, or admin | non_idempotent_write | Must be one of the four allowed enum values; null not allowed |
[IDEMPOTENCY_KEY_PARAMETER] | Name of the parameter that serves as the idempotency key, if one exists | idempotency_key | Must be a valid parameter name from [TOOL_PARAMETERS]; set to null if no key exists |
[RETRY_BEHAVIOR_NOTES] | Current documented retry behavior or known failure modes | Duplicate calls with the same payload will create duplicate invoices | Free text; can be null if undocumented; cite source if from incident postmortem |
[TARGET_MODEL_FORMAT] | The model provider format for the output annotation: openai, anthropic, or generic | openai | Must be one of the three allowed enum values; determines output schema shape |
Implementation Harness Notes
How to wire the idempotency flag description prompt into a CI pipeline, API gateway, or tool registry with validation, retries, and human review gates.
The idempotency flag description prompt is designed to run as a pre-commit or pre-registration step whenever a new tool schema is introduced or an existing tool's side-effect behavior changes. The prompt takes a tool name, its description, its parameter schema, and its intended side-effect profile as input, and it produces a structured idempotency annotation that includes the idempotency key field, retry safety classification, and conditions under which duplicate calls are safe. Wire this prompt into your tool registration pipeline so that every tool in the catalog carries a machine-readable idempotency contract before it becomes callable by a model.
In practice, call this prompt from a CI check that runs on pull requests touching your tool definition files. The application harness should validate the output against a strict JSON Schema that requires idempotency_key_field, retry_classification (one of safe, conditional, or unsafe), duplicate_call_behavior, and retry_guidance. If the output fails schema validation, fail the CI check and block the merge. For high-risk tools where retry_classification is unsafe or conditional, route the annotation to a human reviewer through a lightweight approval queue before the tool is registered. Log every generated annotation with the tool version, prompt version, and model used so that audit trails connect each idempotency decision to its provenance.
When integrating this prompt into a runtime system such as an API gateway or agent execution layer, use the generated annotations to drive retry logic. If retry_classification is safe, the gateway can automatically retry on transient failures without additional checks. If conditional, the retry layer must extract the idempotency_key_field from the original request and include it in the retry, and it should verify that the conditions listed in duplicate_call_behavior are met before reissuing the call. If unsafe, the system must never retry automatically; instead, surface the failure to the calling agent or user with the retry_guidance text. Avoid wiring this prompt directly into hot-path request handling—generate the annotations offline, store them in your tool registry, and have the runtime read the pre-computed contract rather than calling the model on every tool invocation.
Expected Output Contract
Fields the model must return when describing idempotency behavior for a tool. Use this contract to validate the prompt output before publishing the tool schema.
| Field or Element | Type or Format | Required | Validation Rule |
|---|---|---|---|
idempotency_classification | enum: safe, unsafe, conditional | Must be exactly one of the three allowed values. Reject any other string. | |
idempotency_key_source | string or null | If classification is safe or conditional, must describe where the key comes from (e.g., client-generated UUID, hash of payload). If unsafe, must be null. | |
retry_behavior | string | Must describe what happens on duplicate calls: no-op, overwrite, error, or conditional. Must match the classification. | |
precondition_checks | array of strings | If present, each string must describe a check the system performs before deciding idempotency (e.g., 'ETag match', 'idempotency key lookup'). | |
unsafe_retry_consequences | string or null | If classification is unsafe, must describe the side effect of a duplicate call (e.g., 'double charge'). If safe or conditional, must be null. | |
recommended_retry_strategy | string | Must specify one of: retry_with_same_key, retry_with_new_key, do_not_retry, or escalate_to_human. Must align with classification. | |
test_case_duplicate_call | object | Must contain input_payload and expected_outcome fields. expected_outcome must be one of: no_side_effect, overwrite, error, or duplicate_created. |
Common Failure Modes
What breaks first when using an LLM to generate idempotency flags and retry guidance for tool descriptions, and how to guard against it.
Misclassifying Mutating Operations as Idempotent
Risk: The model labels a write operation (e.g., create_user, send_invoice) as idempotent because the description sounds safe or the operation 'usually' produces the same result. This leads to dangerous duplicate executions in production. Guardrail: Provide explicit counterexamples in the prompt showing that only operations with unique client-supplied identifiers or pure read semantics are idempotent. Add a post-generation validation step that flags any POST-like operation without an idempotency key field as non-idempotent.
Ignoring Partial Failure and Side-Effect Windows
Risk: The model declares an operation idempotent based on the final state but ignores transient side effects, such as sending a duplicate welcome email if the database write succeeds but the email queue acknowledgment fails. Guardrail: Require the prompt to distinguish between 'resource-level idempotency' and 'end-to-end idempotency.' Include a specific check in the evaluation rubric that tests whether the model's guidance accounts for side-effect windows and recommends idempotency keys even for operations that appear safe.
Hallucinating Idempotency Key Parameters
Risk: The model invents an idempotency_key parameter for a tool that does not support one, or suggests a non-existent header, leading to integration failures or silently ignored keys. Guardrail: Ground the prompt by requiring the model to cite the specific API documentation field or header that provides idempotency. If no such field exists, the model must default to classifying the operation as non-idempotent and recommending a client-side deduplication strategy instead.
Confusing Retry Safety with Idempotency
Risk: The model conflates 'safe to retry on network error' with 'idempotent.' It might label a read-only operation as idempotent without noting that a write operation could also be safely retried if it uses an idempotency key, missing the critical distinction. Guardrail: Structure the output schema to require separate fields for is_idempotent (boolean), idempotency_method (enum: token, key, none), and retry_strategy (string). Use few-shot examples that show a write operation with a key marked as is_idempotent: true and a read operation marked as is_idempotent: true with idempotency_method: none.
Overlooking Time-Bound Idempotency Guarantees
Risk: The model fails to capture that an API's idempotency guarantee is time-limited (e.g., 24 hours). A retry after the window expires could result in a duplicate, but the generated documentation implies permanent safety. Guardrail: Add a dedicated idempotency_window_seconds field to the output schema. The prompt must instruct the model to extract this value from the source documentation or default to null with a warning that the guarantee duration is unknown.
Generating Generic Retry Guidance Without Backoff Strategy
Risk: The model produces vague advice like 'retry on failure' without specifying an appropriate backoff strategy, leading to thundering herd problems or rate-limit exhaustion in production. Guardrail: The prompt must require a specific retry_strategy field with allowed values like exponential_backoff, immediate, or none. Include a validation step that rejects any output where retry_strategy is exponential_backoff but the max_retries or initial_delay_ms fields are missing.
Evaluation Rubric
Use this rubric to evaluate the quality of idempotency flag descriptions generated by the prompt before integrating them into production tool schemas. Each criterion targets a specific failure mode that causes unsafe retries or broken idempotency key handling.
| Criterion | Pass Standard | Failure Signal | Test Method |
|---|---|---|---|
Idempotency key field identified | Output explicitly names the field to use as the idempotency key (e.g., [IDEMPOTENCY_KEY_FIELD]) | Output omits the key field or describes idempotency without naming a specific parameter | Parse output for a field name matching a tool parameter; assert non-empty string |
Retry safety classification | Output classifies the tool as safe-to-retry, unsafe-to-retry, or conditionally-safe with clear conditions | Output uses vague language like 'usually safe' or fails to state a classification | Check output against enum ['safe', 'unsafe', 'conditional']; reject if missing or ambiguous |
Conditional safety criteria defined | When classification is conditional, output lists specific criteria that must be met for safe retry (e.g., same [RESOURCE_ID], within [TIME_WINDOW]) | Conditional classification present but no criteria listed, or criteria reference undefined variables | For conditional outputs, extract criteria list; assert each criterion references a known tool parameter or system state |
Idempotency window specified | Output states the time window or scope within which duplicate calls are detected (e.g., '24 hours', 'per [ACCOUNT_ID]') | Window is missing, set to 'forever' without justification, or expressed in ambiguous units | Parse window value; assert it includes a numeric value and unit or a scope qualifier |
Retry guidance for callers | Output includes concrete instructions for callers: when to retry, what to change (if anything), and what response to expect on duplicate | Output only says 'retry with same key' without addressing response handling or retry limits | Check for presence of retry instructions block; assert it addresses duplicate response interpretation |
Side-effect documentation | Output lists all side effects the tool produces and notes which are repeat-safe and which are not | Output claims tool is idempotent without enumerating side effects, or omits write operations from the list | Extract side-effect list; cross-reference with tool schema's known write operations; assert no missing side effects |
Error response on duplicate call | Output describes the expected error or success response when a duplicate idempotency key is submitted | Output assumes the API handles duplicates silently without describing the response contract | Check for duplicate-response description; assert it includes HTTP status code or error code and payload shape |
Idempotency key generation guidance | Output advises callers how to generate the idempotency key (e.g., UUID v4, hash of [PAYLOAD_FIELDS]) and where to store it | Output tells callers to use a unique key without specifying generation method or storage expectations | Parse key generation guidance; assert it includes a generation strategy and a storage or scope note |
Enabling Efficiency, Speed & Accuracy
Intelligent Analysis, Decision & Execution
We build AI systems for teams that need search across company data, workflow automation across tools, or AI features inside products and internal software.
Talk to Us
Search across company data
Give teams answers from docs, tickets, runbooks, and product data with sources and permissions.
Useful when people spend too long searching or get different answers from different systems.
Automate internal workflows
Use AI to route work, draft outputs, trigger actions, and keep approvals and logs in place.
Useful when repetitive work moves across multiple tools and teams.
Add AI to products and internal tools
Build assistants, guided actions, or decision support into the software your team or customers already use.
Useful when AI needs to be part of the product, not a separate tool.
Adapt This Prompt
How to adapt
Start with the base prompt and a single tool definition. Use a lightweight JSON output check instead of full schema validation. Focus on getting the idempotency classification (safe/unsafe/conditional) correct before adding retry guidance.
Watch for
- Model classifying write operations as idempotent without checking side effects
- Missing distinction between HTTP-level idempotency (PUT) and business-logic idempotency
- Overly broad "safe to retry" labels on tools with partial state changes
About the author
Prasad Kumkar
CEO & MD, Inference Systems
Prasad Kumkar is the CEO & MD of Inference Systems and writes about AI systems architecture, LLM infrastructure, model serving, evaluation, and production deployment. Over 5+ years, he has worked across computer vision models, L5 autonomous vehicle systems, and LLM research, with a focus on taking complex AI ideas into real-world engineering systems.
His work and writing cover AI systems, large language models, AI agents, multimodal systems, autonomous systems, inference optimization, RAG, evaluation, and production AI engineering.
Partnered with leading AI, data, and software stack.
How We Work
Custom AI workflows for your Business
One-fit-all AI don't work for modern businesses. At Inferensys, we aim to understand your business & custom requirements; which we use to define most efficient agentic workflows, the data, and the tools for your business.
01
Review the use case
We understand the task, the users, and where AI can actually help.
Read more02
Pick the right approach
We define what needs search, automation, or product integration.
Read more03
Build the first useful version
We implement the part that proves the value first.
Read more04
Improve from there
We add the checks and visibility needed to keep it useful.
Read moreThe first call is a practical review of your use case and the right next step.
Talk to Us