When to use

Whenever an agent calls a function and the user benefits from seeing what the call did. The block is more compact than a full chat reply and stays visually distinct from prose, so a thread of mixed text-plus-tool-calls remains scannable. For multi-step tool runs, pair this with agent-reasoning-ui above and agent-trace-ui below for the full lineage.

Running

In-progress invocation. tone="neutral" with a progress-ui indeterminate strip in the body. No action buttons until the call resolves.

{ "query": "claude opus tool use latency", "max_results": 5 }

Running…

Success

tone="accent" on resolution. Body shows the call args + a result preview (truncated when long). Secondary slot carries copy / open-in-new-tab actions.

Query

claude opus tool use latency

Results

5 sources, 482 ms

[ { "title": "Anthropic — Tool use latency", "url": "anthropic.com/news/…", "rank": 1 }, { "title": "Latency primer for agent loops", "url": "blog.…", "rank": 2 } ]

Error

tone="danger" with a clear next-step. The body carries the call args plus the error message in an alert-ui; secondary slot offers retry.

{ "invoice_id": "inv_8421", "format": "pdf" }

404 Not Found

No invoice with id inv_8421 in the last 90 days. Check the id or widen the date range.

Collapsed (default summary)

Default state inside a long thread — the agent has many tool calls and most don't need detail. Header carries the tool name + result count or status; body expands on click. Use collapsed attribute.

[ /* result list */ ]

{ "city": "San Francisco", "temp_f": 64, "condition": "fog" }

SELECT id, name, plan FROM users WHERE …

Composition rules

Always kind="TOOL" for the badge — distinguishes tool blocks from A2UI artifacts, tickets, notes, etc.
Tone tracks state — neutral while running, accent on success, danger on error. Don't use warning here; reserve that for soft warnings (rate-limit nearing, deprecated tool).
Title carries identity — function name first; for collapsed/summary forms, append · + result count or short status.
Body always shows args first in a code-ui block, then result. The reverse hides the call from the user; an agent thread is a contract, not an output stream.
Retry on error, not on success — error gets a Retry button in slot="secondary"; success gets Copy / Open. Don't double-up.

Agent Tool Call