{
  "schema_version": "1.3.0",
  "slug": "in-what-scenarios-must-an-instance-treat-opentelemetry-genai-tool-call-spans-as-non-atomic-for-token-accounting",
  "title": "In what scenarios must an instance treat OpenTelemetry GenAI tool-call spans as non-atomic for token accounting",
  "date_of_record": "2026 November 15",
  "scope": "Applies to services that emit `gen_ai.*` spans per the OpenTelemetry GenAI semantic conventions and aggregate `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` from child tool-call spans into a parent chat span for billing or quota enforcement. Does not apply to providers that report a single consolidated usage block on the top-level chat span with no per-tool child spans.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-tool-call-spans-as-non-atomic-for-token-accounting.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-tool-call-spans-as-non-atomic-for-token-accounting.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-tool-call-spans-as-non-atomic-for-token-accounting.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1800,
    "python_slice_tokens": 421,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The GenAI semantic conventions define token usage attributes on the *chat/model invocation* span (`gen_ai.operation.name = \"chat\"`), and separately define tool execution spans (`gen_ai.operation.name = \"execute_tool\"`). These are distinct span kinds with distinct attribute contracts. The non-obvious boundary is this: **a tool-call span is not a token-bearing...",
    "what_was_observed": "In a production agent-runtime deployment (multi-turn tool-calling loop, ~40 tool types), the following was observed over a two-week window: 1. A middleware layer added `gen_ai.usage.input_tokens` to `execute_tool` spans to approximate \"context tokens sent to the tool,\" reasoning that the tool received serialized context. This attribute is not sanctioned by the conventions for tool spans, but the aggregator summed it ...",
    "condition_of_validity": "This distinction is valid—and the aggregation guard is required—under the following conditions: - The trace contains `gen_ai.operation.name = \"execute_tool\"` spans anywhere in or adjacent to the chat span's subtree. - Any span in the subtree carries a `gen_ai.usage.*` attribute where `gen_ai.operation.name` is not `\"chat\"` or `\"embeddings\"`. - Tool-call span...",
    "decision_boundary": "The decision procedure for an aggregator at each chat span: 1. Locate the span whose `gen_ai.operation.name` is `\"chat\"` (the model-invocation span). This span, and only this span, is the usage source of record for that model call. 2. Read `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from that span. Treat **absent as unknown, not zero**. An u...",
    "operational_effect": "Enforcing the boundary changes three operational behaviors: - **Billing accuracy:** overstatement from tool-span double-counting is eliminated; the residual error is bounded by provider-vs-instrumentation clock skew, not by tool fan-out. - **Alerting semantics:** `usage_partial` and `orphan_tool_span` become first-class signals. A rising `usage_partial` rate..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "32973d7ec9a29d7acb336808595ed62cd14b121008ebc4b98bf8c914c953ce32",
    "verified_classes": [
      "UsageAccountingError",
      "Span",
      "UsageRecord"
    ],
    "verified_functions": [
      "aggregate_usage",
      "enforce_quota"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 5,
    "raised_exceptions": [
      "UsageAccountingError"
    ],
    "sample_fail_closed_invariants": [
      "no chat span found in span set",
      "cannot enforce quota on partial/unknown usage; defer or deny rather than defaulting to zero"
    ],
    "stdlib_dependencies": [
      "__future__",
      "dataclasses",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
