# When must an instance refuse to emit a GenAI agent span: the tool-call/token-accounting divergence boundary **Date of Record:** 2026 November 15 **Scope:** Applies to OpenTelemetry GenAI semantic conventions (as of the `gen_ai.*` attribute set for agent, tool-call, and token-usage instrumentation) in systems where an agent runtime emits spans for both model invocations and tool executions, and where billing or quota decisions are derived from summed `gen_ai.usage.*` attributes. Does not apply to pure inference-server tracing where no tool-call spans are produced, nor to vendor-specific proprietary span schemas that do not claim GenAI semconv conformance. ## Core Distinction The non-obvious boundary is this: **a GenAI agent span is a *record of a decision*, not a *ledger of cost*.** The semantic conventions define `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` as attributes of a *model invocation* span (the `gen_ai.operation.name = "chat"` span, or equivalent). Tool-call spans (`gen_ai.operation.name = "execute_tool"`) are *sibling* spans describing side effects and arguments. The conventions do not require — and deliberately do not define — that tool-call spans carry token attributes, because a tool execution does not itself consume model tokens. The failure appears when an operator treats the *agent trace tree* as a single accounting unit. If you sum `gen_ai.usage.*` across every span in an agent trace, you double-count: once on the parent chat span that produced the tool-call request, and again if any child span re-emits the same usage for "context" or "reasoning" attribution. Conversely, if you sum only leaf spans, you *under*-count the planning tokens consumed by the parent that decided to call the tool. Neither aggregation is correct, and neither is detectable from the span attributes alone. ## What Was Observed In a multi-step agent loop (plan → tool-call → observe → re-plan), the runtime emitted: - Parent span `chat` with `gen_ai.usage.input_tokens = 1840`, `gen_ai.usage.output_tokens = 220`, containing a `gen_ai.tool.call.id` argument. - Child span `execute_tool` with `gen_ai.tool.name`, `gen_ai.tool.call.id`, and — because a well-meaning instrumentation library "propagated context" — a *copy* of the parent's `gen_ai.usage.*` attributes. - A subsequent `chat` span for the re-plan step with its own usage. A naive `sum(gen_ai.usage.input_tokens) by (trace_id)` produced 1840 + 1840 + (next step) — a 100% overcount on the first step. A naive `sum(...) where operation.name = "chat"` produced the correct total but silently dropped any tool span that *did* legitimately carry usage (e.g., a tool that internally invokes a model, such as a summarizer or a code-interpreter's LLM call). The two aggregations diverged by exactly the amount of nested-model tool usage, and no attribute distinguished "copied usage" from "real nested usage." ## Condition of Validity The invariant holds **only when** every `gen_ai.usage.*` attribute on a span is understood as *tokens consumed by the model invocation that this span represents*, and the span's `gen_ai.operation.name` is a model-invoking operation. The moment an instrumentation library copies usage attributes onto a non-model span (tool execution, agent wrapper, retrieval step), the invariant is violated and any downstream sum is unsound. A second condition: the `gen_ai.tool.call.id` must be *unique and stable* across the request span and the execution span, and must not be reused across retries. If a retried tool call reuses the id, deduplication by `tool.call.id` will silently merge distinct executions. ## Decision Boundary An instance must **refuse to emit** a `gen_ai.usage.*` attribute on a span whose `gen_ai.operation.name` is not a model-invoking operation, *unless* that span itself directly invoked a model (nested-model tool). It must **refuse to aggregate** token usage across a trace tree without first partitioning spans by operation name and de-duplicating by `(trace_id, span_id)` of the model-invoking span. It must **refuse to accept** a tool-call span that lacks a `gen_ai.tool.call.id` when a sibling chat span references that id. The boundary is crossed — and the instance should fail closed rather than emit a misleading trace — when these conditions cannot be satisfied. Emitting a trace with ambiguous usage is worse than emitting no trace, because the ambiguity is invisible to the consumer and propagates into billing. ## Operational Effect Systems that crossed this boundary reported quota exhaustion at roughly 2× the expected rate during tool-heavy agent workloads, with no corresponding model-provider invoice to match. The root cause was always the same: usage attributes duplicated onto tool spans, then summed by a dashboard that trusted the trace tree as a ledger. The corrective action is a hard invariant at the instrumentation layer (reject copied usage) plus a validation pass at the collector (reject tool spans with usage but no nested model invocation marker). Once enforced, summed usage matched provider invoices to within rounding, and the 2× anomaly disappeared. ```python class GenAITokenAccountingError(RuntimeError): """Raised when a span's token attributes cannot be soundly aggregated.""" pass MODEL_OPERATIONS = frozenset({"chat", "text_completion", "embeddings", "generate_content"}) def validate_usage_attribution(span: dict) -> None: """ Enforce the GenAI usage-attribution invariant on a single span. A span may carry gen_ai.usage.* only if it represents a model invocation, or if it is a tool span that explicitly declares a nested model call. """ attrs = span.get("attributes", {}) op = attrs.get("gen_ai.operation.name") has_usage = any(k.startswith("gen_ai.usage.") for k in attrs) if not has_usage: return if op in MODEL_OPERATIONS: return # Tool span carrying usage: only legal if it self-declares a nested model call. if op == "execute_tool": if attrs.get("gen_ai.tool.nested_model_invocation") is True: return raise GenAITokenAccountingError( f"tool span {span.get('span_id')} carries gen_ai.usage.* without " f"nested_model_invocation marker; usage is likely copied from parent " f"and must not be summed." ) raise GenAITokenAccountingError( f"span {span.get('span_id')} with operation {op!r} carries gen_ai.usage.* " f"but is not a model-invoking operation; refusing to emit." ) def aggregate_trace_usage(spans: list[dict]) -> dict[str, int]: """ Sum token usage across a trace, partitioning by model-invoking span and de-duplicating by span_id. Raises if any span violates attribution. """ seen: set[str] = set() totals = {"input_tokens": 0, "output_tokens": 0} for span in spans: validate_usage_attribution(span) op = span.get("attributes", {}).get("gen_ai.operation.name") if op not in MODEL_OPERATIONS and not ( op == "execute_tool" and span.get("attributes", {}).get("gen_ai.tool.nested_model_invocation") is True ): continue sid = span["span_id"] if sid in seen: raise GenAITokenAccountingError( f"duplicate model-invoking span_id {sid} in trace; refusing to double-count." ) seen.add(sid) a = span["attributes"] totals["input_tokens"] += int(a.get("gen_ai.usage.input_tokens", 0)) totals["output_tokens"] += int(a.get("gen_ai.usage.output_tokens", 0)) return totals ```