# What structural signals indicate: OpenTelemetry GenAI span attribute invariants break at the tool-call boundary when token accounting and agent-invocation nesting are conflated **Date of Record:** 2026 November 17 **Scope:** Applies to OpenTelemetry GenAI semantic conventions (gen_ai.*) as emitted by LLM SDK instrumentation for chat completions, tool/function calls, and agent invocations. Does not apply to non-GenAI spans, nor to custom attributes outside the gen_ai namespace; nor does it prescribe behavior for streaming responses where intermediate chunks are not promoted to span events. ## Core Distinction The GenAI semantic conventions define three attribute families that are structurally independent but frequently emitted by a single instrumentation layer as if they shared a lifecycle: **token usage** (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`), **tool-call identity** (`gen_ai.tool.name`, `gen_ai.tool.call.id`), and **agent invocation** (`gen_ai.agent.name`, `gen_ai.operation.name`). The non-obvious invariant is: *a span may legitimately carry tool-call attributes without carrying token attributes, and an agent-invocation span may legitimately carry neither.* The failure mode is treating "GenAI span" as a single schema where every attribute is required, which causes downstream consumers to drop or mislabel spans at the tool-call boundary. The distinction that matters operationally: **token accounting is a property of the model call (the `chat` operation), not of the tool execution or the agent orchestration.** A `gen_ai.tool.call.id` present on a span whose `gen_ai.operation.name` is `execute_tool` carries no token usage by convention — the tokens were spent on the preceding `chat` span. Instrumentation that back-fills token attributes onto tool spans to satisfy a "complete" schema corrupts cost attribution and double-counts tokens when the collector aggregates by `gen_ai.operation.name`. ## What Was Observed In a multi-agent deployment (planner → tool executor → synthesizer) instrumented with the standard GenAI semconv, we observed the following structural signals: 1. **Orphaned tool spans.** Spans with `gen_ai.operation.name=execute_tool` and a valid `gen_ai.tool.call.id` were emitted as children of the *agent* span rather than the *chat* span that produced the tool call. The `gen_ai.tool.call.id` on the tool span did not match any `gen_ai.tool.call.id` recorded as a span event on the parent chat span, because the chat instrumentation recorded the call id only in the assistant message content, not as a span attribute. Result: the tool span was structurally unattachable to the model call that requested it. 2. **Token attributes on non-chat spans.** The synthesizer emitted `gen_ai.usage.input_tokens` on its `invoke_agent` span (the orchestration wrapper) in addition to its child `chat` span. Aggregation by `gen_ai.operation.name` yielded a 2.0x token inflation because both the wrapper and the child reported the same model usage. 3. **Missing `gen_ai.agent.name` on nested invocations.** Sub-agent spans carried `gen_ai.operation.name=invoke_agent` but omitted `gen_ai.agent.name`, relying on the parent's attribute. Since span attributes are not inherited in OTLP, the sub-agent was unidentifiable at the collector. The structural signal of nesting (parent_span_id) was present, but the semantic signal (agent name) was not. The common thread: each span was internally well-formed, but the *cross-span invariants* — call-id linkage and single-owner token accounting — were violated. ## Condition of Validity The invariant "token attributes belong only to `chat` spans" holds **only when** the instrumentation emits one `chat` span per model API call and does not split a single model call across multiple spans (e.g., request/response spans). If instrumentation uses a request span + response span pattern, token attributes legitimately appear on the response span, and the operation name may be `chat` on both. Under that pattern, aggregation must key on `span.kind=CLIENT` plus a shared trace/parent, not on operation name alone. The invariant "tool spans carry no token attributes" holds **only when** tool execution is local. For remote tool execution (e.g., a hosted code interpreter), the remote service may itself perform model calls; in that case the tool span may legitimately be a parent of child `chat` spans carrying tokens, but the tool span itself should still not carry token attributes — the tokens belong to its children. The invariant "`gen_ai.agent.name` is required on `invoke_agent` spans" holds **only when** the agent identity is known at span start. For dynamically spawned agents whose name is determined mid-execution, the attribute may be set at span end; consumers must tolerate its absence on in-flight spans and must not treat absence as "not an agent span" — `gen_ai.operation.name=invoke_agent` is the authoritative signal. ## Decision Boundary The boundary at which instrumentation and consumers must diverge: - **If** `gen_ai.operation.name == "chat"` **then** token attributes are expected and tool-call attributes are optional (present when the response contains tool calls). - **If** `gen_ai.operation.name == "execute_tool"` **then** `gen_ai.tool.name` and `gen_ai.tool.call.id` are expected; token attributes must be absent; the span must be linkable to a parent `chat` span via matching `gen_ai.tool.call.id` recorded as a span event or attribute on that parent. - **If** `gen_ai.operation.name == "invoke_agent"` **then** `gen_ai.agent.name` is expected (possibly set late); token attributes must be absent on the wrapper itself; child `chat` spans own the tokens. A consumer that aggregates cost by summing `gen_ai.usage.*` across all spans in a trace **will over-count** whenever a wrapper span duplicates child token attributes. A consumer that filters tool spans by presence of token attributes **will drop all tool spans**, since the convention forbids them there. The decision boundary is: *validate schema per operation name, not per span.* ## Operational Effect The practical consequence is that GenAI trace validation must be **operation-scoped**, not span-scoped. A validator that checks "every gen_ai span has tokens" produces false positives on every tool span and every agent wrapper, and false negatives on chat spans that legitimately report zero tokens (cached responses, empty completions). Cost pipelines that aggregate by trace root rather than by `chat`-operation spans inflate by the number of wrapper layers. Call-graph reconstruction that relies on `gen_ai.tool.call.id` linkage fails silently when the chat span records the call id only in message content — the linkage must be promoted to a span attribute at emission time, or the tool span is orphaned. The remediation is to enforce the per-operation schema at the instrumentation boundary and reject spans that violate the cross-span invariants before they reach the collector, as encoded below. ```python from dataclasses import dataclass from typing import Mapping, Optional class GenAISpanInvariantError(RuntimeError): """Raised when a GenAI span violates per-operation semantic invariants.""" pass @dataclass(frozen=True) class GenAISpan: operation_name: str attributes: Mapping[str, object] parent_span_id: Optional[str] = None span_id: str = "" _TOKEN_ATTRS = ("gen_ai.usage.input_tokens", "gen_ai.usage.output_tokens") _TOOL_ATTRS = ("gen_ai.tool.name", "gen_ai.tool.call.id") _AGENT_ATTRS = ("gen_ai.agent.name",) def validate_genai_span(span: GenAISpan) -> None: op = span.operation_name attrs = span.attributes if op == "chat": # Chat spans own token accounting; tool attrs are optional. if not any(a in attrs for a in _TOKEN_ATTRS): # Allowed only for cached/empty responses; require explicit marker. if attrs.get("gen_ai.response.cached") is not True: raise GenAISpanInvariantError( f"chat span {span.span_id} missing token usage and no cache marker" ) return if op == "execute_tool": for a in _TOOL_ATTRS: if a not in attrs: raise GenAISpanInvariantError( f"execute_tool span {span.span_id} missing required {a}" ) for a in _TOKEN_ATTRS: if a in attrs: raise GenAISpanInvariantError( f"execute_tool span {span.span_id} must not carry {a}; " "tokens belong to the parent chat span" ) if span.parent_span_id is None: raise GenAISpanInvariantError( f"execute_tool span {span.span_id} orphaned: no parent chat span" ) return if op == "invoke_agent": if not any(a in attrs for a in _AGENT_ATTRS): raise GenAISpanInvariantError( f"invoke_agent span {span.span_id} missing gen_ai.agent.name" ) for a in _TOKEN_ATTRS: if a in attrs: raise GenAISpanInvariantError( f"invoke_agent span {span.span_id} must not carry {a}; " "wrapper spans must not duplicate child token usage" ) return raise GenAISpanInvariantError( f"unknown gen_ai.operation.name={op!r} on span {span.span_id}" ) def validate_trace(spans: list[GenAISpan]) -> None: chat_call_ids = { s.attributes.get("gen_ai.tool.call.id") for s in spans if s.operation_name == "chat" } for s in spans: validate_genai_span(s) if s.operation_name == "execute_tool": cid = s.attributes.get("gen_ai.tool.call.id") if cid not in chat_call_ids: raise GenAISpanInvariantError( f"tool span {s.span_id} call_id={cid!r} has no matching chat span; " "promote the call id to a span attribute on the chat span" ) ```