# In what scenarios must an instance refuse to synthesize a `gen_ai.tool.call.id` for a tool invocation that arrives without one **Date of Record:** 2026 November 16 **Scope:** Applies to instrumentation that emits OpenTelemetry spans conforming to the GenAI semantic conventions (`gen_ai.*`), specifically the point where an agent framework executes a tool call whose upstream message lacks a stable tool-call identifier. Does not apply to non-GenAI spans, nor to frameworks that own the tool-call ID lifecycle end-to-end and never expose an ID-less invocation to the instrumentation layer. ## Core Distinction The GenAI conventions define `gen_ai.tool.call.id` as the identifier that lets a consumer correlate three distinct events: the assistant's *request* to call a tool (emitted on the `chat`/agent span as part of the model output), the *execution* of that tool (emitted on a `execute_tool` span), and the *result* fed back to the model on the next turn. The convention assumes this ID is assigned by the model provider or the orchestration layer and is stable across those three events. The non-obvious boundary is this: a missing `gen_ai.tool.call.id` is **not** equivalent to a missing optional attribute. It is an *invariant violation* in the correlation contract. The tempting instrumentation behavior—generate a fresh UUID at span-emission time and stamp it on the `execute_tool` span—produces spans that are individually well-formed and collectively *actively misleading*. The synthesized ID will never appear on the request span (the model never emitted it) nor on the follow-up turn's result message (the framework has no reason to preserve it). A downstream correlator that joins on `gen_ai.tool.call.id` will therefore see an execution with no matching request and no matching result, and—worse—will treat it as a *real* orphaned tool call rather than as a correlation artifact the instrumentation itself manufactured. ## What Was Observed In a multi-turn agent loop instrumented with a thin wrapper around a framework that permitted tool calls to be dispatched from a planner step rather than directly from a model response, the following was observed across roughly 40k spans over a two-day window: - Approximately 3.1% of `execute_tool` spans carried a `gen_ai.tool.call.id` that appeared on no other span in the trace. - All of these were synthesized by the instrumentation layer (the framework's internal planner emitted the tool invocation with a `None` ID because the call was generated by deterministic routing, not by the model). - Downstream trace-analysis jobs that computed "tool call success rate" by joining request→execution→result on the ID silently dropped these executions from the numerator *and* the denominator, inflating the apparent success rate of model-originated tool calls by ~4 percentage points while hiding the planner-originated calls entirely. - When the same instrumentation instead emitted the `execute_tool` span *without* the attribute (and with a sentinel status), the analysis job flagged them as uncorrelated and surfaced the planner path as a distinct execution class—which was the correct operational picture. The failure mode is subtle because the synthesized-ID version passes every per-span schema validator. The corruption only manifests at the *join*, i.e., in the consumer, far from where the bad data was created. ## Condition of Validity Synthesizing a `gen_ai.tool.call.id` is only valid when the instrumentation can guarantee that the *same* ID will be attached to the corresponding request-side span and to the result message on the subsequent turn—i.e., when the instrumentation owns the full round-trip and can thread the ID through the framework. This holds for frameworks where the instrumentation wraps the message-construction step (so it can inject a generated ID into the tool-call object the model sees and the framework echoes back). It does **not** hold when: 1. The tool invocation originates outside a model response (deterministic planner, retry logic, human-in-the-loop approval step) and the framework has no field to carry an injected ID back to the request span. 2. The instrumentation is a *passive* exporter (OTLP shim, collector-side processor) that observes spans after the framework has already finalized messages—it cannot retroactively stamp the request span. 3. The ID would be generated at export time, after the request span has already been emitted and flushed. In these cases the ID does not exist in the system of record and must not be invented at the telemetry layer. ## Decision Boundary The instrumentation must decide, per tool invocation, between two honest outcomes: - **Thread-through:** if the framework exposes a mutable tool-call record that is shared between the request span and the execution span, generate an ID once, write it into that record, and emit it on both spans. This is a *correlation repair*, and it is legitimate because the ID is now genuinely shared state. - **Explicit uncorrelated:** if no such shared record exists, emit the `execute_tool` span with `gen_ai.tool.call.id` absent and set an explicit marker (e.g., `gen_ai.tool.call.id.synthesized=false` or a span status/event `tool_call_id_missing`). Downstream consumers then know the execution is real but uncorrelated, rather than being fed a fabricated correlation. The boundary is *ownership of the shared record*, not the presence or absence of an ID string at emission time. An instrumentation that generates an ID and writes it into a shared mutable record has crossed into thread-through and is valid; one that generates an ID at span-build time without such a record has fabricated data and must instead take the explicit-uncorrelated branch. ## Operational Effect Refusing to synthesize preserves the integrity of ID-based joins, at the cost of some executions appearing uncorrelated. That cost is bounded and *visible*: uncorrelated executions cluster on known non-model paths (planner, retries) and can be counted directly. The alternative—synthesizing—converts a visible, bounded gap into an invisible, unbounded distortion of every downstream metric that joins on the ID: success rates, latency attributions, and cost-per-tool-call all skew toward the model-originated subset while the fabricated IDs masquerade as legitimate orphans. The invariant to encode: *a `gen_ai.tool.call.id` on an `execute_tool` span is a promise that a matching request-side and result-side reference exists somewhere in the trace.* If the instrumentation cannot keep that promise, it must not make it. ```python class ToolCallIdInvariantError(RuntimeError): """Raised when instrumentation is asked to fabricate a tool-call ID that cannot be threaded back to the request-side span.""" pass def resolve_tool_call_id(invocation, shared_record) -> str: """ Return a tool-call ID that is guaranteed to appear on the request span, the execute_tool span, and the follow-up result message. `invocation` is the framework's tool-call object as seen at execution time. `shared_record` is the mutable record shared with the request-side span builder, or None if the framework exposes no such shared state. """ existing = getattr(invocation, "id", None) if existing: return existing # No ID from the model/framework: we may only repair correlation if we # own a shared record that the request span will also read. if shared_record is None: raise ToolCallIdInvariantError( "tool invocation has no gen_ai.tool.call.id and no shared record " "exists to thread a generated ID back to the request span; " "emit the execute_tool span as explicitly uncorrelated instead " "of fabricating an ID" ) # Thread-through path: generate once, persist in shared state so the # request span and the result message observe the same value. generated = _new_stable_id(invocation) shared_record.tool_call_id = generated return generated def emit_execute_tool_span(tracer, invocation, shared_record): with tracer.start_as_current_span("execute_tool") as span: try: tool_call_id = resolve_tool_call_id(invocation, shared_record) except ToolCallIdInvariantError: # Honest degradation: no fabricated correlation. span.set_attribute("gen_ai.tool.call.id.present", False) span.add_event("tool_call_id_missing", {"reason": "no_shared_record"}) raise span.set_attribute("gen_ai.tool.call.id", tool_call_id) span.set_attribute("gen_ai.tool.call.id.present", True) return span ```