ki-tool-call
@kimen/elements/ki-tool-call- Source
- Agent reference
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
approval-label | approvalLabel | string | 'Needs approval' | Status text for a call waiting on an approval decision. |
done-label | doneLabel | string | 'Done' | Status text for a successful call. |
duration | duration | number | undefined | – | Non-negative elapsed time in milliseconds. Displayed only for Done. |
error-label | errorLabel | string | 'Error' | Caption for the error slot. |
failed-label | failedLabel | string | 'Failed' | Status text for a failed call. |
input-label | inputLabel | string | 'Input' | Caption for the input slot. |
locale | locale | string | 'en' | Language tag used to format the completed duration. Defaults to English. |
name | name | string | – | Tool identifier, such as search_docs, displayed in monospace. |
open | open | boolean | 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-label | outputLabel | string | 'Output' | Caption for the output slot. |
pending-label | pendingLabel | string | 'Pending' | Status text for a call waiting to run. |
retry-label | retryLabel | string | 'Retry' | Visible and accessible label for the built-in retry control. |
retryable | retryable | boolean | false | Offer the built-in Retry button when the call fails. |
running-label | runningLabel | string | 'Running' | Status text for a call in progress. |
status | status | "approval" | "done" | "failed" | "pending" | "running" | 'pending' | Lifecycle status. Unknown values display Pending. |
title | toolTitle | string | undefined | – | Optional human-readable label displayed beside the identifier. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-tool-retry | CustomEvent<{ name: string }> | A request to retry this tool call. Bind a declared surface action to handle it. |
ki-tool-status-change | CustomEvent<{ name: string; status: string; label: string }> | Once per status transition after initialization. Append one entry to the conversation log. |
Slots
| Slot | Description |
|---|---|
error | A failure message or a consumer-owned retry control, visible on failed calls. |
input | Arguments supplied to the tool. Use ki-code-block for structured text. |
output | Result returned by the tool. Use ki-code-block for structured text. |
CSS parts
| Part | Description |
|---|---|
body | Content disclosed by opening the call. |
disclosure | Native details surface. |
error | Error section for failed calls. |
input | Input section with its caption and payload. |
name | Monospaced tool identifier. |
output | Output section with its caption and payload. |
payload | Surface for the input and output content. |
retry | Opt-in action button for failed calls. |
status | Badge that contains the status text and completed duration. |
summary | Native 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.
| Token | Description |
|---|---|
--ki-badge-sm-height | dimension used by the badge component for sm height. |
--ki-density-target-min | The 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-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-width | Thickness 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-filter | Whole filter behind the call. |
--ki-tool-call-bg | Solid background of the call disclosure. |
--ki-tool-call-bg-image | Optional image over the solid background. |
--ki-tool-call-border | Border ink around the call. |
--ki-tool-call-border-width | Width of the disclosure frame. |
--ki-tool-call-caption-size | Size of captions and the tool identifier. |
--ki-tool-call-code-bg | Background for input and output payloads. |
--ki-tool-call-code-fg | Plain text ink on the payload surface. |
--ki-tool-call-code-radius | Corners of the plain payload surface. |
--ki-tool-call-fg | Text ink on the call surface. |
--ki-tool-call-font-size | Body text size. |
--ki-tool-call-gap | Gap between summary items and body sections. |
--ki-tool-call-icon | Ink of the decorative icons. |
--ki-tool-call-icon-size | Size of the wrench and chevron. |
--ki-tool-call-inline-gap | Gap between status items and after each caption. |
--ki-tool-call-line-height | Body text line height. |
--ki-tool-call-mono-family | Typeface of the tool identifier. |
--ki-tool-call-padding | Horizontal inset and space after the body. |
--ki-tool-call-radius | Corners of the disclosure surface. |
--ki-tool-call-transition-duration | Duration of the disclosure chevron rotation. |
--ki-tool-call-transition-easing | Easing of the disclosure chevron rotation. |
--ki-typography-family-body | semantic font family for typography family body. |