# What structural signals indicate tool-call attribute loss in OpenTelemetry GenAI agent spans **Date of Record:** 2026 November 15 **Scope:** Applies to OpenTelemetry GenAI semantic conventions (`gen_ai.*`) as emitted by agent frameworks producing `execute_tool` and `chat`/`invoke_agent` spans, specifically when tool-call attributes, token usage, and model invocation events are correlated across a span tree. Does not apply to raw OTLP transport failures or to non-GenAI spans. ## Core Distinction A GenAI agent span can be *structurally valid* (well-formed `gen_ai.operation.name`, non-null span IDs, correct parent linkage) while being *semantically hollow*: the `gen_ai.tool.name`, `gen_ai.tool.call.id`, and `gen_ai.usage.input_tokens`/`output_tokens` attributes are absent, zero, or misattributed. The non-obvious boundary is this: **the absence of `gen_ai.tool.call.id` on an `execute_tool` span is not a sampling artifact — it is a signal that the framework stripped the attribute during a retry or a parallel fan-out, and the corresponding model invocation event will double-count tokens.** The distinction that matters operationally is between *missing* attributes (never set) and *dropped* attributes (set then lost in a re-export or a context-propagation break). Only the latter produces token-accounting drift, because the model invocation event still fires. ## What Was Observed In a multi-tool agent loop (three parallel `execute_tool` spans under one `invoke_agent` span), the following pattern recurred under load: - Each `execute_tool` span carried `gen_ai.tool.name` but only two of three carried `gen_ai.tool.call.id`. - The `invoke_agent` parent reported `gen_ai.usage.input_tokens` equal to the sum of *all* model invocation events, including a retried invocation whose `execute_tool` child had lost its `call.id`. - The retried invocation emitted a second `gen_ai.client.inference.operation.details` event with the *same* `gen_ai.response.id` but a fresh `gen_ai.usage.output_tokens` value. The structural tell was not the missing ID in isolation. It was the **cardinality mismatch**: `count(execute_tool spans) != count(distinct gen_ai.tool.call.id)`, combined with `count(model invocation events) > count(distinct gen_ai.response.id)`. Either condition alone is benign; together they indicate a retry that re-emitted a model invocation event without re-emitting the tool-call correlation attribute. ## Condition of Validity This diagnostic is valid only when: 1. The agent framework emits `gen_ai.operation.name = "execute_tool"` (per the current GenAI conventions) rather than a custom operation name. 2. The exporter is configured with `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`; under the older `gen_ai.system`-only regime, `tool.call.id` was not standardized and its absence carries no signal. 3. The span tree is complete — i.e., the collector did not tail-sample the `invoke_agent` parent while retaining children. Incomplete trees produce the same cardinality mismatch for benign reasons. When any of these fail, treat the mismatch as noise, not as a retry signal. ## Decision Boundary Do **not** alert on a single missing `gen_ai.tool.call.id`. Do alert when, over a rolling window, the ratio `distinct(gen_ai.tool.call.id) / count(execute_tool)` falls below 0.99 **and** `count(inference events) / distinct(gen_ai.response.id) > 1.0`. The conjunction is the boundary: attribute loss alone is a telemetry-quality issue; attribute loss *co-occurring with* event duplication is a token-accounting correctness issue that will inflate billing and corrupt per-tool cost attribution. The correct remediation is at the framework's retry wrapper, not the collector: the retry must preserve `gen_ai.tool.call.id` across attempts and must not emit a second inference event for a response it already recorded. ## Operational Effect Left undetected, this boundary silently doubles the input-token cost attributed to retried tool calls and breaks the invariant that `sum(child tool tokens) <= parent input_tokens`. Downstream cost dashboards that join on `gen_ai.tool.name` will show a tool as "expensive" when it is merely "retried." The signal to watch is structural, not numeric: cardinality of correlation IDs against cardinality of events. ```python from dataclasses import dataclass, field class ToolCallCorrelationError(RuntimeError): """Raised when GenAI span cardinality indicates attribute loss with event duplication.""" @dataclass class GenAISpanBatch: execute_tool_spans: int = 0 distinct_tool_call_ids: int = 0 inference_events: int = 0 distinct_response_ids: int = 0 stability_opt_in: bool = True tree_complete: bool = True def check_tool_call_invariant(batch: GenAISpanBatch) -> None: if not batch.stability_opt_in: return # older semconv regime: absence of tool.call.id is not a signal if not batch.tree_complete: return # incomplete trees produce benign cardinality mismatch if batch.execute_tool_spans == 0: return id_coverage = batch.distinct_tool_call_ids / batch.execute_tool_spans event_duplication = ( batch.inference_events / batch.distinct_response_ids if batch.distinct_response_ids else float("inf") ) if id_coverage < 0.99 and event_duplication > 1.0: raise ToolCallCorrelationError( f"tool-call attribute loss co-occurring with event duplication: " f"id_coverage={id_coverage:.3f} (<0.99), " f"event_duplication={event_duplication:.3f} (>1.0); " f"token accounting will double-count retried invocations" ) ```