Tool list
A project with no tool call in the last 90 days shows an empty state with a TypeScript and Python snippet that records a named tool call (
agent.traceTool inside zespan.withAgent, or zespan.trace_tool_fn). Agent framework integrations such as LangChain, OpenAI Agents and Google ADK record tool calls on their own, so the snippet is only needed for tools you run yourself.
The list and each tool’s detail page count calls the same way. A tool is identified by its tool span’s name (falling back to the span’s tool call ID). Calls come from tool spans; the
tools_used list on LLM and agent spans is only used for a tool that has no tool spans of its own, so one call is not counted twice. The unique_tools KPI counts distinct tools by that same identifier, and a tool’s sample errors are distinct, non-empty messages.
Tool names are bare. A tool span records its tool as tool.search_kb, while an LLM span’s tools_used list holds search_kb. Zespan strips the tool. prefix everywhere, so these are one tool in the list, the detail page, the unique_tools KPIs, the co-occurrence pairs, and the Errors page. On the API, GET /projects/{id}/tools/detail?toolName= accepts either form, search_kb or tool.search_kb. Ranges (24h, 7d, 30d, 90d) are trailing windows.
Sort by failure rate to prioritize reliability work. Sort by avg latency to find performance bottlenecks.
Tool detail
Click any tool to open its detail page.Call history
A paginated list of recent calls with timestamp, agent, input arguments (ifstorePrompts is enabled), return value summary, latency, and outcome.
Latency distribution
A histogram of call durations. A bimodal distribution (two peaks) often indicates cache hit vs cache miss behavior or fast vs slow execution paths.Calling agents
A ranked list of agents that call this tool, with per-agent call counts and failure rates. If one agent has a much higher failure rate than others calling the same tool, the issue is likely in how that agent constructs the tool arguments.Tool span types
Zespan records tool calls as spans of kindtool. Retrieval operations (vector search, document fetch) are recorded as spans of kind retriever. Both appear in the Tools view.
See Span kinds for the full list of span types and what each captures.
Registering tools in code
Tools appear automatically when your agent makes calls that the SDK recognizes as tool spans. For custom tools, wrap the tool function with a manual span:withAgent block you can instead call agent.traceTool(), which records the tool span for you.
See Manual spans for full span API reference.
Next steps
- Traces — inspect individual tool calls in context
- Manual spans — instrument custom tools
- Span kinds — span type reference