---
id: llm--llm-tool
title: "AI tool"
summary: "Exposes a branch of the flow as a tool (function) that an **LLM chat client** can call. The model decides when to call it, the arguments are sent to the components on `Output`, and whatever comes back on `Input` is returned to the model as the tool result."
audience: user
keywords: "register, output, input, name, instructions, timeout"
---
# AI tool

Exposes a branch of the flow as a tool (function) that an **LLM chat client** can call. The model decides when to call it, the arguments are sent to the components on `Output`, and whatever comes back on `Input` is returned to the model as the tool result.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Register | register | `Viaducta.Plugins.Llm.Types.LlmToolRegistrationRequest` | Connect to the `Register` pin of one LLM chat client. |
| Output | output | type of the output connection | The tool call: an object of the connection's type filled with the arguments chosen by the model. |
| Input | input | type of the input connection | The tool result. Connect the last component of the tool branch here. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `Name` | string | empty | Tool name the model sees, e.g. `order_status` (use letters, digits, `_`; unique per chat client). |
| `Instructions` | multi-line text | empty | Tool description for the model: what it does, when to use it, what the arguments mean. |
| `Timeout` | integer seconds | `30` | Maximum time for the branch to deliver a result; `0` means 24 hours. |

## Behaviour

- When the flow starts, the tool registers with every chat client its `Register` pin is connected to.
- Arguments schema: generated from the type on the **Output** connection - its public properties become the tool's parameters (strings, numbers, booleans, dates as strings, enums as strings, lists as arrays, nested types as objects). Result schema: generated from the type on the **Input** connection.
- On a tool call, a new object of the Output type is created, each argument is converted to the property type and set (unknown arguments are skipped with a warning), and the object is emitted on `Output` with new metadata containing `LlmToolInvokeData` (`ToolInvokeRequestId`, `LlmToolRegistryKey`).
- When a message arrives on `Input`, the metadata identifies the pending call and the message is returned to the model as the result. The chat client waits at most `Timeout` seconds; then the model gets an error text instead.

## Notes

- Keep the metadata: the branch between `Output` and `Input` must pass on the metadata it received (normal plugins do). A result without `LlmToolInvokeData` raises "The Llm tool metadata is null".
- Every call must produce exactly one message on `Input`; a filtered or failed branch makes the model wait for the timeout. Exceptions in the branch are returned to the model as an error.
- Both `Output` and `Input` must be connected before the flow starts; without an Output connection a tool call fails ("has no connected Output pin").
- Connect a tool to one chat client only: when connected to several, each call is emitted on `Output` once per connected client.
- The model only sees `Name`, `Instructions` and the property names/types; name properties clearly (`OrderNo`, not `P1`).

## Example

```json
{ "Name": "order_status", "Instructions": "Returns the status and delivery date of an order. Call it when the user asks about an order. Argument OrderNo is the order number, e.g. 2024-0001.", "Timeout": 20 }
```

LLM chat client ← (Register) **AI tool** → (Output, type `OrderQuery`) Database reader → Data mapper (type `OrderStatus`) → **AI tool** (Input)