Tool call
A compact tool lifecycle row with optional request and response payloads.
{"jurisdiction":"UK"}
{
"count": 2,
"jurisdiction": "UK"
}
Usage
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
{"jurisdiction":"UK"}
{
"count": 2,
"jurisdiction": "UK"
}
Use Start/Finish activity to exercise streaming updates. New run resets disclosure intent.
Failure and recovery
{"jurisdiction":"UK"}
{
"count": 2,
"jurisdiction": "UK"
}
Request timed out.
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
| Prop | Type | Behavior |
|---|---|---|
nameRequired | string | Required machine tool name, such as list_entities |
statusRequired | "pending"|"running"|"done"|"failed" | Required execution state |
label | string | Overrides automatic English tense/localizes the row |
meta | string | Optional inline metadata and supporting copy |
description | string | Optional inline metadata and supporting copy |
error | string | Visible failure detail outside the collapsed payload |
input | ToolCallPayloadView fields | Complete pre-serialized, redacted payload; language defaults to text |
output | ToolCallPayloadView fields | Complete pre-serialized, redacted payload; language defaults to text |
disclosureConfig | ActivityDisclosureConfigView fields | Payload starts closed and remains independent of execution |
className | string | Layout override |
inputObject fields
| Field | Type | Requirement |
|---|---|---|
code | string | Required Complete, pre-serialized text. Redaction and safe serialization belong to the host. |
language | string | Optional |
filename | string | Optional |
outputObject fields
| Field | Type | Requirement |
|---|---|---|
code | string | Required Complete, pre-serialized text. Redaction and safe serialization belong to the host. |
language | string | Optional |
filename | string | Optional |
disclosureConfigObject fields
| Field | Type | Requirement |
|---|---|---|
open | boolean | Optional |
defaultOpen | boolean | Optional |
onOpenChange | ((open: boolean) => void) | Optional |
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
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 for migration mappings; consumer migration is outside this phase.