Span helpers for LLM tool / function calls. Provider-agnostic — works for any agent loop where the LLM emits structured tool requests and the app executes them.

High-level usage

Impact.Tool.with_call(tool_call, position, fn ->
  Tools.Registry.execute(tool_call.name, tool_call.arguments)
end)

Opens a tool.<name> span, sets request-side gen_ai.tool.* attributes upfront, runs the closure, and stamps result-side attributes (gen_ai.tool. call.result, gen_ai.tool.call.result.status) before returning whatever the closure returned.

Result classification

The closure can return any of these shapes; with_call/3 interprets them as follows:

The original return value is passed through unchanged — wrapping in a span does not alter the function's contract.

Manual control

If you need finer control (e.g., custom status strings, mid-call events), call Impact.trace directly and use attrs_for_call/2 + attrs_for_result/2 to build attributes.

Attribute keys (OTel GenAI semantic conventions)

Request side (attrs_for_call/2):

• gen_ai.operation.name = "execute_tool"
• gen_ai.tool.name — tool name
• gen_ai.tool.call.id — the tool-use ID assigned by the model
• gen_ai.tool.call.arguments — JSON-encoded input
• gen_ai.tool.type = "function"
• gen_ai.tool.call.position — 0-based index in the model's batch

Result side (attrs_for_result/2):

• gen_ai.tool.call.result — JSON-encoded result (or raw string)

• gen_ai.tool.call.result.status — "success" | "error" (or any string)