# Tool (/docs/agent-ui/components/tool)

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.

<Example caption="Press search_docs, or focus it and press Enter or Space, to see what the search returned.">
<i />

```tsx
import { fromUIMessagePart } from "@kind-ui/agent-ui/adapters/ai-sdk";
import { Tool } from "@/components/ui/tool";

const parts = [
  {
    type: "tool-search_docs",
    toolCallId: "call_1",
    state: "output-available",
    input: { query: "retry with backoff" },
    output: { hits: 3, top: "guides/retries.md" },
  },
  {
    type: "tool-run_tests",
    toolCallId: "call_2",
    state: "input-available",
    input: { filter: "client" },
  },
  {
    type: "tool-delete_branch",
    toolCallId: "call_3",
    state: "approval-requested",
    input: { branch: "old-retry" },
    approval: { id: "approval_1" },
  },
  {
    type: "tool-fetch_url",
    toolCallId: "call_4",
    state: "output-error",
    input: { url: "https://example.com/status" },
    errorText: "Request timed out after 30 s.",
  },
] as const;

export default function ToolExample() {
  return (
    <div className="flex flex-col gap-1">
      {parts.map((part, index) => {
        const mapped = fromUIMessagePart(part, { messageId: "message_1", index });
        if (mapped?.type !== "step" || mapped.step.kind !== "tool") return null;
        const { step } = mapped;
        return <Tool key={step.id} call={step.call} error={step.error} />;
      })}
    </div>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/tool
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/tool-web
```

## Composition [#composition]

```text
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](./code-block.mdx) or [Markdown](./markdown.mdx), and `ToolError` the error. `ToolApproval` renders a [Confirmation](./confirmation.mdx) while the call has an approval, after the content, so it shows while the tool is closed. Each takes its own children instead.

## Usage [#usage]

### Tool Calls [#tool-calls]

Pass the call as `call` and update it as the host does. With the [AI SDK](../adapters/ai-sdk.mdx), `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.

```tsx
<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 [#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 [#approvals-and-errors]

While the call has an approval, the tool shows a [Confirmation](./confirmation.mdx) 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](../adapters/ai-sdk.mdx). 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.

```tsx
<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 [#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 [#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 [#api-reference]

### ToolOptions

| Prop               | Type                                                                                   | Description                                                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind?`            | `string \| undefined`                                                                  | Written as `data-kind`, for styling by step type.                                                                                                                                              |
| `open?`            | `boolean \| undefined`                                                                 | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                |
| `defaultOpen?`     | `boolean \| undefined`                                                                 | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                |
| `onOpenChange?`    | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined` | Called when the step opens or closes, with what caused it.                                                                                                                                     |
| `autoOpen?`        | `"never" \| "running"`                                                                 | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"` |
| `durationSeconds?` | `number \| undefined`                                                                  | Written as `--kind-step-duration`.                                                                                                                                                             |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                   |
| `call?`            | `ToolCall \| undefined`                                                                | The call to show, from the host. Update it as its input streams, its approval moves and its output arrives.                                                                                    |
| `status?`          | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`   | Defaults to the call's: `error`, `cancelled`, `awaiting-input`, `complete` or `running`, as `toolStatus` reads it.                                                                             |
| `label?`           | `string \| undefined`                                                                  | Replaces the title, which is the tool's name, and names the tool in announcements and in its copy buttons and code blocks ("<label> input"), so keep it a name.                                |
| `error?`           | `{ message: string; } \| undefined`                                                    | What went wrong, shown while the status is `error`. Without it, the tool shows "The tool failed."                                                                                              |
| `highlight?`       | `Highlight \| undefined`                                                               | Colors the input and output code, as Code Block's `highlight` does.                                                                                                                            |
| `onApprove?`       | `ConfirmationCallback \| undefined`                                                    | Called when the call's approval is approved, with its `approvalId` and `generation`. Shows Approve while set.                                                                                  |
| `onDeny?`          | `ConfirmationCallback \| undefined`                                                    | Called when the call's approval is denied, with its `approvalId`, `generation` and reason. Shows Deny while set.                                                                               |
| `approvalReason?`  | `boolean \| undefined`                                                                 | Shows a box for the reason Deny sends, as Confirmation's `reason` does. Default: `false`                                                                                                       |

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

### ToolAgentActions

| Prop         | Type                                    | Description                                                                                                         |
| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `expand`     | `() => boolean`                         | Opens the step. Returns whether the change was accepted.                                                            |
| `collapse`   | `() => boolean`                         | Closes the step. Returns whether the change was accepted.                                                           |
| `copyInput`  | `(() => Promise<boolean>) \| undefined` | Copies the input as shown, and resolves with whether the clipboard write went through. Only while there is input.   |
| `copyOutput` | `(() => Promise<boolean>) \| undefined` | Copies the output as shown, and resolves with whether the clipboard write went through. Only while there is output. |

<Caption>
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.
</Caption>