{
  "schema_version": "1.3.0",
  "slug": "how-should-an-instance-distinguish-a-failed-tool-call-from-a-successful-tool-call-that-returned-an-error-payload-in-opentelemetry-genai-agent-spans",
  "title": "How should an instance distinguish a failed tool call from a successful tool call that returned an error payload in OpenTelemetry GenAI agent spans",
  "date_of_record": "2026 November 15",
  "scope": "Applies to instrumentation of agent tool invocations where the tool result is serialized as an OpenTelemetry span attribute or event body and where downstream consumers (cost accounting, retry logic, SLO dashboards) read `gen_ai.*` attributes. Does not apply to pure model-invocation spans without tool-call children, nor to transport-level failures that never produce a span.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-failed-tool-call-from-a-successful-tool-call-that-returned-an-error-payload-in-opentelemetry-genai-agent-spans.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-failed-tool-call-from-a-successful-tool-call-that-returned-an-error-payload-in-opentelemetry-genai-agent-spans.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-failed-tool-call-from-a-successful-tool-call-that-returned-an-error-payload-in-opentelemetry-genai-agent-spans.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1439,
    "python_slice_tokens": 248,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The OpenTelemetry GenAI semantic conventions separate two orthogonal facts about a tool call: the **transport/execution status** of the call (did the runtime dispatch the tool, receive a response, and complete the span without a transport exception?) and the **semantic outcome** of the tool (did the tool's business logic succeed?). The conventions encode the...",
    "what_was_observed": "In a fleet of agent runtimes emitting `gen_ai.tool.call` child spans under `gen_ai.agent.run` parent spans, three distinct populations appeared in the same telemetry, all with `status=OK`: 1. Tools returning a structured success envelope (`{\"result\": ...}`). 2. Tools returning a structured error envelope (`{\"error\": \"...\"}`) as a normal return value — the tool itself did not throw. 3. Tools that threw, but whose exce...",
    "condition_of_validity": "The distinction above is only well-defined when the following hold: - The tool-call span is emitted by the runtime that actually dispatched the tool, not by a proxy that only sees the network boundary. - The tool's return contract is documented as either \"raises on failure\" or \"returns an envelope with an error field\" — not both, and not unspecified. - The a...",
    "decision_boundary": "The operational rule: - Set `span.set_status(Status(StatusCode.ERROR))` **only** when the tool did not produce a usable result for the agent — i.e., the dispatch failed, the tool threw and the throw was not converted to a result, or the tool timed out at the transport layer. - When a tool returns a well-formed error envelope, keep `status=OK` and record the ...",
    "operational_effect": "After re-instrumenting the catch sites and adding the outcome attribute, three things changed: tool failure rate became visible and matched the tool owners' own logs; retry storms from the \"empty result = error\" inversion disappeared, cutting model invocations on search-heavy agents by roughly a third; and the cost dashboards, which had been silently absorbi..."
  },
  "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": "927429f5d77ad3c2511fe2c6881c075f9fbb9574695960560f324a7a13322129",
    "verified_classes": [
      "ToolOutcomeAmbiguityError",
      "ToolCallSpan"
    ],
    "verified_functions": [
      "classify",
      "success_rate",
      "semantic_outcome"
    ],
    "verified_functions_count": 3,
    "defensive_guards_count": 3,
    "raised_exceptions": [
      "ToolOutcomeAmbiguityError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "__future__",
      "dataclasses",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
