The Collaboration Model

In AI chat, users interact with both the assistant and any tool UIs it renders. Most tool UIs treat this relationship as incidental: a tool UI appears, the user clicks something, done. We treat it as foundational. The assistant, the tool UI, and the user form a collaborative triad.

The assistant contextualizes, interprets, and narrates. The tool UI provides structure that prose cannot: sortable tables, precise controls, rich media. Neither replaces the other.

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 primary role:

• Information: Display data (tables, cards, charts). The focus is on comprehension rather than interaction.

• Decision: Capture consequential choices (approve/reject, send/cancel). These require clear options and receipts that prove what happened.

• Control: Adjust parameters without commitment (filters, sort orders, date ranges). Changes are reversible.

• State: Expose internal activity (progress indicators, status logs, loading states).

Some tool UIs combine roles. A data table with row actions is "information with control." When combining, the primary role should dominate.

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").

Prefer stable IDs derived from your backend (database IDs, canonical URLs) over array indexes or UUIDs generated at render time. When something can be acted on, it 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 state that confirms what happened. This gives the user proof and gives the assistant something to reference later.

The receipt shows what the user chose. The assistant's follow-up confirms the outcome and offers a way to reverse it.

Anti-Patterns

• Input fields: Input fields introduce dissonance by competing with the primary composer input. Reflect on whether it'd be more appropriate to capture that information through dialogue with the asssitant or, in rare cases, link to a dedicated form outside of or detached from the the chat context.
• Hidden mutations: Actions that change state should produce visible indication of what happened; terminal decisions should produce a receipt that reflects what choice the user made.
• 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, providing context that clarifies what's being shown.
• Redundant narration: The assistant shouldn't describe what the tool UI already shows. Conversely, 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: the assistant provides context, the tool UI provides structure.