Cross-System Correlation ID Annotation Prompt

Use this prompt when your AI system calls external tools—APIs, databases, internal services—and you need to debug latency, attribute errors, or prove data lineage across service boundaries. The core job is to generate or propagate a unique, consistent correlation ID for every tool call the model makes, linking the model's decision to downstream logs. This is essential for observability engineers and platform teams who are stitching together distributed traces that span an LLM call and its subsequent side effects. The ideal user is someone who already has a tracing backend (like Jaeger, Datadog, or Grafana Tempo) and needs the AI layer to participate in that trace context, not someone building a tracing system from scratch.

This prompt is not a replacement for a tracing library or an OpenTelemetry SDK. It does not generate traces; it annotates the model's tool call with the identifier that makes tracing possible. You should not use this prompt when your application can deterministically set the correlation ID in the tool-calling layer before the model's request is even constructed. If your orchestrator already has a trace ID from an incoming user request, inject it directly into the tool call metadata without asking the model to generate one. Reserve this prompt for scenarios where the model must decide to initiate a new trace segment, propagate an ID from a prior tool call's result, or handle a mid-session context where the trace context is ambiguous and requires semantic reasoning.

Before implementing, confirm that your tool execution harness can read the model's output and inject the correlation ID into the actual API call headers or metadata. The prompt's value is zero if the ID stays in the model's text response and never reaches your backend systems. Pair this prompt with a post-processing step that extracts the ID and sets it as the X-Correlation-ID header or equivalent in your outbound requests. If your system already has a mandatory correlation ID injected at the API gateway, you likely do not need this prompt—instead, focus on ensuring that ID is passed through to the model's context for logging purposes only.

This prompt template instructs the model to annotate each tool call with a stable, traceable correlation ID before execution. It is designed to be placed in the system prompt or as a pre-processing step in your tool-call pipeline. The model will either reuse an existing ID from the conversation context or generate a new one, ensuring every downstream API log, database query, and error tracker entry can be linked back to a single user interaction or workflow instance.

textCopy
You are a correlation ID annotation layer operating before any tool call is executed.

Your only job is to ensure every tool call carries a `correlation_id` that links it to the originating user request or workflow instance.

## Rules
1. If the current conversation context already contains a `correlation_id`, reuse that exact value for every subsequent tool call in this session.
2. If no `correlation_id` exists, generate a new one using the format: [ID_FORMAT] (e.g., `req_` + UUIDv4, or `trace_` + ksuid).
3. Attach the `correlation_id` to the tool call metadata or as a top-level argument if the tool schema supports it.
4. Never modify a `correlation_id` once it has been set for a session.
5. If the tool call is part of a retry or recovery flow, keep the same `correlation_id` and add a `retry_count` field starting at 1.

## Input Context
- User Request: [USER_INPUT]
- Conversation History (last 5 turns): [CONVERSATION_HISTORY]
- Existing Correlation ID (if any): [EXISTING_CORRELATION_ID]
- Tool to be Called: [TOOL_NAME]
- Tool Arguments: [TOOL_ARGUMENTS]

## Output Schema
Return a JSON object with the following structure:
{
  "tool_name": "string",
  "correlation_id": "string",
  "retry_count": 0,
  "propagation_instruction": "Attach this correlation_id to all downstream logs, API calls, and error records for this operation."
}

## Constraints
- Do not execute the tool. Only annotate it.
- If [EXISTING_CORRELATION_ID] is not null or empty, you must reuse it.
- The `correlation_id` must be unique per user session, not per tool call.

To adapt this template, replace the square-bracket placeholders with your runtime values. [ID_FORMAT] should match your organization's tracing standard (e.g., W3C Trace Context, OpenTelemetry span IDs, or an internal format). [USER_INPUT] and [CONVERSATION_HISTORY] provide the model with enough context to determine if a session is ongoing. [EXISTING_CORRELATION_ID] should be extracted from your application state or previous tool call metadata. Wire this prompt into your pre-tool-call hook so it runs before every tool execution. Validate the output JSON to ensure the correlation_id field is present and non-empty before allowing the tool call to proceed. For high-risk or regulated environments, log the annotation output as part of your audit trail and consider adding a human review step if the model attempts to generate a new ID when one already exists.

This prompt is designed to sit inside a pre-execution interceptor in your AI gateway or agent framework. Before any tool call is dispatched, the harness injects the prompt with the tool name, arguments, and the current trace context. The model returns a structured annotation that includes a deterministic or propagated correlation ID. The harness then attaches this ID to the outbound tool call headers and logs it alongside the model's decision context. Do not rely on the model to generate a random UUID—instead, provide a [TRACE_ID] from your existing distributed tracing system (e.g., W3C Trace Context, OpenTelemetry traceparent) and instruct the model to use it directly or derive a deterministic sub-span ID.

Wiring steps: (1) Extract the incoming trace context from the request headers or generate a new trace ID if one is absent. (2) Assemble the prompt with [TOOL_NAME], [TOOL_ARGUMENTS], [TRACE_ID], [SESSION_ID], and [TIMESTAMP]. (3) Call a fast, low-cost model (e.g., GPT-4o-mini, Claude Haiku) with temperature=0 and strict JSON mode enabled. (4) Parse the response and validate that correlation_id is non-empty and matches the expected format. If validation fails, fall back to using the provided [TRACE_ID] directly as the correlation ID and log a warning. (5) Inject the correlation_id into the tool call's metadata (e.g., as an HTTP header X-Correlation-ID or a field in the tool call envelope). (6) Log the full annotation payload to your observability backend (e.g., Datadog, Honeycomb, OpenTelemetry collector) as a span event on the parent trace.

Retry and failure handling: If the model call fails or times out, do not block the tool execution. Use the provided [TRACE_ID] as the correlation ID and emit a degraded-mode annotation record with "source": "fallback" and the error reason. This ensures observability continuity even when the annotation model is unavailable. For high-throughput systems, consider caching the prompt prefix (system message and static instructions) to reduce latency and cost. Validation checks should include: correlation ID format (non-empty string, no whitespace, matches your organization's ID convention), source field is one of the expected enum values ("propagated", "derived", "fallback"), and trace_parent is present when source is "propagated". Reject annotations that hallucinate tool names not present in the input.

When to avoid this prompt: If your tool execution framework already enforces mandatory correlation ID propagation at the infrastructure level (e.g., a service mesh that injects headers automatically), this prompt adds latency without benefit. Similarly, if you are not logging model decisions alongside tool calls, the annotation has no consumer. Start by instrumenting your tool dispatch layer with basic trace propagation, then add this prompt when you need to link the model's decision context to the downstream trace—this is the gap that standard distributed tracing does not cover.