# Tool call

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tool-call
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=601-225

```tsx
import { ToolCall } from '@commenda/pathfinder/tool-call';

<ToolCall
  name="list_entities"
  status="done"
  meta="2 of 5 have a UK filing"
  output={{ code: '{"count":2}', language: 'json' }}
/>;
```


## Usage [#usage]

```tsx
import { ToolCall } from '@commenda/pathfinder/tool-call';

<ToolCall
  name="list_entities"
  status="done"
  meta="2 of 5 have a UK filing"
  output={{ code: '{"count":2}', language: 'json' }}
/>;
```

## Live activity [#live-activity]


```tsx
import { ToolCall } from '@commenda/pathfinder/tool-call';

<ToolCall
  name="list_entities"
  status="done"
  meta="2 of 5 have a UK filing"
  output={{ code: '{"count":2}', language: 'json' }}
/>;
```


Use Start/Finish activity to exercise streaming updates. New run resets disclosure intent.

## Failure and recovery [#failure-and-recovery]


```tsx
<ToolCall
  name="get_calendar"
  status="failed"
  error="Request timed out."
  input={{ code: '{"jurisdiction":"UK"}', language: 'json' }}
/>;
```


A failure retains the tool glyph and exposes its error outside the disclosure. Retrying belongs to the application: update the same stable tool step to running while preserving the payload disclosure. Use input and output together to show Request and Response CodeBlocks.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `name` | `string` | required | Required machine tool name, such as `list_entities` |
| `status` | `"pending" \| "running" \| "done" \| "failed"` | required | Required execution state |
| `label` | `string` | optional | Overrides automatic English tense/localizes the row |
| `meta` | `string` | optional | Optional inline metadata and supporting copy |
| `description` | `string` | optional | Optional inline metadata and supporting copy |
| `error` | `string` | optional | Visible failure detail outside the collapsed payload |
| `input` | `ToolCallPayload` | optional | Complete pre-serialized, redacted payload; language defaults to text |
| `output` | `ToolCallPayload` | optional | Complete pre-serialized, redacted payload; language defaults to text |
| `disclosureConfig` | `ActivityDisclosureConfig` | optional | Payload starts closed and remains independent of execution |
| `className` | `string` | optional | Layout override |

### input fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes | Complete, pre-serialized text. Redaction and safe serialization belong to the host. |
| `language` | `string` | No |  |
| `filename` | `string` | No |  |

### output fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes | Complete, pre-serialized text. Redaction and safe serialization belong to the host. |
| `language` | `string` | No |  |
| `filename` | `string` | No |  |

### disclosureConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | No |  |
| `defaultOpen` | `boolean` | No |  |
| `onOpenChange` | `((open: boolean) => void)` | No |  |

## Design rules [#design-rules]

- **TOOLCALL-01:** Figma 600:180: Label12 pearl800 with a 12px tool glyph and 6px gap. Failure retains the tool glyph and adds a red800 “Failed to” prefix.
- **TOOLCALL-02:** Only payload-bearing rows are disclosure buttons. The chevron is 12px and payload CodeBlocks are indented 18px; complete code scrolls horizontally.
- **TOOLCALL-03:** The host executes and retries tools, serializes values, and removes secrets. The component never executes tools or parses payloads. Errors remain visible when collapsed.
- **TOOLCALL-04:** Name verbs follow Figma: list → check, get → look up; search/create/update/add/set/remove/post/assign retain their verbs. Unknown verbs use run. Override label for localized/domain copy. Disclosure is independent of lifecycle.

## Accessibility and integration [#accessibility-and-integration]

Disclosure buttons support Enter and Space, preserve focus, and expose `aria-expanded`. Payload copy buttons are outside the disclosure trigger. Pointer disclosure uses the existing 200ms height transition; keyboard and reduced-motion interaction are immediate. Long text wraps while code scrolls inside its own region. Use one meaningful ThinkingIndicator status per active response rather than announcing every streamed token or tool payload.

The application owns requests, cancellation, approval, retries, durations, and history persistence. No AI SDK provider is required. See [AI content integration](/docs/guides/ai-content) for migration mappings; consumer migration is outside this phase.