## 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.

## See also

- agent-artifact-ui — the underlying component.
- agent-reasoning-ui — pair above for "why I called this tool".
- agent-trace-ui — pair below for the full execution trace.
- adia-chat — host surface for tool-call blocks in a thread.