> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM Custom

> Extract several flat fields from the current conversation in one LLM call, using a supplied JSON schema.

## Description

Use **LLM Custom** when you need to extract several fields from the current conversation in one call. It is best for small, flat groups of related values, such as contact details or claim details.

Use [LLM Data](/tools/llm/llm-data) instead when you only need one value.

***

## Manual Inputs

| Name          | Data Type | Required | Description                                                       |
| ------------- | --------- | -------- | ----------------------------------------------------------------- |
| Reasoning     | string    | No       | LLM reasoning effort (`low`, `medium`, `high`). Defaults to `low` |
| Transcript    | string    | No       | How much conversation history to read. Defaults to `Full`         |
| System Prompt | string    | No       | Instruction that applies to every field                           |
| Schema JSON   | json      | Yes      | The flat fields the tool should return                            |
| Response Map  | object    | No       | Where to write each extracted field                               |

### Reasoning

How hard the model works to interpret the information.

* `low` — fields are directly stated
* `medium` — the caller may imply values or answer in a messy way
* `high` — fields need careful normalization, or there are competing details (can be slower)

### Transcript

How much conversation history the tool reads: `Full`, or the last `2`, `4`, `6`, `8`, or `10` messages.

* Use `Last 2` / `Last 4` when fields should come from the caller's latest answer.
* Use `Last 6` / `Last 10` when values may be spread across a short exchange.
* Use `Full` when earlier context matters — avoid it for simple extraction, since older details can confuse the result.

### System Prompt

Optional instruction that applies to every field. Appended before the transcript and schema.

```text theme={null}
Only extract values explicitly stated by the customer. Do not infer missing contact details.
Return null for fields the caller did not provide.
Normalize dates to YYYY-MM-DD when possible.
Prefer the customer's latest correction if they changed an earlier answer.
```

Don't repeat every field description here — put field-specific rules in the schema.

### Schema JSON

One parent JSON object. Each key is a flat output field. Each value must include `type` and `description`.

```json theme={null}
{
  "first_name": {
    "type": ["string", "null"],
    "description": "Customer first name"
  },
  "email": {
    "type": ["string", "null"],
    "description": "Customer email address"
  },
  "claim_number": {
    "type": ["string", "null"],
    "description": "Insurance claim number. Exclude policy numbers."
  }
}
```

Supported field types:

| Type      | Meaning                                                        |
| --------- | -------------------------------------------------------------- |
| `string`  | Text                                                           |
| `number`  | Decimal number                                                 |
| `integer` | Whole number                                                   |
| `boolean` | True or false                                                  |
| `array`   | A list — include an `items` definition for the item type       |
| `null`    | Usually combined with another type when a field may be missing |

Use nullable fields (`["string", "null"]`) when the customer might not provide a value.

**Keep the schema flat.** Do not nest objects — use field names like `customer_email` instead of `customer.email`. Do not include wrapper fields such as `schema`, `required`, or `additionalProperties`; the tool adds those internally.

### Response Map

Optional. Maps each destination variable to the field name returned by the schema. The left side is the destination variable; the right side is the extracted field name.

```text theme={null}
{{contact.email}}        -> email
{{custom.claim_number}}  -> claim_number
```

Use a blank field name on the right to write the whole extracted object into one variable.

***

## Manual Outputs

| Name   | Data Type | Description                                                                  |
| ------ | --------- | ---------------------------------------------------------------------------- |
| result | bool      | `true` if the LLM returned schema-valid JSON and configured writes succeeded |

***

## Conditions

### Success (true)

The LLM returned valid JSON matching the schema. If a Response Map is configured, fields are written to their destinations.

### Failure (false)

The schema was invalid, the transcript was empty, or extraction failed.

***

## Example Usage

Contact details:

```text theme={null}
Reasoning: low
Transcript: Last 6
System Prompt: Only extract values explicitly stated by the customer. Return null for missing fields.
Schema fields: first_name, last_name, email
Response Map:
  {{contact.first_name}} -> first_name
  {{contact.last_name}}  -> last_name
  {{contact.email}}      -> email
```

Claim details:

```text theme={null}
Reasoning: medium
Transcript: Full
System Prompt: Prefer the customer's latest correction.
Schema fields: claim_number, incident_date, incident_location
Response Map:
  {{custom.claim_number}}     -> claim_number
  {{custom.incident_date}}    -> incident_date
  {{custom.incident_location}} -> incident_location
```

***

## Common Issues

* **Schema fails validation** — check that every field has both `type` and `description`.
* **Unsupported type error** — use `string`, `number`, `integer`, `boolean`, `array`, or `null`.
* **Array fields fail** — add an `items` definition describing the list item type.
* **Nested objects fail** — flatten the schema into top-level fields.
* **Wrong value is written** — check the Response Map field name on the right side.
* **Noisy extraction** — reduce Transcript and make field descriptions more specific.

***

## Next Steps

* [LLM Data](/tools/llm/llm-data) — Extract a single typed value
* [LLM Tools overview](/tools/llm/overview) — When extraction passes vs fails
* [Variables](/flows/variables) — See all available variables