Skip to content
Kimenpre-v1documentation home
Color scheme

ki-tool-call

Theme for this example
Color scheme for this example
{"query": "Form validation"} ["Field help and errors"]
<ki-tool-call name="search_docs" title="Search docs" status="done" duration="1200" open>
<ki-code-block slot="input" language="json" filename="search-input.json" wrap>{"query": "Form validation"}</ki-code-block>
<ki-code-block slot="output" language="json" filename="search-output.json" wrap>["Field help and errors"]</ki-code-block>
</ki-tool-call>

Use one disclosure per tool call. Supply a stable tool ID in name and an optional human-readable title (toolTitle in typed bindings). A completed call shows its elapsed duration when supplied in milliseconds.

Put arguments in input, results in output and failure details in error. Use CodeBlock for structured text and supply distinct filenames when you show multiple blocks in the same view. A failed call opens by default. Set open="false" to start it collapsed. The native summary responds to pointer activation, Enter and Space.

Set retryable to offer the Retry button on a failure. Handle the ki-tool-retry event in your app or bind a declared action to the ToolCall in a guarded surface. For approvals, show the approval status and provide a separate confirmation control.

Listen for ki-tool-status-change and append one entry to your conversation’s existing log. The event provides detail.name, detail.status and detail.label. Initial states remain available in the summary. Localize the badge and caption labels through their label props. Set locale to format the completed duration for your audience.

API reference

When to use: show which tool ran, its state and duration, and let the reader inspect the supplied input, output or error. Use a conversation log for status updates.

When not to use: collecting approval, running or configuring tools. Pair with a separate confirmation control for an approval decision.

Properties & attributes

AttributePropertyTypeDefaultDescription
approval-labelapprovalLabelstring'Needs approval'Status text for a call waiting on an approval decision.
done-labeldoneLabelstring'Done'Status text for a successful call.
durationdurationnumber | undefined–Non-negative elapsed time in milliseconds. Displayed only for Done.
error-labelerrorLabelstring'Error'Caption for the error slot.
failed-labelfailedLabelstring'Failed'Status text for a failed call.
input-labelinputLabelstring'Input'Caption for the input slot.
localelocalestring'en'Language tag used to format the completed duration. Defaults to English.
namenamestring–Tool identifier, such as search_docs, displayed in monospace.
openopenboolean | undefined–Override the disclosure state. Without an override, failed calls are open and other calls are closed. Set open="false" for an explicit collapse. Using the summary sets the property to the reader's choice.
output-labeloutputLabelstring'Output'Caption for the output slot.
pending-labelpendingLabelstring'Pending'Status text for a call waiting to run.
retry-labelretryLabelstring'Retry'Visible and accessible label for the built-in retry control.
retryableretryablebooleanfalseOffer the built-in Retry button when the call fails.
running-labelrunningLabelstring'Running'Status text for a call in progress.
statusstatus"approval" | "done" | "failed" | "pending" | "running"'pending'Lifecycle status. Unknown values display Pending.
titletoolTitlestring | undefined–Optional human-readable label displayed beside the identifier.

Events

EventDetail typeDescription
ki-tool-retryCustomEvent<{ name: string }>A request to retry this tool call. Bind a declared surface action to handle it.
ki-tool-status-changeCustomEvent<{ name: string; status: string; label: string }>Once per status transition after initialization. Append one entry to the conversation log.

Slots

SlotDescription
errorA failure message or a consumer-owned retry control, visible on failed calls.
inputArguments supplied to the tool. Use ki-code-block for structured text.
outputResult returned by the tool. Use ki-code-block for structured text.

CSS parts

PartDescription
bodyContent disclosed by opening the call.
disclosureNative details surface.
errorError section for failed calls.
inputInput section with its caption and payload.
nameMonospaced tool identifier.
outputOutput section with its caption and payload.
payloadSurface for the input and output content.
retryOpt-in action button for failed calls.
statusBadge that contains the status text and completed duration.
summaryNative disclosure control and its status row.

CSS custom properties

The public styling contract of ki-tool-call: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-badge-sm-heightdimension used by the badge component for sm height.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-tool-call-backdrop-filterWhole filter behind the call.
--ki-tool-call-bgSolid background of the call disclosure.
--ki-tool-call-bg-imageOptional image over the solid background.
--ki-tool-call-borderBorder ink around the call.
--ki-tool-call-border-widthWidth of the disclosure frame.
--ki-tool-call-caption-sizeSize of captions and the tool identifier.
--ki-tool-call-code-bgBackground for input and output payloads.
--ki-tool-call-code-fgPlain text ink on the payload surface.
--ki-tool-call-code-radiusCorners of the plain payload surface.
--ki-tool-call-fgText ink on the call surface.
--ki-tool-call-font-sizeBody text size.
--ki-tool-call-gapGap between summary items and body sections.
--ki-tool-call-iconInk of the decorative icons.
--ki-tool-call-icon-sizeSize of the wrench and chevron.
--ki-tool-call-inline-gapGap between status items and after each caption.
--ki-tool-call-line-heightBody text line height.
--ki-tool-call-mono-familyTypeface of the tool identifier.
--ki-tool-call-paddingHorizontal inset and space after the body.
--ki-tool-call-radiusCorners of the disclosure surface.
--ki-tool-call-transition-durationDuration of the disclosure chevron rotation.
--ki-tool-call-transition-easingEasing of the disclosure chevron rotation.
--ki-typography-family-bodysemantic font family for typography family body.

Open ki-tool-call in Storybook