Tool

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add tool

Usage#

import {
  Tool,
  ToolHeader,
  ToolIcon,
  ToolName,
  ToolSummary,
  ToolMeta,
  ToolStatus,
  ToolContent,
  ToolInput,
  ToolOutput,
  ToolApproval,
  ToolApprovalMessage,
  ToolApprovalActions,
} from "@/components/ui/tool"

export function Example({ call }) {
  return (
    <Tool status={call.status}>
      <ToolHeader>
        <ToolIcon><MagnifyingGlass weight="bold" /></ToolIcon>
        <ToolName>Searched the web</ToolName>
        <ToolSummary>{call.input.query}</ToolSummary>
        <ToolMeta>{call.duration}</ToolMeta>
      </ToolHeader>
      <ToolContent>
        <ToolInput value={call.input} />
        <ToolOutput value={call.output ?? call.error} />
      </ToolContent>
    </Tool>
  )
}

Anatomy#

Three blocks. A header line that is also the disclosure: the status column, the name, a summary of the arguments and a meta read-out. The content it opens: an input sheet and an output sheet. And an approval row that exists only while the call is waiting for a person.

import {
  Tool,
  ToolHeader,
  ToolIcon,
  ToolName,
  ToolSummary,
  ToolStatus,
  ToolMeta,
  ToolContent,
  ToolInput,
  ToolOutput,
  ToolApproval,
  ToolApprovalMessage,
  ToolApprovalActions,
} from "@/components/ui/tool"

<Tool>
  <ToolHeader>
    <ToolIcon />
    <ToolName />
    <ToolSummary />
    <ToolStatus />
    <ToolMeta />
  </ToolHeader>
  <ToolContent>
    <ToolInput />
    <ToolOutput />
  </ToolContent>
  <ToolApproval>
    <ToolApprovalMessage />
    <ToolApprovalActions />
  </ToolApproval>
</Tool>

States#

Six states, one per stage an agent SDK reports. They live in the 16px column at the head of the line: the tool's own glyph at rest (at half strength while the model is still writing the arguments), a spinner while it runs, a warning when it threw, a prohibit sign when someone turned it down. While pending or running, the name carries the same ink sweep as Chat's “Thinking…”. A finished call gets no green tick: a column of checks says nothing a finished line doesn't.

Status chip#

ToolStatus is an optional Badge worded and toned from the root's status, so a label and a state can never drift apart. Leave it out in a chat, where the status column already says it; reach for it in an audit log or an activity feed, where each call has to announce itself.

Input and output#

Pass the arguments and the result as they come from your SDK. An object is pretty-printed and highlighted as JSON, with copy on hover; a string is shown as plain text, so a shell's stdout keeps its own layout. A long JSON result clamps at 200px behind a Show more, so a 400-line response never unrolls at whoever opens the call.

{
  "command": "pnpm test auth",
  "cwd": "apps/web"
}

✓ session.test.ts (6)
✓ reset.test.ts (4)

Test Files  2 passed (2)
     Tests  10 passed (10)

Errors#

Mark the call error and the output sheet reads its value as the message: labelled “Error”, in the destructive ink, wrapped rather than scrolled sideways, and announced as an alert. Nothing else on the card turns red; the warning in the status column is enough to find it in a list.

{
  "table": "orders",
  "range": "30d"
}

Approval#

A call that needs a person mounts open, so you never have to expand a card to learn what you are being asked to allow, and ToolApproval sits outside the collapsible content, so the decision can't be folded away. It renders nothing in any other status: leave it in the markup and let the status decide. The pair is the house rule, ghost on the left and primary on the right.

{
  "paths": [
    "drafts/q3-pricing-v1.md",
    "drafts/q3-pricing-v2.md",
    "drafts/q3-pricing-old.md"
  ]
}

Editing the arguments#

ToolInput editable turns the same sheet into an editor: no new field, no frame, the same mono type, so nothing moves until you type. Pass the raw text back as value, validate it yourself and set invalid while it does not parse; this demo holds Send back until the JSON is valid again.

{
  "to": "dana@northwind.co",
  "subject": "Your Q3 renewal",
  "body": "Hi Dana, your Team plan renews on 1 October at $79 per seat."
}

In a chat#

Inside a Chat turn or an AI Panel, use variant="plain". It drops the frame, so the calls read as a few quiet lines of the answer rather than as cards inside a card, and the sheets indent to the name's axis when opened.

Density#

Like Card and Plan, Tool reads the density context (or a density prop). It tunes the header band (44px or 40px) and the sheets' padding; the labels move with the code so “Input” always starts on the listing's left edge. The 8px gutter between frame and sheet is fixed in both, because it is what keeps the sheet's corner concentric with the frame's.

{
  "path": "pricing/q3-final.md"
}

{
  "path": "pricing/q3-final.md"
}

API reference#

FAQ#