Transparency
Transparency is a design requirement for AI agent products, not just a nice-to-have. Users who don't understand what an agent did — what data it accessed, what tools it used, what decisions it made along the way — cannot meaningfully evaluate its output. They can't calibrate their trust. And they can't catch errors.
The challenge is that full transparency is overwhelming. A raw tool call log — JSON objects with timestamps, inputs, outputs, token counts — is machine-readable but not human-readable. Showing it to end users produces one of two reactions: confusion or alarm. Neither is what you want.
Good trace visualization solves this problem: it makes the agent's actions legible without making them frightening. Here's how to do it.
Before designing the UI, establish what different users need to see:
End users (non-technical, using your product) need to know: did the agent use external data? Did it access anything sensitive? Did anything fail? What was the high-level sequence of steps?
Power users and operators need more: which tools exactly, what data was queried, approximate timing, whether there were retries or fallbacks.
Engineers and developers need everything: full inputs and outputs, exact timestamps, error messages with stack traces, token usage, model version.
A good ToolTrace component serves all three audiences through progressive disclosure. The collapsed state serves end users. Expanding one level serves power users. Expanding all the way serves engineers. The same component, different levels of visibility.
When a trace is collapsed, it should show exactly three things:
Nothing else. Not the function name. Not the raw input parameters. Not the response object size. Users don't need to see fetch_revenue_data(start_date='2025-01-01', end_date='2025-12-31', segment='enterprise') to understand that the agent queried revenue data. The human-readable label is enough at the collapsed level.
The human-readable label for each tool call is where most implementations fail. Teams surface the technical function name (query_warehouse) and wonder why users are confused. The function name is meaningless to non-engineers.
Every tool in your agent should have a display name — a human-readable description of what it does. This is not a UI concern; it's an agent architecture concern that happens to surface in the UI. The agent schema should include a display_name field alongside the function name.
Examples of bad vs. good tool display names:
query_warehouse → "Searched sales data"fetch_user_cohort → "Loaded customer segment"execute_sql → "Ran database query"send_email_via_sendgrid → "Sent email"Status indicators need to be unambiguous at a glance:
Success: Green check. Universally understood. Use it.
Running: Animated spinner or pulsing indicator. This is critical for streaming tool calls — users need to see that something is happening, not wonder if the interface is frozen.
Failed: Red X. Clear, but don't leave it without explanation. Failed tool calls should be expandable to show the error message in a non-technical format ("The database returned an error — the query may have timed out") alongside the raw error for engineers.
Pending: Subtle, greyed out. Shows the planned sequence without implying it's executing.
Some tool calls return large data: a database query might return thousands of rows, an API call might return a large JSON payload. Showing all of it inline is not an option — it would destroy the layout and overwhelm users.
The pattern that works: show a summary of the output in the collapsed state ("2,847 rows returned"), and in the expanded state show a truncated preview with a note about the total size and an option to export the full result. Never dump raw JSON on users unless they're in an explicit developer mode.
Two common patterns for where to display traces:
Inline in the thread: Tool call results appear as special message types between the user message and the assistant's response. The sequence is visible: user asks, agent uses tools (shown inline), agent responds. This is the most transparent pattern — users see exactly when tools were used in relation to what they asked.
Sidebar or collapsible panel: The conversation thread stays clean; tool traces are accessible in a side panel or via a "show trace" toggle on each assistant message. This is cleaner visually but requires users to actively seek out the trace information.
The right choice depends on your users. For technical users who actively want to inspect tool usage, inline is better. For end users who mostly want the answer, sidebar keeps the interface uncluttered while preserving transparency for those who need it.
The goal isn't to show users everything — it's to show them enough that they can trust what they can't see.
Users who can see what their agent did develop a calibrated mental model of its capabilities and limitations. They learn which tools it uses for which tasks. They develop intuitions about when to trust its output and when to verify. They catch errors not because the trace surfaced a red icon, but because they've learned enough about the agent's behavior to notice when something looks off.
This calibrated trust is more valuable than either blind trust (users accept everything) or no trust (users verify everything). Trace visualization, done well, is how you build it.
The ToolTrace component in Agent Interface implements progressive disclosure, human-readable tool names, multi-state indicators, and large output handling out of the box. Get early access →
Continue reading
All the UI primitives you'll need, and why they're harder than they look.
Read →Cognitive load, trust calibration, and the decisions that matter.
Read →When to pause, when to proceed, and how to present the decision.
Read →