Tool-use visibility

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?