Multi-Step Tool Trace Correlation Prompt

This prompt is designed for AI operations engineers and SREs who need to reconstruct a coherent, causally-linked trace map from dozens of raw, potentially out-of-order agent tool call logs. The core job-to-be-done is debugging a multi-step agent failure or proving governance by transforming fragmented log lines into a single correlated trace that links tool invocations by session, task, and parent-child dependency. The ideal user has access to raw tool execution logs but lacks a unified view of the agent's workflow, making it impossible to answer questions like 'Why did the agent call the payment API after the order was cancelled?' or 'Which tool call introduced the stale customer ID?'

Use this prompt when you have a flat list of tool call events and need to produce a structured dependency graph. The required context includes a session identifier, timestamps, tool names, and input/output payloads for each call. The prompt expects these to be provided in the [TOOL_CALL_LOG] placeholder. Do not use this prompt for real-time streaming trace generation, for single-step tool debugging, or when you need OpenTelemetry-compliant span formats—use the 'Agent Tool Execution Trace Span Prompt Template' instead. This prompt is also unsuitable when the raw logs are missing critical fields like parent span IDs or timestamps; in that case, you need log enrichment before correlation.

The prompt's value is in its causal reasoning: it doesn't just sort by time, it infers parent-child relationships by analyzing input/output data flow between calls. However, it is not a replacement for proper distributed tracing instrumentation. Treat the output as a best-effort reconstruction that requires validation. The playbook includes checks for broken dependency chains, orphaned spans, and circular references. For high-risk or compliance-grade reconstructions, always route the output through human review and cross-reference against the original system-of-record logs before using the trace map in an incident postmortem or audit submission.

This prompt template is designed to be dropped into your observability pipeline when you need to reconstruct a coherent trace map from dozens or hundreds of individual tool call log entries. It takes raw, potentially fragmented log records and produces a structured correlation output that links tool invocations by session, task, and causal dependency. Use this template when your agent's native tracing is incomplete, when you're merging logs from multiple systems, or when you need to verify that the agent's actual execution path matches the intended plan.

textCopy
You are a trace correlation engine for an AI agent system. Your task is to reconstruct a correlated trace map from raw tool call log entries.

## INPUT
You will receive a set of tool call log entries. Each entry contains at minimum a timestamp, a tool name, and a session identifier. Some entries may include parent span IDs, task IDs, or input/output references.

[RAW_LOG_ENTRIES]

## OUTPUT_SCHEMA
Produce a JSON object with the following structure:
{
  "trace_map": {
    "sessions": [
      {
        "session_id": "string",
        "start_time": "ISO8601",
        "end_time": "ISO8601",
        "tasks": [
          {
            "task_id": "string",
            "task_description": "inferred or provided description",
            "spans": [
              {
                "span_id": "string",
                "parent_span_id": "string | null",
                "tool_name": "string",
                "start_time": "ISO8601",
                "end_time": "ISO8601",
                "input_summary": "brief summary of arguments",
                "output_summary": "brief summary of result",
                "status": "success | failure | timeout | unknown",
                "dependencies": ["span_id"]
              }
            ]
          }
        ]
      }
    ],
    "orphaned_spans": ["span_id"],
    "broken_dependency_chains": [
      {
        "span_id": "string",
        "missing_parent": "string",
        "reason": "string"
      }
    ],
    "correlation_confidence": 0.0-1.0
  }
}

## CONSTRAINTS
[CONSTRAINTS]

## INSTRUCTIONS
1. Group all log entries by session_id first.
2. Within each session, identify distinct tasks by clustering spans around shared task_ids, temporal proximity, or input/output data flow.
3. For each span, determine its parent span using explicit parent_span_id fields where available. Where missing, infer parent-child relationships from temporal ordering and data dependencies.
4. Flag any span that cannot be linked to a parent as an orphaned_span.
5. Flag any span that references a parent_span_id not present in the log entries as a broken_dependency_chain.
6. Assign a correlation_confidence score based on the proportion of spans with explicit parent links versus inferred links.
7. If a span's status is not explicitly provided, infer it from the presence of error fields, timeout indicators, or incomplete output records.

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

To adapt this template for your environment, replace the square-bracket placeholders with your specific context. [RAW_LOG_ENTRIES] should contain the actual log payload, which may come from your observability platform, a log aggregator, or a direct database query. [CONSTRAINTS] is where you define domain-specific rules, such as maximum trace depth, required fields for compliance, or tool-specific dependency rules. Use [EXAMPLES] to provide one or two few-shot demonstrations of correctly correlated traces from your own system, which dramatically improves accuracy on your specific tool call patterns. Set [RISK_LEVEL] to low, medium, or high to control the verbosity of validation warnings and the strictness of the correlation logic. For high-risk domains like financial transactions or healthcare operations, set this to high and ensure the output is reviewed by a human before being used for audit or incident response.

Before deploying this prompt into an automated pipeline, validate the output against a golden dataset of manually correlated traces. Common failure modes include incorrect parent assignment when timestamps are within milliseconds of each other, misgrouping of spans across session boundaries when session IDs are missing or malformed, and false orphan detection when a parent span exists but uses a different ID format. Implement a post-processing validator that checks for these specific failure modes and triggers a retry or human review when the correlation_confidence score falls below your threshold. For production use, log the prompt version, input hash, and output hash alongside the trace map to maintain an audit trail of how each correlation was produced.

This prompt is designed to be called as a post-processing step after agent execution completes or when an SRE triggers a trace reconstruction. It expects a batch of raw tool call logs, typically sourced from an OpenTelemetry collector, a centralized logging system, or an agent framework's trace export. The prompt is not a streaming, real-time component; it operates over a closed window of completed tool interactions. The primary integration point is a reconciliation service that queries the log store for all spans within a given [SESSION_ID] or [TRACE_WINDOW_START] and [TRACE_WINDOW_END], assembles them into the [RAW_TOOL_CALLS] input array, and invokes the model. The output is a structured JSON trace map that must be validated before it is written to the observability backend or used for incident response.

The implementation harness requires three validation layers. First, a schema validator must confirm the output matches the expected [OUTPUT_SCHEMA], checking that every span has a span_id, parent_span_id, tool_name, and timestamp. Second, a graph integrity checker must traverse the reconstructed trace map to detect orphaned spans (spans with a parent_span_id that does not match any known span_id in the output) and broken causal chains (a tool call that depends on the output of a prior call that is missing or failed). If the integrity check fails, the harness should retry the prompt once with the validation errors appended to the [CONSTRAINTS] field, explicitly instructing the model to resolve the specific broken links. If the retry also fails, the partial trace map should be written to a dead-letter queue with a correlation_failure flag for manual review. Third, a timestamp sanity check must verify that child spans do not start before their parent spans, accounting for clock skew by flagging, not rejecting, minor overlaps under a configurable threshold.

For production deployment, run this prompt on a model with strong structured output and long-context capabilities, such as gpt-4o or claude-3.5-sonnet, because the input array of raw tool calls can exceed 10k tokens for complex agent sessions. Set response_format to json_object and provide the [OUTPUT_SCHEMA] as a strict JSON Schema definition. Log every invocation with the session ID, input span count, output span count, validation pass/fail status, and model latency. For high-compliance environments, store the raw input logs, the prompt template version, the model response, and the validation results as an immutable audit record before the correlated trace map is used for any incident postmortem or compliance report. Do not use this prompt for real-time agent decision-making; it is a diagnostic and audit tool, not an in-the-loop controller.