The Collaboration Model

In AI chat, users interact with both the assistant and any tool UIs it renders. Most tool UIs treat this as incidental — a tool UI appears, the user clicks, done. That undersells what's happening. The assistant, the tool UI, and the user form a collaborative triad.

The assistant gives context and narration. The tool UI gives structure that prose cannot — sortable tables, controls, media. They work together.

The assistant introduces the tool UI, the user scans it and asks a follow-up, the assistant answers by referencing specific rows. This is the triadic loop.

Roles

Every Tool UI has a job:

• Information — Display data. Users read more than they click. Examples: Data Table, Chart, Link Preview.

• Decision — For choices that matter (approve/reject, send/cancel). Show clear options and receipts that confirm what happened. Examples: Approval Card, Option List.

• Control — Adjust parameters without commitment (filters, sort orders, date ranges). Changes are reversible. Examples: Parameter Slider, Preferences Panel.

• State — Show internal activity (progress indicators, status logs, loading states). Examples: Progress Tracker, Terminal.

Some tool UIs combine roles. A data table with row actions is "information with control." When combining, pick one role to lead.

Constraints

Tool UIs live in chat: narrow widths, variable heights, mixed with prose.

• Vertical: Communicate purpose within the first 300px or so.
• Horizontal: Expect 400–600px. Prefer single-column layouts.
• Touch: Interactive elements need at least 44×44px tap area.
• Choices: Limit visible options to 5–7. The assistant can offer to show more.

Addressability

If the assistant can't point at something later, you lose half the value of rendering it.

• id: Identifies this specific tool UI in the conversation ("the preview above", "that table").
• assetId / row IDs / option IDs: Identify real objects ("that link", "row 4", "the merge option").

Use stable IDs from your backend — database IDs, canonical URLs — not array indexes or render-time UUIDs. Anything the user can act on should have an ID the assistant can cite.

Receipts

When a user takes an action with consequences, the tool UI should transition to a receipt — a read-only confirmation of what happened. This gives the user proof and the assistant something to cite later.

See the Receipts page for patterns and copy guidance.

Anti-Patterns

• Input fields: Input fields compete with the main chat composer. Ask whether the assistant could gather that information through conversation, or link to a form outside the chat.
• Hidden mutations: Actions that change state should show what happened. Terminal decisions need a receipt showing what the user chose.
• Kitchen sinks: If it needs tabs or navigation, consider breaking it into separate Tool UIs.
• Uncontextualized tool UIs: Always have the assistant introduce a tool UI and explain what it shows.
• Redundant narration: The assistant shouldn't describe what the tool UI already shows. The tool UI shouldn't echo what the assistant just said. If the assistant asks "Where to?", the tool UI doesn't need a header saying "Where to?" — just show the options. Divide the work between them: the assistant gives context, the tool UI gives structure.

Further reading

• Overview: What Tool UI is and how schema-first rendering works
• Actions: The local vs. decision action model in detail
• Receipts: How to show durable records of user decisions
• Gallery: Browse all available components