Skip to content

Tool

A tool call, from its arguments to its result, as an expandable line.

Input
Press C to copy a value, or P to copy its path.
Output
Press C to copy a value, or P to copy its path.
Running: Fetching example.com/pricing

Installation

  1. Add the registryOnce per project
  2. Add tool

Usage

A tool call is a Trace line, so it goes in a Trace beside the other steps. ToolIcon, ToolTitle and ToolDescription are the line's Trace parts. The line expands only when a ToolContent is a direct child of Tool. Set expandable when the content is inside a fragment or a component of your own.

state sets the line's status from the call's progress: pending before it starts, running while it runs, approval-requested while it waits for someone to allow it, then done, error or denied. The color and motion aren't announced, so say the state in the title too, as in "Running" and "Ran".

ToolIcon follows the call's state. It shows a Spinner while the call runs, and a cross or a slashed circle once it has failed or been denied. Otherwise it shows its children, usually the tool's icon. Without children, it shows a check once the call is done and a dashed circle before then. Screen readers announce the state instead, as "Running", "Failed" and so on, before the title. ToolIcon's label changes that text.

ToolInput and ToolOutput render objects, arrays and JSON strings in a JSON Viewer, and other strings in a Code Block. Pass props to either one with jsonViewerProps and codeBlockProps, such as the code's language.

With an AI library

The tool-call parts from the AI SDK and TanStack AI each have their own state, which maps onto Tool's. The Chat guide has each mapping as a function.

Composition

Examples

Failed

Put the error in a ToolError once a call fails.

Input
Press C to copy a value, or P to copy its path.
DNS query timed out after 5 seconds.

Needs approval

ToolApproval asks someone to allow the call while its state is approval-requested. It hides once the state changes and returns focus to the line. Return a promise from onApprove or onDeny to keep that button pending and the other one disabled until the promise settles. This example does that while it sends the response.

Needs approval: Run pnpm db:migrate
Run the migration on the production database?

Props

Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.

Tool

ToolTrigger

ToolIcon

ToolTitle

ToolDescription

ToolContent

ToolInput

ToolOutput

ToolError

ToolApproval