UX Patterns Guide
UI + UX AI And Automation UX emerging

Tool-use visibility

Expose tool use as structured, permission-aware, redacted, and inspectable cards or detail panels that show tool purpose, inputs, outputs, status, permissions, side effects, failures, and links to progress trace, approval gates, source evidence, and audit records.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • An AI agent or automation calls tools, functions, APIs, retrieval systems, commands, or integrations.
  • Users need to understand what data was accessed, what payload was sent, what output returned, or what side effect occurred.
  • Permission, privacy, safety, failure recovery, debugging, compliance, or trust depends on tool-call inspection.
  • The product can expose safe summaries and role-gated details without leaking sensitive internals.

Avoid when

  • The system cannot reliably identify tool calls, inputs, outputs, status, permissions, or side effects.
  • Users only need the high-level run sequence, which belongs to agent progress trace.
  • The task is claim-level evidence inspection or answer-wide grounding rather than tool details.
  • Raw payload disclosure would be unsafe and no safe summary can be generated.
  • Users only need retained after-the-fact evidence in an activity log.

Problem it prevents

AI agents can call tools, retrieve data, run code, update records, send messages, or trigger integrations, but users often see only a friendly progress message or final answer and cannot tell what was accessed, what changed, what failed, or which permissions and payloads were involved.

Pattern anatomy

What a strong implementation has to make clear

User need

The system can call functions, tools, APIs, retrieval systems, file search, web search, shell commands, data connectors, messaging services, payment systems, workflow actions, or enterprise integrations.

Pattern promise

Expose tool use as structured, permission-aware, redacted, and inspectable cards or detail panels that show tool purpose, inputs, outputs, status, permissions, side effects, failures, and links to progress trace, approval gates, source evidence, and audit records.

Required state

Pending tool call state with tool name, purpose, requested permission, and side-effect risk.

Recovery path

Users cannot tell which tool ran or what data it accessed.

Access contract

Expose tool name, status, permission, risk, input summary, output summary, and redaction reason as text.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A research agent shows Knowledge search, Web search, and CRM lookup tool cards with purpose, input summary, source scope, output summary, status, and redacted raw request details.
  • A support agent pauses before a refund tool call, shows the amount, customer, permission scope, side-effect warning, and approval requirement before execution.
  • A user opens the active CRM lookup, sees it is read-only, verifies the account ID, and continues watching the run.
  • A reviewer sees a send-email tool call is permission-limited and opens the human approval gate before it can run.
Weak implementation

Vague, hidden, hard to recover from

  • A trace says Using tools but never names the tool, input, source, output, permission, or side effect.
  • The UI dumps raw JSON containing secrets and internal system prompts as the only explanation of tool use.
  • Users cannot tell whether the agent searched the web, read private files, or changed customer data.
  • A tool card says Success even though the returned data was partially redacted or stale.
UI guidance
  • Render tool-use visibility as an inspectable tool-call surface with tool name, purpose, input summary, output summary, permission scope, data source, side-effect risk, status, timestamps, and redaction state.
  • Separate safe summaries from sensitive raw payloads so users can understand what the agent is doing without exposing secrets, private records, hidden prompts, or implementation-only events.
UX guidance
  • Use tool-use visibility when users need to understand, verify, approve, debug, or audit how an AI agent used tools, data, or integrations during a run.
  • Keep the display actionable: show pending, running, succeeded, failed, denied, redacted, permission-limited, rate-limited, retried, and side-effect states with clear controls to open details, grant permission, retry, cancel, report, or view audit where appropriate.
Implementation contract

What the implementation must handle

States

  • Pending tool call state with tool name, purpose, requested permission, and side-effect risk.
  • Running tool call state with elapsed time, cancellability, and current operation summary.
  • Succeeded tool call state with output summary, returned object count, source or target, and safe details.
  • Failed, timed out, rate-limited, offline, denied, and retried tool call states.

Interaction

  • Each tool-use item identifies one tool call or tool-call attempt with stable call ID, run ID, step ID, tool name, status, timestamp, and permission scope.
  • Input summary, output summary, raw request, raw response, source excerpts, target objects, and side effects are distinct fields with separate visibility rules.
  • Users can tell whether a tool is pending, running, succeeded, failed, denied, redacted, retrying, skipped, approval-waiting, or complete.
  • Opening details reveals task-relevant payload information without leaking secrets, hidden prompts, credentials, private data, or irrelevant low-level logs.

Accessibility

  • Expose tool name, status, permission, risk, input summary, output summary, and redaction reason as text.
  • Do not rely on color, icons, animation, indentation, or raw code formatting alone for pending, running, succeeded, failed, denied, redacted, or side-effect states.
  • Make expand details, retry, cancel, grant permission, open gate, copy tool ID, open source, open target, and view audit controls keyboard reachable.
  • Announce meaningful tool status changes such as tool started, permission denied, output redacted, retry started, tool failed, or side effect executed.

Review

  • Which exact tool call, attempt, run, step, permission scope, and target object is visible?
  • Can users see safe input summary, output summary, status, redaction reason, and side-effect risk without raw payload leakage?
  • Which tool details are hidden, truncated, permission-limited, or role-gated, and why?
  • What happens when a tool call fails, times out, is denied, is retried, or creates a side effect?
Interactive lab

Inspect the states before you copy the pattern

Inspect an AI tool call safely

Inspect pending tool call, running tool call, succeeded tool call, failed tool call, denied permission, redacted input, redacted output, raw payload gated, side-effect preview, side-effect executed, retry attempt, stale result, duplicate tool event, mobile tool card, and compare vague-tools, raw-secret-dump, false-success, hidden-side-effect, unsafe-retry, missing-redaction, and audit-disconnect failures.

Tool-use visibility
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Pending tool call state with tool name, purpose, requested permission, and side-effect risk.

Keyboard / Access

Tab reaches tool summary cards, expand controls, detail sections, recovery actions, and audit links in predictable order.

Avoid Generating

Showing a vague Using tools label without names, inputs, outputs, or permissions.
Evidence trail

Source-backed claims behind this guidance

OpenAI File search guide

OpenAI - checked

Supports file-search tool outputs and annotations that may need source-aware inspection.

OpenAI Web search guide

OpenAI - checked

Supports web-search tool outputs and citation annotations that may need source-aware inspection.

Full agent/debug reference

Problem Context

  • The system can call functions, tools, APIs, retrieval systems, file search, web search, shell commands, data connectors, messaging services, payment systems, workflow actions, or enterprise integrations.
  • Tool calls may include sensitive inputs, hidden prompts, private records, credentials, user files, source excerpts, customer data, side effects, rate limits, failed outputs, or partial results.
  • Users may need tool visibility before allowing a risky call, during execution to debug a run, after completion to verify evidence, or during review to understand what the agent actually did.
  • The same tool call may need different levels of disclosure for end users, admins, reviewers, support, developers, and auditors.
  • Tool-use visibility often appears inside an agent progress trace, approval gate, source grounding panel, chat transcript, code task, or activity log.

Selection Rules

  • Choose tool-use visibility when users need to inspect exact tool names, purposes, inputs, outputs, permissions, side effects, failures, or redactions.
  • Use agent progress trace when users need the run-level sequence of steps; link from the trace to tool-use visibility for detailed tool inspection.
  • Use source grounding display when the task is answer-wide evidence coverage, not individual tool-call payloads.
  • Use citation display when the task is claim-level source verification rather than inspecting a tool execution.
  • Use human approval gate when a tool call is paused for authorization; keep tool-use visibility responsible for showing what the tool will receive and return.
  • Use activity log when users need retained evidence after the run rather than live or contextual tool details.
  • Expose safe input summary, output summary, permission scope, target object, side-effect risk, status, and redaction reason before exposing raw payloads.
  • Show raw request, raw response, stack trace, full command output, or hidden diagnostic detail only to eligible users and only when useful for the task.
  • Do not hide tool failures, denied permissions, stale results, partial output, or redacted data behind a plain success label.
  • Do not present tool-use visibility as proof of correctness; pair it with citations, grounding, confidence, approval, or audit surfaces when those are the real decision inputs.

Required States

  • Pending tool call state with tool name, purpose, requested permission, and side-effect risk.
  • Running tool call state with elapsed time, cancellability, and current operation summary.
  • Succeeded tool call state with output summary, returned object count, source or target, and safe details.
  • Failed, timed out, rate-limited, offline, denied, and retried tool call states.
  • Permission-limited, blocked, approval-required, and human-gated tool call states.
  • Redacted input, redacted output, hidden raw payload, and eligible raw payload states.
  • Side-effect preview, side-effect executed, side-effect skipped, and rollback or compensation states.
  • Multiple tool calls, parallel tool calls, duplicate tool events, and stale tool result states.
  • Mobile compact tool card state that preserves tool name, status, permission, risk, and details access.

Interaction Contract

  • Each tool-use item identifies one tool call or tool-call attempt with stable call ID, run ID, step ID, tool name, status, timestamp, and permission scope.
  • Input summary, output summary, raw request, raw response, source excerpts, target objects, and side effects are distinct fields with separate visibility rules.
  • Users can tell whether a tool is pending, running, succeeded, failed, denied, redacted, retrying, skipped, approval-waiting, or complete.
  • Opening details reveals task-relevant payload information without leaking secrets, hidden prompts, credentials, private data, or irrelevant low-level logs.
  • Retry, cancel, grant permission, open gate, report issue, copy tool ID, open source, open target, and view audit actions appear only when allowed by tool state and role.
  • Tool outputs used in generated answers remain linked to citations or grounding where claims depend on them.
  • Redaction explains whether content is hidden by permission, privacy, safety, policy, retention, or technical truncation.
  • After completion, failed or side-effecting tool calls remain inspectable and link to durable audit or activity records where needed.

Implementation Checklist

  • Model tool call ID, attempt number, run ID, step ID, tool name, purpose, input summary, output summary, raw payload availability, permission scope, target object, side-effect type, status, timestamps, redaction reason, and audit link as structured data.
  • Separate tool-use records from progress trace milestones, source grounding results, citation markers, approval decisions, raw telemetry, and activity log records.
  • Render compact tool cards with expand-to-details, safe summaries, status labels, permission labels, risk labels, and role-gated raw payload access.
  • Add states and actions for pending, running, success, failure, retry, cancel, grant permission, open approval gate, report mismatch, copy tool ID, open source, open target, and view audit.
  • Apply redaction and truncation before rendering or copying tool inputs and outputs.
  • Connect tool outputs to generated content, source grounding, citations, final artifacts, and audit records when those outputs affect user-facing results.
  • Throttle live updates and avoid announcing every low-level tool delta.
  • Test hidden tool calls, permission-denied tools, redacted payloads, stale results, failed tool output, side effects, parallel tools, duplicate attempts, long file paths, mobile wrapping, keyboard details, and screen-reader status changes.

Common Generated-UI Mistakes

  • Showing a vague Using tools label without names, inputs, outputs, or permissions.
  • Dumping raw JSON, stack traces, tokens, secrets, or hidden prompts as the user-facing tool view.
  • Showing tool success when returned data was partial, stale, redacted, or unused.
  • Hiding a side-effecting tool call until after it already changed data or sent a message.
  • Merging all tool calls into one progress step so users cannot inspect which tool failed.
  • Letting users retry a side-effecting tool without showing idempotency, target, or duplicate risk.
  • Treating tool-use visibility as citation, grounding, approval, or audit evidence when those need their own surfaces.
  • Removing failed or denied tool details before users can debug or appeal.

Critique Questions

  • Which exact tool call, attempt, run, step, permission scope, and target object is visible?
  • Can users see safe input summary, output summary, status, redaction reason, and side-effect risk without raw payload leakage?
  • Which tool details are hidden, truncated, permission-limited, or role-gated, and why?
  • What happens when a tool call fails, times out, is denied, is retried, or creates a side effect?
  • How do tool outputs connect to generated claims, citations, grounding, final artifacts, and audit records?
  • Would agent progress trace, source grounding display, citation display, human approval gate, or activity log better fit the actual task?
Accessibility
  • Expose tool name, status, permission, risk, input summary, output summary, and redaction reason as text.
  • Do not rely on color, icons, animation, indentation, or raw code formatting alone for pending, running, succeeded, failed, denied, redacted, or side-effect states.
  • Make expand details, retry, cancel, grant permission, open gate, copy tool ID, open source, open target, and view audit controls keyboard reachable.
  • Announce meaningful tool status changes such as tool started, permission denied, output redacted, retry started, tool failed, or side effect executed.
  • Keep focus stable when live tool events append or details load.
  • Ensure long tool names, file paths, JSON keys, error text, and redaction explanations wrap at mobile widths and high zoom.
Keyboard Behavior
  • Tab reaches tool summary cards, expand controls, detail sections, recovery actions, and audit links in predictable order.
  • Enter or Space expands details, starts retry, cancels, opens gate, grants permission, copies tool ID, or opens target according to native control behavior.
  • Escape closes layered raw-detail or payload panels and returns focus to the invoking tool card.
  • New tool status events do not steal focus from the selected card or action.
  • After retry, failure, permission grant, or approval handoff, focus remains near the affected tool status.
  • Keyboard users can move from a generated claim to the tool output that produced it and back when that relationship exists.
Variants
  • Tool call card
  • Function call inspector
  • Command execution details
  • Retrieval tool details
  • Web search tool visibility
  • File search tool visibility
  • API connector tool visibility
  • Permission-gated tool detail
  • Side-effecting tool preview
  • Mobile tool-use sheet

Verification

Last verified: