docs: add governed tool action metadata example

[jw-ond]

Summary

Adds a non-normative GenAI example showing how applications can attach governance metadata to an execute_tool span when a tool call is reviewed before execution.

The example uses application-specific attributes (app.governance.*) so it does not introduce new normative semantic convention attributes. It illustrates action references, approval verdicts, replay/proof URLs, and external verifier references as telemetry that can correlate tool execution with an approval or policy checkpoint.

Validation

• Checked Markdown code fence balance locally
• Confirmed the example is vendor-neutral and uses non-normative app.governance.* attributes
• Added a clarification changelog fragment

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jw-ond / name: jw_ond (0114a05, 5414b14, 63721a2, 2c53ee2)

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds a non-normative documentation example showing how to attach application-specific governance metadata to an execute_tool span for tool calls that are gated by approval/policy checks.

Changes:

• Added a “Governed tool action metadata” example with app.governance.* attributes in the GenAI tool-call docs.
• Added a changelog clarification fragment for the documentation update.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/gen-ai/non-normative/examples-llm-calls.md	Documents a new non-normative example for correlating tool execution telemetry with governance/approval evidence.
changelog.d/+.clarification.md	Adds a changelog fragment noting the new documentation example.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-08-21 01:55 UTC

Review the latest changes.

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.

[jw-ond]

Updated after review: the example SHA-256 value is now a full 64-character digest, and the changelog fragment has been renamed to 417.clarification.md per changelog.d/README.md. The old +.clarification.md fragment was removed from the branch.

[Silentpartnercoding]

One trust boundary may be worth stating explicitly: these app.governance.* attributes are application-emitted correlation claims. The span alone does not prove that the approval gate ran, that the executed inputs matched the approved action.hash, or that the referenced proof/verifier was independently validated.

Could the example add one sentence such as: “These attributes are correlation claims, not authorization or verification evidence; consumers must independently validate the referenced proof before treating the execution as approved.”

That would preserve the example’s purpose without making an execute_tool span look like an authorization receipt.

[jw-ond]

Thanks, that trust-boundary wording is right. Updated the example to state that the app.governance.* attributes are correlation claims, not authorization or verification evidence, and that consumers must independently validate the referenced approval/verifier/proof material before treating them as governance evidence.

[jw-ond]

/dashboard route:reviewers

[opentelemetry-pr-dashboard]

@jw-ond routed this pull request to reviewers.

[lmolkova]

None of the attributes added in the example are existing attributes defined in this repo. Applications are free to add them, but this is not something they should expect from OpenTelemetry GenAI instrumentations, hence it's controversial to have them in examples.

While the current language says that it's non-normative, the example is very specific and reads more prescriptive than 'attach whatever attributes you want'.

The example can be changed in a more generic way: do not mention specific attributes, use something like acme.custom.attribute, emphasize that applications can add them on any spans, tool calls or not.

[jw-ond]

Addressed the requested change in the latest commits. The example no longer defines or suggests app.governance.* attributes; it now uses a generic acme.custom.attribute placeholder, states that custom attributes are outside the OpenTelemetry GenAI semantic conventions, and notes that they can be added to any span, including GenAI client spans, execute-tool spans, or surrounding application spans. It also keeps the trust-boundary wording that custom attributes are application claims, not authorization or verification evidence.

Also fixed the generated TOC anchor after the section rename. All current PR checks are passing.

/dashboard route:reviewers