Skip to Content
kindui

Tool

Show a tool call from its streamed input to its output or error.

Use a tool for each tool call the model makes. Its header shows the tool's name and status, and its content holds the input, then the output or the error.

InputPartial
{  "filter": "client"}
InputPartial
{  "branch": "old-retry"}
Waiting for approval
Press search_docs, or focus it and press Enter or Space, to see what the search returned.

Installation

npx shadcn@latest add @kind-ui/tool

Composition

Tool
├── ToolTrigger
│   ├── ToolIcon
│   └── ToolTitle
├── ToolContent
│   ├── ToolInput
│   │   └── ToolInputCopy
│   ├── ToolOutput
│   │   └── ToolOutputCopy
│   └── ToolError
└── ToolApproval

Tool renders these parts when you pass no children; any children you pass replace them. The trigger is a native button that shows or hides the content. ToolTitle shows the tool's name, ToolInput and ToolOutput the values as a Code Block or Markdown, and ToolError the error. ToolApproval renders a Confirmation while the call has an approval, after the content, so it shows while the tool is closed. Each takes its own children instead.

Usage

Tool Calls

Pass the call as call and update it as the host does. With the AI SDK, fromUIMessagePart maps each tool part to a step whose call and error you pass on. Key each tool by its toolCallId: updating one call never closes another tool or clears its copied state.

<Tool key={step.id} call={step.call} error={step.error} />

The status comes from the call. An error outcome is error, a denied or cancelled one is cancelled, an approval that's waiting is awaiting-input, final output is complete, and anything else is running. Pass status to set it yourself.

Input and Output

The input shows as JSON, labeled Partial while it streams. Output appears once the call has some: text renders as Markdown, and any other value as JSON, so 0, false, "" and null show as themselves. Output that may still change is labeled Preliminary. JSON longer than its block scrolls inside it, and nothing above a value moves while it streams.

Each has a copy button, shown once there's a value, that copies it as shown, checks for 2 seconds and announces "Copied". The buttons and code blocks are named after the tool, like "Copy search_docs input" and "search_docs input", so people and agents can tell two tools apart. Pass highlight to color both, as Code Block's does.

Approvals and Errors

While the call has an approval, the tool shows a Confirmation named after it, like "Run search_docs?". Pass onApprove and onDeny to offer Approve and Deny; each is called with the approval's approvalId and generation, and approvalReason adds a box for the reason Deny sends. toApprovalResponse comes from the AI SDK adapter. Without them, it shows where the approval stands, like "Waiting for approval". Once the decision is recorded, the outcome stays, like "Approved". When a choice goes away with focus, focus moves to the tool's trigger.

<Tool
  call={step.call}
  onApprove={() => addToolApprovalResponse(toApprovalResponse(step.call.approval, { approved: true }))}
  onDeny={({ reason }) =>
    addToolApprovalResponse(toApprovalResponse(step.call.approval, { approved: false, reason }))
  }
/>

The tool's status stays awaiting-input until the decision is recorded, even when it wasn't sent.

When the status is error, the content shows error.message, or "The tool failed." without one.

Opening and Closing

A tool opens while it runs or waits for approval, closes into its header when it completes, and stays open when it fails. Once someone opens or closes it, it stays as they left it. Screen readers hear the tool's name and its outcome, like "search_docs complete", when it needs input, completes, fails or is cancelled, and "search_docs denied" when its approval is denied. The confirmation announces the decision itself, like "Approved", and "Decision not sent" when it fails.

Motion

The content grows open and shut. Under prefers-reduced-motion, or with motion="reduced", it fades over 120 ms instead and the title holds still, and with motion="none" it changes at once.

API Reference

Prop

Type

Agent

An agent connected with createAgent finds a tool by its name and reads its open and status. It can run these actions, and press the trigger like a person would. copyInput and copyOutput are listed only while there's a value to copy.

Prop

Type

Runs in React and Web Components. On <kind-tool>, call, error and highlight are properties only, other props are kebab-case attributes, and onOpenChange fires openchange. Approve and Deny need the can-approve and can-deny attributes and fire approve and deny on the tool, as Confirmation's do. The element fills in its parts when it has no children, and an empty <kind-tool-input> or <kind-tool-output> with its heading, copy button and code block, writes its title and error into those parts while they're empty, and writes the input and output into the <kind-code-block> and <kind-markdown> inside them.