# Which invariants prevent tool-call span corruption under OpenTelemetry GenAI semantic conventions **Date of Record:** 2026 November 17 **Scope:** Applies to instrumentation that emits `gen_ai.*` attributes on spans modeling LLM turns, tool calls, and agent steps per the OpenTelemetry GenAI semantic conventions (as of the 1.x experimental drafts). Does not cover pure request/response HTTP spans, nor spans emitted by vendor SDKs that have not adopted the convention. ## Core Distinction The GenAI conventions distinguish a **turn span** (one model invocation, carrying `gen_ai.operation.name`, `gen_ai.request.model`, token usage, and `gen_ai.response.finish_reasons`) from a **tool-call span** (one execution of a tool the model requested, carrying `gen_ai.tool.name`, `gen_ai.tool.call.id`, and `gen_ai.tool.type`). The non-obvious failure is not "missing attributes." It is **cardinality and parentage drift**: a tool-call span that is attributed to the wrong turn, or a turn span that absorbs N tool executions into one attribute set. The invariant that matters is *one tool-call span per `gen_ai.tool.call.id`, parented to the turn span that emitted the request for that call id* — not to the agent step, not to the trace root, and not to a sibling turn. ## What Was Observed In a multi-step agent loop (plan → tool → observe → plan), instrumentation emitted tool spans as children of the *current* active span at execution time. Under concurrent tool execution (parallel function calling), three tool spans for call ids `A`, `B`, `C` were all parented to the second turn span because the executor reused the context of the most recently completed model call. Result: the first turn's tool calls had no children, and the second turn had three. Backends reconstructing the agent trajectory from span parentage reordered the tool results ahead of the plan that produced them, producing a coherent-but-wrong causal chain. A second observation: when a model returned `finish_reason = "tool_calls"` but the tool executor failed to start (queue saturation), the turn span was closed with `gen_ai.response.finish_reasons = ["tool_calls"]` and zero child tool spans. Downstream consumers treated this as "model requested tools that were never run" — which was *true* — but the absence of a tool span was indistinguishable from "tool span was dropped by the exporter." The two states are operationally different and must not share a representation. ## Condition of Validity The "one span per call id, parented to the requesting turn" invariant holds only when: - The `gen_ai.tool.call.id` is propagated from the model response into the executor's span context *before* the span starts, not read from the executor's local state after. - Parallel tool execution uses `contextvars`/explicit context passing per task, not the ambient span context. - A turn span with `finish_reasons` containing `tool_calls` is not closed until every requested call id has either a child tool span or an explicit `gen_ai.tool.call.id`-keyed error event. It does not hold for streaming responses where call ids are emitted incrementally; there, the turn span must not close until the stream terminates, or call ids must be reconciled via events. ## Decision Boundary Choose between **eager span creation** (open the tool span at request-parse time, before the executor is scheduled) and **deferred span creation** (open at execution start). Eager creation preserves parentage and makes dropped executions visible as long-lived or errored spans; deferred creation risks the parentage drift above and hides queue-saturation drops. Use eager creation whenever tool calls can be requested in parallel or the executor is asynchronous. Use deferred creation only in single-threaded, synchronous executors where the active span is provably the requesting turn. ## Operational Effect With the invariant enforced, agent-trajectory reconstruction from spans is exact: every `gen_ai.tool.call.id` appears once as a child of the turn that requested it, and a requested-but-unexecuted tool is a visible errored child span rather than a silent gap. Without it, trace-based evaluation of agent correctness silently attributes tool outputs to the wrong reasoning step, and token/cost attribution per turn is skewed by tool spans landing under the wrong model invocation. ```python from __future__ import annotations from dataclasses import dataclass, field class ToolCallParentageError(RuntimeError): """Raised when a tool-call span violates the one-span-per-call-id, parented-to-requesting-turn invariant of the GenAI conventions.""" @dataclass class TurnSpan: span_id: str finish_reasons: list[str] = field(default_factory=list) requested_call_ids: set[str] = field(default_factory=set) child_call_ids: set[str] = field(default_factory=set) def register_tool_span( turn: TurnSpan, *, call_id: str, parent_span_id: str, tool_name: str, ) -> None: if not call_id: raise ToolCallParentageError( "tool-call span emitted without gen_ai.tool.call.id; " "parentage cannot be verified" ) if parent_span_id != turn.span_id: raise ToolCallParentageError( f"tool call {call_id!r} parented to {parent_span_id!r}, " f"but requesting turn is {turn.span_id!r}" ) if call_id in turn.child_call_ids: raise ToolCallParentageError( f"duplicate tool-call span for call id {call_id!r} under turn " f"{turn.span_id!r}; exactly one span per call id is required" ) if call_id not in turn.requested_call_ids: raise ToolCallParentageError( f"tool call {call_id!r} has no matching request on turn " f"{turn.span_id!r}; finish_reasons={turn.finish_reasons!r}" ) turn.child_call_ids.add(call_id) def close_turn(turn: TurnSpan) -> None: if "tool_calls" in turn.finish_reasons: missing = turn.requested_call_ids - turn.child_call_ids if missing: raise ToolCallParentageError( f"turn {turn.span_id!r} closed with finish_reason 'tool_calls' " f"but call ids {sorted(missing)!r} have no child span; " "emit an errored tool span or an explicit drop event" ) ```