feat(gen-ai): require provider-supplied tool call ID on execute_tool (#489)

[1aifanatic]

Description

Fixes #489.

This PR clarifies the semantics and requirement level of gen_ai.tool.call.id:

• Clarifies in the attribute definition that gen_ai.tool.call.id MUST carry the identifier generated and supplied by the model or provider, and MUST NOT be populated with synthesized fallback identifiers (such as object memory addresses or sequential indices).
• Promotes the attribute on execute_tool spans from Recommended: If available. to Conditionally Required: If the model or provider supplied a tool call identifier..

Motivation

• User journey: Causal attribution, auditability, and incident triage in multi-step and parallel agentic execution. In enterprise agentic systems, correlating an execute_tool span back to the exact model generation that requested it is essential for tracing decision causality, verifying tool parameters, and auditing actions against system-of-record updates.
• Why absence must be load-bearing: At Recommended, omitting the attribute is ambiguous: it could mean the provider didn't supply an ID, the operator disabled recommended attributes, or the instrumentation hasn't implemented it. Promoting to Conditionally Required: If the model or provider supplied a tool call identifier. gives absence deterministic meaning: an omitted attribute reliably indicates the provider did not supply one, eliminating the temptation for frameworks to manufacture synthetic fallback IDs.
• Failure mode of synthetic IDs: When frameworks synthesize local fallback IDs—such as CrewAI's previous f"call_{id(tool_call)}"—CPython address reuse after garbage collection causes collision across retries and parallel tool calls, silently corrupting causal joins in downstream observability platforms.
• Prior art: CrewAI (feat(events): expose native tool call ids crewAIInc/crewAI#7189) explicitly documented that local pairing fallbacks must not be emitted as provider correlation keys in telemetry. The condition pattern mirrors standard semconv precedents like http.route.

Prototype

10 existing reference scenarios in this repository already emit gen_ai.tool.call.id (agent-framework, autogen, google-adk, google-genai, langchain, llamaindex, openai-agents, openai-assistants, pydantic-ai, vertexai). In all cases, they extract and emit the model/provider-attested identifier directly from the provider response. All scenarios and Weaver policy checks conform cleanly.

Checklist

• Motivation section filled in above
• Reference scenarios updated for affected libraries
• Towncrier fragment added under changelog.d/489.clarification.md

[Copilot]

🟢 Approval recommended

The model, generated documentation, and changelog consistently implement the scoped clarification.

Pull request overview

Clarifies gen_ai.tool.call.id as a provider/model-supplied correlation identifier and makes it conditionally required on execute_tool spans.

Changes:

• Prohibits synthesized fallback tool-call identifiers.
• Promotes the attribute from recommended to conditionally required when supplied.
• Regenerates documentation and adds a clarification changelog entry.

File summaries

File	Description
model/gen-ai/spans.yaml	Updates the execute_tool requirement level.
model/gen-ai/registry.yaml	Defines identifier provenance and prohibits local fallbacks.
docs/registry/attributes/gen-ai.md	Regenerates attribute registry documentation.
docs/gen-ai/gen-ai-spans.md	Regenerates span documentation.
changelog.d/489.clarification.md	Records the clarification.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-09-22 07:36 UTC

Review the latest changes.

Also blocked by: Merge conflicts.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[1aifanatic]

/dashboard route:reviewers

[opentelemetry-pr-dashboard]

@1aifanatic, this pull request was routed to reviewers. The handoff remains active across pushes until newer actionable human feedback arrives. Top-level feedback through this request will not return; unresolved review threads remain open.