Tool-Call Race Condition Detection Prompt

This prompt is designed for reliability engineers and SREs who need to audit production trace data for race conditions in agent executions. You should use it when you have structured traces from an agent that executes multiple tool calls in parallel and you suspect non-deterministic outcomes caused by two or more tool calls operating on the same resource without proper synchronization. The ideal input is a trace containing timestamps, tool names, arguments, target resource identifiers, and return values. The prompt performs a post-execution forensic analysis, correlating overlapping time windows with shared resource access to surface likely race condition candidates. It does not replace real-time concurrency controls, locking mechanisms, or transactional boundaries in your tool implementations.

To use this effectively, you must provide traces with sufficient granularity. Each tool-call record should include a precise start and end timestamp, the resource or entity ID being mutated, the operation type (create, update, delete), and the final state or return value. The prompt works by grouping calls by target resource, then identifying pairs or groups with overlapping execution windows where at least one call is a write operation. It flags cases where the final state is inconsistent with any valid serial ordering of the calls. For example, if Tool A updates a record at T1 and Tool B reads the same record at T2 where T1 and T2 overlap, the prompt will flag this as a read-write race. If both calls are writes with overlapping windows and the final state reflects only one, it flags a write-write conflict. The output is a structured race condition report keyed by resource, with an affected timeline and a severity classification.

Do not use this prompt for single-threaded sequential traces where ordering is guaranteed by design. Do not use it as a substitute for idempotency keys, optimistic locking, or transactional boundaries in your tool implementations. The prompt is a diagnostic tool, not a prevention mechanism. After receiving the race condition report, your next step should be to correlate the flagged resources with user-reported incidents or data integrity alerts. For high-severity findings affecting critical data, always require human review of the trace evidence before taking remediation actions such as state repair or tool-level synchronization fixes.

The prompt below is designed to analyze a production agent trace where multiple tool calls were executed in parallel or rapid succession. It identifies overlapping side effects, missing synchronization, and non-deterministic ordering that could have caused state corruption. Use this template as the core of a trace review harness—feed it structured trace data, tool manifests, and resource identifiers, and it will produce a structured race condition report.

textCopy
You are a reliability engineer reviewing an agent execution trace for race conditions. Your task is to identify tool calls that accessed or mutated shared resources without proper synchronization, leading to potential state corruption.

## INPUT

**Trace Data:** [TRACE_DATA]
**Tool Manifest:** [TOOL_MANIFEST]
**Shared Resource Definitions:** [SHARED_RESOURCES]
**Expected Execution Model:** [EXECUTION_MODEL]

## OUTPUT_SCHEMA

Return a JSON object with the following structure:
{
  "trace_id": "string",
  "analysis_timestamp": "string (ISO 8601)",
  "findings": [
    {
      "finding_id": "string",
      "severity": "HIGH | MEDIUM | LOW",
      "race_type": "WRITE_AFTER_READ | WRITE_AFTER_WRITE | READ_AFTER_WRITE | MISSING_SYNCHRONIZATION | NON_DETERMINISTIC_ORDERING",
      "affected_resource": "string",
      "tool_calls_involved": [
        {
          "tool_call_id": "string",
          "tool_name": "string",
          "timestamp": "string (ISO 8601)",
          "operation": "READ | WRITE | DELETE | UPDATE",
          "arguments_summary": "string"
        }
      ],
      "timeline_description": "string describing the overlapping execution",
      "expected_behavior": "string describing correct synchronized behavior",
      "observed_behavior": "string describing what actually occurred",
      "impact_assessment": "string describing potential state corruption",
      "recommendation": "string describing fix (e.g., idempotency key, lock, sequential execution)"
    }
  ],
  "summary": {
    "total_tool_calls_reviewed": "integer",
    "parallel_execution_groups_identified": "integer",
    "race_conditions_found": "integer",
    "high_severity_count": "integer",
    "resources_affected": ["string"]
  },
  "no_findings": "boolean (set to true only if zero race conditions found)"
}

## CONSTRAINTS

1. Only flag tool calls that actually overlap in execution time or lack ordering guarantees.
2. Do not flag sequential tool calls that have explicit dependency ordering.
3. For each finding, cite specific timestamps and tool call IDs from the trace.
4. If the trace contains idempotency keys or version vectors, note whether they were used correctly.
5. Distinguish between true race conditions and acceptable concurrent reads.
6. If no race conditions are found, return an empty findings array with no_findings set to true and a brief explanation.

## EXAMPLES

**Example Race Condition:**
- Tool A reads resource X at T1
- Tool B writes resource X at T2 (T2 overlaps with T1's execution window)
- Tool A's read may have captured stale or partially-written state
- Severity: HIGH if the read result was used for a subsequent write

**Example Non-Issue:**
- Tool A reads resource X at T1
- Tool B reads resource X at T2 (concurrent reads, no mutation)
- No race condition; do not flag

## RISK_LEVEL: [RISK_LEVEL]

If RISK_LEVEL is HIGH, require explicit evidence of state corruption before flagging. If RISK_LEVEL is MEDIUM, flag potential races with clear impact descriptions. If RISK_LEVEL is LOW, flag all concurrent access to mutable resources.

To adapt this template, replace [TRACE_DATA] with a structured representation of your agent's tool-call log—ideally JSON with timestamps, tool names, arguments, and return values. Replace [TOOL_MANIFEST] with the list of available tools and their side-effect profiles (read-only vs. mutating). Replace [SHARED_RESOURCES] with the identifiers of resources that multiple tools can access, such as database rows, file paths, or API endpoints. Replace [EXECUTION_MODEL] with a description of how your agent schedules parallel calls—whether it uses a task graph, promises, or fire-and-forget. Set [RISK_LEVEL] to HIGH for financial or healthcare workflows where false positives waste review time, or LOW for debugging sessions where you want maximum coverage.

After running this prompt, validate the output against your trace data: every tool_call_id in the findings must exist in the original trace, timestamps must be consistent, and severity classifications should match your incident response thresholds. For production use, wire this prompt into a scheduled trace-sampling job that pulls recent parallel-execution traces, runs detection, and routes HIGH-severity findings to an on-call channel. Always log the raw model output and the validated finding count for observability. If the model returns findings for resources you know are immutable, adjust your [SHARED_RESOURCES] input to exclude them in the next run.

The Tool-Call Race Condition Detection Prompt is designed to be integrated into an automated trace analysis pipeline, not run as a one-off chat interaction. The primary integration point is your existing observability platform (e.g., Datadog, Grafana, Arize, LangSmith) where agent traces are stored. When an incident is declared or an anomaly detector flags a state corruption event, a webhook should trigger a job that fetches the relevant trace spans, formats them into the [TRACE_DATA] placeholder, and sends the assembled prompt to a capable reasoning model. The model's structured output is then parsed and written back as an annotation on the incident timeline or as a structured finding in your security information and event management (SIEM) system.

The implementation must enforce a strict contract around the prompt's output. Because the prompt produces a JSON report with a race_conditions array, your harness should validate this schema immediately upon receiving the model's response. Use a JSON Schema validator to confirm the presence of required fields (affected_resources, timeline, root_cause_classification) and reject malformed responses. If validation fails, implement a single retry with a more forceful instruction appended to the prompt: 'You MUST respond with valid JSON matching the provided schema. Do not include any text outside the JSON object.' If the retry also fails, log the raw response and escalate to a human reviewer via your incident management tool (e.g., PagerDuty, Opsgenie). For high-severity production environments, consider routing the prompt to a model with strong JSON mode support, such as GPT-4o or Claude 3.5 Sonnet, and enabling structured output features to guarantee schema compliance on the first attempt.

To avoid false positives, the harness should pre-filter traces before invoking the LLM. Only send traces that contain parallel or concurrent tool calls—sequential traces with no overlapping execution windows cannot contain race conditions by definition. Your trace query should filter for spans where concurrency > 1 or where multiple tool calls share the same start_time and resource_id. This pre-filtering reduces token costs and prevents the model from hallucinating race conditions in purely sequential workflows. Additionally, maintain an audit log of every detection run: store the trace IDs, the prompt version, the model used, the raw LLM output, and the final validated finding. This log is essential for tuning the prompt over time and for defending false-positive detections during post-incident review. Never allow the model's output to automatically remediate or roll back state—always require a human operator to approve corrective actions based on the race condition report.