# What happens when an instance reports tool-call spans without a parent `invoke_agent` span: orphaned GenAI telemetry and the span-link invariant **Date of Record:** 2026 November 16 **Scope:** Applies to OpenTelemetry instrumentation of LLM agents that emit `gen_ai.*` semantic convention attributes across `invoke_agent`, `execute_tool`, and `chat`/`generate_content` spans, where the collector or backend performs parent-child reconstruction based on `trace_id`/`span_id` only. Does not apply to systems that exclusively use OTLP logs with embedded trace context, nor to single-shot model invocations that never involve tool calls. ## Core Distinction The distinction that matters here is between *span presence* and *span topology*. The GenAI semantic conventions define attribute namespaces (`gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, etc.) and specify that tool execution should be represented as `execute_tool` spans and agent orchestration as `invoke_agent` spans. What they do *not* enforce at the wire level is that an `execute_tool` span is a descendant of the `invoke_agent` span that decided to call the tool. Instrumentation libraries, especially when tool execution is delegated to a worker pool, a separate process, or a remote MCP server, frequently emit the `execute_tool` span in a context where the active span is the HTTP client span or nothing at all. The result is a trace that contains all the right attribute names but the wrong graph — orphaned tool spans whose `gen_ai.tool.call.id` cannot be joined to the model invocation that produced the call. ## What Was Observed In a deployment instrumenting a planner/executor agent, `execute_tool` spans were emitted from a `ThreadPoolExecutor` whose worker threads did not inherit the OTel `Context`. The spans were created with valid `trace_id` (propagated via an explicit `Context.attach` in the submitting thread) but their parent was the executor's internal `run` span, not the `invoke_agent` span. Downstream, a trace-stitching pipeline that assumes `parent_span_id` of `execute_tool` == `span_id` of the active `invoke_agent` silently dropped 100% of tool spans from the agent-latency rollup. The spans existed, the attributes were correct, `gen_ai.tool.name` was populated, `gen_ai.usage.*` on the sibling `chat` spans was correct — and yet the agent's tool-call latency was reported as zero. A second symptom: `gen_ai.tool.call.id` appeared on both a `chat` span's `gen_ai.tool.call.id` event attribute and the `execute_tool` span, but no backend join key existed because the conventions do not mandate that the tool-call id be recorded as a span link on the invoking `chat` span. The correlation was semantically intended but structurally unenforced. A third, subtler observation: when the agent retried a tool call, the retry `execute_tool` span reused the same `gen_ai.tool.call.id` but a new `span_id` under a different parent. Consumers keying on `gen_ai.tool.call.id` alone double-counted; consumers keying on span topology undercounted. Neither the spec nor the instrumentation defined which was authoritative. ## Condition of Validity The invariant "tool-call telemetry is attributable to the invoking agent span" holds only when all three of the following are true: 1. The instrumentation guarantees `Context` propagation across the execution boundary that runs the tool (thread, process, async task, or remote hop), such that the `execute_tool` span's parent is the `invoke_agent` span or a descendant of it. 2. The `gen_ai.tool.call.id` is recorded on *both* the model-invocation span (as the event/attribute that requested the call) and the `execute_tool` span, and consumers treat the pair `(trace_id, gen_ai.tool.call.id)` as the join key rather than span topology alone. 3. Retries are represented as distinct `execute_tool` spans with a retry-attempt attribute (e.g., a custom `gen_ai.tool.retry.attempt`), because the conventions do not define retry semantics and `gen_ai.tool.call.id` is not guaranteed unique per attempt. If any of these fail, any pipeline that reconstructs agent behavior from span parentage is operating on an unvalidated assumption. ## Decision Boundary The operational decision is whether to *reject* orphaned `execute_tool` spans at ingest or to *repair* them. Rejecting is correct when the backend's agent analytics depend on topology and a mis-parented span would corrupt latency percentiles; the cost is losing real tool executions that happened but were mis-instrumented. Repairing (re-parenting by `gen_ai.tool.call.id` join) is correct when the join key is reliably present on the invoking span; the cost is that a missing or duplicated call id produces a silently wrong graph. The boundary is the presence of the join key on the invoking span: if `gen_ai.tool.call.id` is absent from the `chat`/`invoke_agent` span that requested the tool, repair is impossible and the span must be quarantined rather than guessed at. Do not re-parent by timestamp proximity — concurrent agents in the same trace make that ambiguous. ## Operational Effect Once the invariant is enforced (either by fixing context propagation or by join-key repair with quarantine on missing keys), agent latency rollups become correct, tool-call success rates stop being computed over a biased subset, and retry double-counting disappears. The residual effect is that the collector must carry a validation stage that knows the GenAI conventions well enough to distinguish "span with correct attributes but wrong parent" from "span that is genuinely a root." That stage is where the failure mode lives, and it is invisible to any check that only validates attribute schema conformance. ```python from __future__ import annotations from dataclasses import dataclass from typing import Iterable, Mapping, Optional class OrphanedToolSpanError(RuntimeError): """Raised when an execute_tool span cannot be attributed to an invoking agent span.""" @dataclass(frozen=True) class Span: trace_id: str span_id: str parent_span_id: Optional[str] operation_name: str # gen_ai.operation.name tool_call_id: Optional[str] # gen_ai.tool.call.id attributes: Mapping[str, str] def validate_tool_attribution( spans: Iterable[Span], *, require_join_key: bool = True, ) -> dict[str, str]: """ Return a mapping of execute_tool span_id -> resolved invoking span_id. Raise OrphanedToolSpanError when a tool span cannot be attributed. The invariant: every execute_tool span must either (a) have a parent that is an invoke_agent span in the same trace, or (b) carry a gen_ai.tool.call.id that also appears on exactly one invoke_agent/chat span in the same trace. """ by_trace: dict[str, list[Span]] = {} for s in spans: by_trace.setdefault(s.trace_id, []).append(s) resolved: dict[str, str] = {} for trace_id, trace_spans in by_trace.items(): invoking_by_call_id: dict[str, list[Span]] = {} for s in trace_spans: if s.operation_name in ("invoke_agent", "chat") and s.tool_call_id: invoking_by_call_id.setdefault(s.tool_call_id, []).append(s) span_ids = {s.span_id for s in trace_spans} for s in trace_spans: if s.operation_name != "execute_tool": continue parent_ok = ( s.parent_span_id is not None and s.parent_span_id in span_ids and any( p.span_id == s.parent_span_id and p.operation_name == "invoke_agent" for p in trace_spans ) ) if parent_ok: resolved[s.span_id] = s.parent_span_id # type: ignore[assignment] continue if not require_join_key: continue candidates = invoking_by_call_id.get(s.tool_call_id or "", []) if len(candidates) == 1: resolved[s.span_id] = candidates[0].span_id continue raise OrphanedToolSpanError( "execute_tool span {span} in trace {trace} has parent {parent!r} " "which is not an invoke_agent span, and gen_ai.tool.call.id {call!r} " "resolved to {n} invoking spans (expected exactly 1). " "Quarantine this span; do not re-parent by timestamp.".format( span=s.span_id, trace=trace_id, parent=s.parent_span_id, call=s.tool_call_id, n=len(candidates), ) ) return resolved ```