A tool-call span must carry name, call id, arguments, result, status, and latency. Without those six, the trace cannot be debugged when a tool call goes sideways in production.
Picture a kitchen ticket that travels with one order from the counter to the line cook and back. If the ticket only says 'burger' but not which table, which sides, whether the cook actually made it, or how long it took, the manager has nothing to investigate when a customer complains. A tool-call span is that ticket. The name tells you what the model asked for, the call id tells you which model message it belongs to, the arguments are the order details, the result is what came back, the status says whether the cook burned it, and the latency says how long the kitchen took. Skip any of these and the next post-mortem turns into a guessing game.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Tool-call spans are the most under-instrumented part of most agent systems. Teams remember to capture model spans because vendor SDKs do it automatically. Tool spans are user code, so the attributes are whatever the engineer typed in by hand, and a tired engineer types in less than they should.
The consequence is that when something goes wrong in production, the trace shows that a tool was called and how long it took, but not what was passed in or what came back. The debugging session collapses into adding logging and waiting for the bug to recur. The fix is to make a discipline of recording the six load-bearing attributes on every tool span, and to use pointer-based storage when the payloads do not fit cleanly as indexed attributes.
The six attributes and what each one buys you
Every tool-call span should carry: tool.name, tool.call_id, tool.arguments, tool.result, status, and latency.
- Tool name. Lets you filter dashboards by tool. A retrieval tool and a calculator tool have different latency distributions and different failure modes; without the name attribute, p99 latency across all tools is meaningless.
- Tool call id. Matches the
idfield inside the assistant message'stool_callsarray. Critical the moment a single turn fires more than one tool. Without it, three parallel results return out of order and you cannot tell which model intent each one satisfied. - Arguments. Lets you reproduce the call. The single highest-value attribute for post-mortems.
- Result. Lets you compare what the tool actually returned against what the model used in its next reasoning step. Hallucinations frequently come from the model misreading a perfectly correct tool result.
- Status. Distinguishes the silent-failure case (tool threw, agent kept going, output looks plausible) from the clean path.
- Latency. Already on the span; explicit mention is for completeness.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- OpenTelemetry GenAI semantic conventions (2026) define `gen_ai.tool.name`, `gen_ai.tool.call.id`, and `gen_ai.tool.type` as stable attributes for tool-call spans.
- Langfuse's auto-instrumentation for LangGraph in 2026 records all six fields by default for every tool node in the graph.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you structure tool-call spans when a single agent turn fires three tools in parallel?
Three sibling child spans under the agent-step parent, each carrying its own tool.call_id matching the assistant message; they share parent span id but have distinct span ids and start/end times that may overlap.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Logging only the tool name and latency to 'keep traces cheap'. Six months later a customer reports a wrong tool result bug and you have nothing to reproduce it with.
60 second bullets to scan on the way to the call.
The six attributes that belong on a tool-call span
Why tool call id is required for multi-tool turns
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.