Tool calls are the most consequential moment in any AI agent flow. The agent stops being a chatbot and becomes an actor: it reads a file, hits an API, runs a shell command, edits a database row. If the UI hides that moment, users have no way to verify, intervene, or trust what just happened. If the UI overwhelms users with raw JSON, they tune out and click "approve all".

The teams shipping the best AI agent experiences in 2026, Cursor, Anthropic, Replit, Linear, Granola, treat tool calls as a first-class UI surface. They have evolved a small set of repeatable patterns for how to announce a tool call, render its arguments, stream its result, surface failure, and let the user inspect, retry, or roll back. These patterns are now the floor for any serious agent product.

This guide breaks down seven AI tool call UI design patterns founders and product designers should know in 2026. For each one you get a definition, the problem it solves, the agent context where it appears, a real product example, an implementation walkthrough, when not to use it, and accessibility notes.

TL;DR, AI agents that earn trust in 2026 render every tool call as an inspectable, interruptible UI block: name, arguments, streaming result, status, and one-click retry. Hidden tool calls and raw JSON dumps are both broken defaults.

The seven AI tool call UI patterns: a brief overview

• Named tool call cards: Best for replacing raw JSON dumps with a human-readable surface.

• Collapsible argument and result panels: Best for scanning long agent transcripts.

• Pre-flight permission prompts: Best for destructive or external-side-effect tools.

• Streaming partial results inside the call: Best for slow tools (web search, code execution).

• Status badges with retry affordances: Best for unreliable APIs and flaky integrations.

• Inline tool output rendering: Best for rich data types (images, tables, files).

• Tool call timeline view: Best for multi-step agents and post-hoc debugging.

1. Named tool call cards, best for replacing raw JSON dumps with a human-readable surface

A named tool call card is a UI block that renders a single agent tool invocation as a labeled, scoped card with a human-readable title, a short description of what the tool does, the arguments it received, and the result it produced. It is the atomic unit of a trustworthy agent transcript.

The problem it solves is the early-2020s default of dumping raw function-call JSON into a chat log. That format works for engineers debugging at 2am, but it actively hostile for the PM, customer, or executive watching the agent run. Named cards translate the same data into something readable in three seconds.

Where it appears. Coding agents (Cursor, Replit Agent, Claude Code), research agents (Perplexity, Anthropic), workflow agents (Linear AI, Notion AI). Any agent that exposes more than one tool ends up needing this pattern.

Real example. Cursor renders each tool call as a card with the tool name (read_file, run_terminal_cmd, edit_file), a one-line summary of the target, and an expandable region for full arguments and result. Anthropic Console uses the same pattern in its prompt playground, with each tool call collapsed by default and color-coded by status.

How to implement.

• Map each tool name to a human-readable title and short description (read_file becomes "Read file" with a path subtitle)

• Choose an icon per tool family (file, shell, web, database, email) so users orient by shape, not text

• Render the card with three regions: header (tool + status), body (key argument summary), footer (timing, retry link)

• Keep the default card height under 120 pixels so a 10-step agent run still fits on screen

When not to use it. Single-tool agents where the tool is implicit (a pure text summarizer, a pure translator). Forcing a card around every call adds noise without benefit.

Accessibility notes. The card header must be a real heading (h3 or h4), not a styled div, so screen reader users can navigate between calls. Status (success, error, running) must be conveyed by both color and an icon or text label, never color alone.

2. Collapsible argument and result panels, best for scanning long agent transcripts

Collapsible argument and result panels are an extension of the tool call card where the verbose payloads (full arguments object, full tool response) are hidden behind a disclosure toggle by default. The header stays visible. The detail expands on demand. This keeps a 40-step agent run scannable.

The problem it solves is transcript bloat. A single web search tool call can return 5 kilobytes of JSON. A single read_file call can return 800 lines of source code. Render that inline and the human cannot find the agent's actual reasoning between the JSON walls.

Where it appears. Long-running agents (Cursor agent mode, Replit Agent), debugging surfaces (Anthropic Console, LangSmith, Braintrust), multi-step research tools (Perplexity Pro, Claude Projects).

Real example. Anthropic Console collapses every tool call result by default and shows a one-line preview (first 80 characters or a record count). Click to expand. Cursor uses the same pattern, with a per-tool default: short results (under 5 lines) stay open, long results collapse automatically.

How to implement.

• Pick a sensible default: collapse anything over N lines or M kilobytes, leave short results open

• Show a meaningful preview in the collapsed state (record count, first line, file size), never just "Result"

• Persist the expanded state per call so the user can scroll away and come back without losing context

• Provide a session-level "expand all" or "collapse all" control for debugging mode

When not to use it. Short, low-volume tool calls. Collapsing a five-character result wastes a click. Skip the pattern when the entire result fits in two lines.

Accessibility notes. The disclosure toggle must be a real button with aria-expanded, not a clickable div. Keyboard users need Enter and Space to toggle. The expanded region should not steal focus on expand, since users often expand while reading.

3. Pre-flight permission prompts, best for destructive or external-side-effect tools

A pre-flight permission prompt is a UI gate that surfaces a tool call before it executes, shows the user exactly what is about to happen, and requires explicit confirmation. It is the seatbelt of agent UX. It is the difference between an agent that drafts an email and an agent that sends one.

The problem it solves is the irreversible side effect. Once an agent has emailed a customer, deleted a row, or charged a card, no amount of clever UI recovers the action. Permission prompts move the decision back to the human at the only moment where it still costs nothing.

Where it appears. Coding agents about to modify files or run shell commands (Cursor, Replit Agent, Claude Code), workflow agents about to send messages or hit external APIs (Linear AI, Granola, Zapier Agents), database agents about to write or delete (any text-to-SQL tool that goes beyond read-only).

Real example. Cursor surfaces a permission card before any terminal command and any external network call, with the exact command rendered in a code block. The user clicks "Run" or "Skip". Replit Agent does the same for shell commands and package installs. Anthropic's computer use beta gates clicks and keystrokes the same way.

How to implement.

• Classify every tool by reversibility (safe read, reversible write, destructive, external side effect) at tool registration time

• Render the destructive or side-effect calls with a distinct visual treatment (border color, warning icon, larger button)

• Show the literal payload (the SQL, the email body, the file diff) before asking for approval

• Offer a "always approve this kind for this session" option so power users do not get gate fatigue

When not to use it. Read-only tools. Gating a file read or a web search slows the agent without protecting anything. Pre-flight prompts should be reserved for irreversible or side-effect operations.

Accessibility notes. Permission prompts must be operable by keyboard alone, with the safe default (Skip or Cancel) focused first. Never auto-confirm after a timeout. Announce the prompt to assistive tech with role alertdialog.

4. Streaming partial results inside the call, best for slow tools (web search, code execution)

Streaming partial results inside a tool call is the pattern of rendering output incrementally as the tool produces it, instead of waiting for the entire result before showing anything. The user watches the search results populate, the file tokens stream in, or the code execution log scroll line by line.

The problem it solves is the perceived wait. A web search tool that takes eight seconds feels broken if the UI shows a spinner. The same eight seconds feel productive if results stream in starting at 400 milliseconds. Streaming converts wait time into progress.

Where it appears. Web search tools (Perplexity, ChatGPT search, Claude web search), code execution tools (Claude code interpreter, Replit Agent terminal), long-form generation tools (any image, video, or document generator that supports progressive output).

Real example. Claude streams web search results as they arrive, with each citation appearing in the answer as the source is retrieved. Cursor streams terminal output line by line during run_terminal_cmd, matching the cadence of a real shell. Perplexity progressively populates the sources column while the answer streams.

How to implement.

• Choose a streaming protocol the tool naturally supports (SSE, websockets, chunked HTTP) and propagate it to the UI

• Render a skeleton or placeholder for the expected shape (three search result rows, an empty terminal pane) so layout does not jump

• Show progress at the granularity the tool produces (per token, per line, per record), not at a fake artificial cadence

• Keep a visible "stop" button for the entire stream so users can interrupt long tool calls

When not to use it. Tools that return instant or near-instant results (under 500 milliseconds). Streaming a sub-second result adds engineering complexity for no perceived benefit.

Accessibility notes. Streaming content can overwhelm screen readers if every chunk triggers a live region announcement. Use aria-live polite, batch announcements every second or two, and provide a "stop streaming" control accessible via keyboard.

5. Status badges with retry affordances, best for unreliable APIs and flaky integrations

Status badges with retry affordances are small UI elements attached to each tool call that show its current state (queued, running, succeeded, failed, retried) and provide a one-click action to re-run the call when it fails. They turn flaky tool execution from a dead end into a recoverable state.

The problem it solves is silent failure. Without status badges, a failed tool call often looks identical to a slow one. The agent moves on, the user does not realize anything went wrong, and the final answer is built on a missing piece. Badges and retry buttons make failure visible and recoverable.

Where it appears. Agent debugging surfaces (Anthropic Console, LangSmith, Braintrust), workflow agents that call external APIs (Linear AI, Granola, Zapier Agents), any agent that hits third-party SaaS with rate limits.

Real example. Anthropic Console attaches a colored status pill to every tool call (green, yellow, red) with the duration and a retry icon for failed calls. LangSmith does the same in its trace view. Linear AI shows a small warning chip on any tool call that hit a rate limit, with a "retry" link.

How to implement.

• Define a clear set of statuses (queued, running, succeeded, failed, retried, skipped) and render each with both color and icon

• Show duration on every call so users learn which tools are slow and budget accordingly

• Make retry a single click that re-runs from the failed call, preserving the rest of the agent state

• Distinguish retryable failures (timeouts, rate limits) from permanent ones (invalid arguments, missing permissions)

When not to use it. Pure local tools that cannot fail in interesting ways (a string-reverse function). The pattern is meaningful only when failure is a real possibility users care about.

Accessibility notes. Status must be conveyed in text (running, succeeded, failed), not color alone. Use aria-live polite to announce status transitions for screen reader users. Retry buttons need a clear label like "Retry web search" rather than a bare "Retry" icon.

6. Inline tool output rendering, best for rich data types (images, tables, files)

Inline tool output rendering is the pattern of rendering a tool's return value in its native visual form (an image as an image, a table as a table, a file as a download chip, a chart as a chart) instead of stringifying everything into a code block. It treats tool results as content, not as logs.

The problem it solves is the "wall of JSON" experience. When an image generation tool returns a URL, dumping the URL as text forces the user to right-click and open it. When a SQL tool returns 200 rows, dumping them as raw text makes them unscannable. Inline rendering turns each result into something the user can immediately consume.

Where it appears. Multimodal agents (Claude, ChatGPT, Gemini), data agents (any text-to-SQL tool, Hex Magic, Julius), research agents that fetch documents (Perplexity, Notion AI Q&A).

Real example. Claude renders image generation results as inline images, code blocks with syntax highlighting, and tables for tabular results. Perplexity renders fetched articles as preview cards with title, source, and snippet. Cursor renders edit_file results as inline diffs with a "view full file" link.

How to implement.

• Detect the result content type at the tool boundary (mime type, schema, sample inspection) and route to the right renderer

• Build a small library of renderers (image, table, code, chart, file chip, map) and let tools declare which renderer fits

• Provide a "view raw" toggle on every rich render so power users can inspect the underlying payload

• Keep the rendered preview bounded in height (300 to 500 pixels) with a "view all" expansion

When not to use it. Truly text-shaped results (a translated paragraph, a summary). Wrapping text in an unnecessary card adds visual weight without benefit.

Accessibility notes. Every rendered image needs alt text (use the agent's prompt or a vision model summary as a starting point). Tables need real th headers. Charts need an accessible data table fallback or a textual summary of the trend.

7. Tool call timeline view, best for multi-step agents and post-hoc debugging

A tool call timeline view is a dedicated UI surface that lists every tool call from a single agent run in chronological order, with timing, status, and click-through to the full payload. It complements the inline transcript with a bird's-eye view useful for debugging, billing, and audit.

The problem it solves is multi-step opacity. A 30-tool-call agent run buried inside a long chat transcript is impossible to audit. Did the agent hit the database four times? Did it search the web twice for the same query? The timeline answers in one scan.

Where it appears. Agent observability platforms (LangSmith, Braintrust, Helicone, Arize Phoenix), debug modes in agent IDEs (Cursor, Replit Agent, Claude Code), enterprise agent products with compliance requirements.

Real example. Anthropic Console shows a tool call timeline in its workbench, with each call as a horizontal bar sized by duration. LangSmith renders the same idea as a flame graph. Cursor surfaces a "history" panel listing every tool the agent called during the current task.

How to implement.

• Capture a structured event per tool call (start time, end time, tool name, status, token cost) at the agent runtime layer

• Render the timeline as a vertical list or a horizontal Gantt, depending on screen real estate

• Color-code by status and let users filter by tool name, status, or duration

• Link each timeline entry back to the inline transcript at the matching position

When not to use it. Single-call agents and consumer chat apps where users do not care about the underlying steps. The timeline is a power-user and operator surface.

Accessibility notes. A Gantt-style timeline is hard for keyboard navigation. Always provide a list-shaped alternative (a real ordered list of tool calls) that conveys the same information. Color coding needs a text label beside it.

How to choose the right AI tool call UI patterns for your product

1) How many tools does your agent expose?

If your agent exposes one or two tools, you can get away with simple inline rendering. As soon as the toolbox grows past five tools, you need named cards (pattern 1), collapsible panels (pattern 2), and a timeline view (pattern 7) to keep the experience scannable. Multi-tool agents that skip these patterns drown users in noise.

2) What is the blast radius of a wrong call?

If a wrong tool call costs the user real money, real data, or real reputation, pre-flight permission prompts (pattern 3) are non-negotiable. Read-only research agents can skip the gates. Coding agents that touch production, workflow agents that send emails, and database agents that write must always ask before they act.

3) How long does each tool take?

Tools that finish in under 500 milliseconds do not need streaming. Tools that take more than two seconds always do. Tools that take more than ten seconds need streaming plus a visible stop button plus a status badge with retry. Match the pattern to the wait.

4) Who is your operator?

If your product has a power user or an admin (an engineer debugging the agent, an ops lead auditing decisions), invest early in the timeline view (pattern 7) and the inline output rendering (pattern 6). Consumer-only products can keep these behind a "developer mode" toggle.

5) Scoring your patterns

Use this rubric to prioritize. Visibility = how much the pattern improves user understanding. Trust impact = how much it changes whether users delegate bigger tasks. Effort = engineering days to implement well. Score = (Visibility + Trust) / Effort.

If you have picked your tool call UI patterns but want a design partner to turn the AI-built output into a profitable, human-grade product (interfaces users actually trust, transcripts ops teams can audit, agent UIs that do not look templated), that is what AY Design does. We help founders and product teams ship AI agents that earn delegation by being legible. Book a design audit to see what to fix first.

FAQ

What is an AI tool call UI pattern?

An AI tool call UI pattern is a reusable design solution for surfacing the moment an AI agent invokes an external tool, function, or API in its interface. Tool call UI patterns cover how the call is announced, how arguments are rendered, how results are displayed, how failures are recovered, and how the user inspects or audits what the agent did.

Why do AI agents need a dedicated UI for tool calls?

AI agents need a dedicated UI for tool calls because tool calls are where the agent moves from "answering" to "acting", and acting has consequences. Without a visible, scannable tool call UI, users cannot tell if the agent read the right file, hit the correct API, or sent the email they expected. Dedicated UI converts hidden side effects into something users can verify and trust.

What is the difference between a tool call card and a chat bubble?

A tool call card is a structured UI block that represents a single function invocation with name, arguments, status, and result, while a chat bubble is an unstructured message from the agent. Tool call cards live inside the transcript but get a distinct visual treatment because they describe actions, not words. Most modern agent UIs interleave both shapes in a single scroll.

Should I show raw JSON in tool call results?

You should not show raw JSON as the default result rendering, but you should make it accessible behind a "view raw" toggle. Default to rich rendering (images, tables, file chips, charts) for non-engineers, and let power users inspect the underlying payload when debugging. Forcing JSON on everyone hurts trust and adoption.

How do I design tool call UIs that scale to 50+ steps?

To design tool call UIs that scale past 50 steps, lean on collapse by default, sticky filters, and a parallel timeline or flame-graph view. Anything that requires reading a 50-card transcript top-to-bottom will fail at scale. Pair a transcript view (linear, narrative) with a timeline view (overview, audit) so users can switch between depth and breadth.

Should tool call permission prompts auto-approve after a timeout?

No, permission prompts should never auto-approve after a timeout, because that defeats the entire point of a gate. The whole purpose of a pre-flight prompt is to require a deliberate human decision before an irreversible action. If you find your team wanting auto-approve, the right fix is offering a "trust this tool for this session" toggle on first approval, not a timer.

How do I make tool call UIs accessible to screen reader users?

Make tool call UIs accessible by using real headings for card titles, real buttons for disclosure toggles, and aria-live polite for status transitions and streaming output. Always convey status with text and icon, never color alone. Provide a list-shaped alternative for any timeline or flame-graph visualization, and make sure the safe default in every permission prompt is the initial focus.

Which AI products have the best tool call UI today?

Cursor, Anthropic Console, Claude, Replit Agent, and Perplexity have the strongest tool call UIs in 2026. Cursor leads on permission gates and inline diffs for coding agents, Anthropic Console leads on debugging timelines and status badges, Claude leads on streaming and rich result rendering, and Perplexity leads on inline citation cards for research workflows.