# Tool call

One tool call as a compact row: what it did in plain words, its status, and how long it took. Expands to the input and output. A failed call opens by default and leads with its error. A call that finishes while on screen draws its tick or cross; one that arrives finished is drawn still.

- Registry name: `tool-call` (`@candor/tool-call`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/tool-call

## Install

```bash
npx candor-ui add tool-call
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/tool-call`.
It brings in: chat, collapsible, locale, payload, status, step-list, streaming-text, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { ToolCallGroup } from "@/components/tool-call"

export default function Example() {
  return (
    <ToolCallGroup
      className="max-w-lg"
      calls={[
        { id: "1", tool: "orders.lookup", title: "Looked up order #4821", status: "succeeded", duration: "0.4s", input: '{ "id": 4821 }', output: '{ "status": "shipped" }', outputLanguage: "json" },
        { id: "2", tool: "carrier.track", title: "Checked the carrier", status: "running" },
        { id: "3", tool: "email.send", title: "Emailed the tracking link", status: "failed", error: "The mail service refused the address." },
      ]}
    />
  )
}
```

## <ToolCall>

Props:

- `call: ToolCallData`: The call: tool name, plain-words title, status, input, output, duration or error.
- `className?: string | undefined`

## <ToolCallGroup>

A run of tool calls, with a count when it's long enough to fold.

Props:

- `calls: ToolCallData[]`: Several calls, summarised as a group.
- `className?: string | undefined`

## Strings (`toolCall`)

The fixed words, English by default. Override any of them under `toolCall` in `<LocaleProvider strings={{ toolCall: { … } }}>`; the table is exported as `toolCallStrings`.

- `input`: Input
- `output`: Output
- `calls`: { one: "{count} tool call", other: "{count} tool calls" }
- `done`: {count} done
- `failed`: {count} failed
- `working`: working
- `approvedAutomatically`: Approved automatically
- `approvedByPerson`: Approved by a person
- `editedBeforeRun`: Edited before it ran
- `editedNote`: A person changed the input before allowing it. Input is what ran.
- `proposed`: As the agent proposed it

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.