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

# Tools

The `TOOLS:` section defines the external capabilities available to an agent. Each tool declares a typed signature (parameters and return type), an optional execution binding, and metadata that guides the LLM's tool selection.

## Tool binding types

The `type:` property selects how a tool is executed. The supported values are:

| Type | Purpose |
| :- | :- |
| `http` | Call a REST (or SOAP) API endpoint. See [HTTP tools](#http-tools). |
| `mcp` | Bind a tool exposed by an MCP server. See [MCP tools](#mcp-tools). |
| `lambda` | Invoke a cloud serverless function. See [Lambda tools](#lambda-tools). |
| `async_webhook` | Fire-and-callback async HTTP. See [Async webhook tools](#async-webhook-tools). |
| `workflow` | Invoke a durable workflow on the workflow engine. See [Workflow tools](#workflow-tools). |
| `searchai` | Query a SearchAI knowledge base. See [SearchAI tools](#searchai-tools). |
| `table` | Structured CRUD against an Agent Table. See [Table tools](#table-tools). |

## Tool declaration syntax

You declare a tool with a function-style signature followed by indented properties.

```yaml theme={null}
TOOLS:
  tool_name(param1: type1, param2: type2 = default) -> ReturnType
    description: "What this tool does"
    type: http
    endpoint: "/api/path"
    method: POST
```

### Signature format

```yaml theme={null}
name(parameters) -> return_type
```

* **name** -- a lowercase identifier using `snake_case`
* **parameters** -- comma-separated list of typed parameters
* **return\_type** -- the type of data the tool returns

### Parameter syntax

Each parameter follows the format `name: type`, optionally marked optional with `?` and/or given a default value:

```yaml theme={null}
param_name: type
param_name?: type              # optional (no default)
param_name: type = default_value
```

| Component | Description | Examples |
| - | - | - |
| `name` | Parameter identifier (snake\_case) | `account_id`, `query`, `limit` |
| `?` | Optional marker after the name — makes the parameter optional without giving it a default | `note?: string` |
| `type` | Data type | `string`, `number`, `boolean`, `date` |
| `= default` | Default value (also makes the parameter optional) | `= 10`, `= "USD"`, `= true` |

A parameter is required only when it has **neither** a `?` marker **nor** a default value. Both `name?: type` and `name: type = default` make it optional.

### Parameter types

| Type | Description | Examples |
| - | - | - |
| `string` | Text value | `"hello"` |
| `number` | Numeric value (integer or float) | `42`, `3.14` |
| `boolean` | True or false | `true`, `false` |
| `date` | Date value | `"2026-03-01"` |
| `object` | Nested object (specify fields with nested `parameters:`) | -- |
| `type[]` | Array of the given type | `string[]`, `number[]` |

#### Object parameters

When a parameter has type `object`, you can define nested fields using a `parameters:` block under the tool:

```yaml theme={null}
TOOLS:
  create_order(customer: object, items: object[]) -> {order_id: string}
    description: "Create a new order"
    parameters:
      customer:
        name: string
        email: string
      items:
        product_id: string
        quantity: number
```

#### Array parameters

Array types use the `[]` suffix:

```yaml theme={null}
TOOLS:
  bulk_lookup(ids: string[]) -> {results: object[]}
    description: "Look up multiple records by ID"
```

#### Parameter enrichment and sources

The `parameters:` block does more than describe nested object fields — it can enrich any signature-declared parameter with a description, validation, visibility, and a **value source**. This lets you inject values (from system state, config, auth, an expression, or a lookup table) without the LLM having to supply them, and optionally hide them from the model.

```yaml theme={null}
TOOLS:
  charge_card(amount: number, customer_id: string) -> {receipt_id: string}
    description: "Charge the customer's card on file"
    type: http
    endpoint: "/api/charges"
    method: POST
    parameters:
      customer_id:
        source: system            # model | system | runtime | config | auth | expr | lookup
        value: "session.customer_id"
        hidden: true              # do not expose to the model
      amount:
        description: "Charge amount in the account currency"
        required: true
```

| Enrichment key | Type | Description |
| - | - | - |
| `description` | `string` | Parameter description shown to the model. |
| `required` | `boolean` | Whether the parameter is required. |
| `default` | any | Default value. |
| `source` | `string` | Value source: `model`, `system`, `runtime`, `config`, `auth`, `expr`, `lookup`. |
| `value` | `string` | The expression or reference used with `expr`/`lookup`/`system`/`config` sources. |
| `key` / `table` | `string` | Lookup key and table (with `source: lookup`). |
| `hidden` | `boolean` | Hide the parameter from the model (still sent to the tool). |
| `visibility` | `object` | Fine-grained `{ model, trace }` visibility flags. |
| `properties` | `object` | Nested object field schema (for `object` params). |
| `items` | `object` | Item schema (for array params). |

> [!NOTE]
>
> `default_source` is accepted as an alias for `source` (both set the parameter's value source). Some compile-time diagnostics — for example the [trusted SIP transfer destination](#trusted-sip-transfer-destinations) check — refer to the key by its `default_source` spelling.

#### Trusted SIP transfer destinations

The built-in `call_transfer` voice tool takes a `sipTransferId` parameter — a `sip:`/`sips:` endpoint URI. To pin a **fixed, trusted** transfer target for the agent (rather than letting the model choose one, or relying on project settings), declare `call_transfer` with its signature in `TOOLS:` and enrich the `sipTransferId` parameter with a literal `default` and `default_source: config`:

```yaml theme={null}
TOOLS:
  # Pin the agent's SIP transfer destination on the built-in call_transfer tool.
  call_transfer(callTransferType: string, sipTransferId: string) -> object
    params:                       # `parameters:` is an accepted alias
      sipTransferId:
        default: "sip:premium-support@sbc.example.com"
        default_source: config
```

The `params:` block enriches the signature-parsed parameter by name — it does not redeclare the built-in's implementation. Marking the default `default_source: config` does two things: the runtime reads the destination **server-side from the compiled agent** (never from the tool-call arguments, which carry model- and caller-influenced values), and it **hides the parameter from the model's tool schema** entirely, so the LLM never sees a destination field to fill.

At SIP transfer time the runtime resolves the destination in order: (1) the authored `sipTransferId` default, if present and valid; (2) the project-configured `voice.sipTransferTargetUri` (Agent Transfer settings); (3) otherwise the call fails with a missing-target error. `default_source: system` is treated as trusted the same way (for platform-injected declarations).

The compiler enforces that an authored destination is safe to trust:

| Diagnostic | Severity | Fires when |
| - | - | - |
| [`INVALID_SIP_TRANSFER_DESTINATION`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#invalid_sip_transfer_destination) | Error | A trusted-source (`config`/`system`) `sipTransferId` default is empty, is not a valid `sip:`/`sips:` URI, uses a dynamic source (`expr`, `lookup`, `runtime`, `auth`), or contains a `{{ }}` template other than an admitted inbound-header placeholder (see [Inbound SIP header placeholders](#inbound-sip-header-placeholders)). The destination's user/host must be a static literal — a target derived from conversation data could be influenced by the caller. |
| [`UNTRUSTED_SIP_TRANSFER_DESTINATION`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#untrusted_sip_transfer_destination) | Warning | A `sipTransferId` default is declared with `default_source` **absent or `model`**. The value is treated as model-supplied and is **ignored at transfer time** (behavior is unchanged from before) — add `default_source: config` to make it the agent's trusted destination. |

Omit the `sipTransferId` default entirely to rely solely on the project-configured Agent Transfer target.

##### Inbound SIP header placeholders

The one template form allowed in a `sipTransferId` default is `{{sip.<header>}}`. At transfer time the runtime replaces it with the value of an inbound SIP header from the **current call's trusted SIP metadata** (the headers the call arrived with) — never from conversation data or model output. Use it to forward an inbound header onto the transfer leg, for example a `User-to-User` correlation token or a tracing header:

```yaml theme={null}
TOOLS:
  call_transfer(callTransferType: string, sipTransferId: string) -> object
    params:
      sipTransferId:
        default: "sip:premium-support@sbc.example.com?User-to-User={{sip.user-to-user}}&X-Trace-Id={{sip.x-trace-id}}"
        default_source: config
```

**Syntax.** `{{sip.<header>}}`, where `<header>` is the inbound SIP header name, matched case-insensitively (for example `{{sip.user-to-user}}` reads the inbound `User-to-User` header).

Placeholders are constrained so inbound data can *decorate* the transfer but never *redirect* it. The compiler rejects the default with `INVALID_SIP_TRANSFER_DESTINATION` unless every placeholder satisfies all of:

| Rule | Requirement |
| - | - |
| **Position** | A placeholder may appear only in the URI's header section (the `?Name=value&…` part after `?`). A placeholder anywhere in the user/host — the part that determines where the call is dialed — is rejected (`placeholder_outside_headers`). |
| **Whole value only** | A placeholder must be the *entire* value of a URI header (`?X-Trace-Id={{sip.x-trace-id}}`), not embedded in a larger value and not partial. |
| **Value, not name** | A placeholder may never appear in a URI-header *name* (`placeholder_in_header_name`) — an inbound value must not become a header key. |
| **Admitted destination header** | Only `User-to-User` and any `x-*` header may *carry* a placeholder value (`inadmissible_header_name` otherwise). |
| **Admitted source header** | The inbound header *read from* — the `<name>` in `{{sip.<name>}}` — must **also** be admissible (`User-to-User` or `x-*`), so an admitted destination header cannot launder an arbitrary inbound header's value (`inadmissible_source_header` otherwise). |

Any other use of `{{ }}` — a general expression/variable template, a placeholder in the user/host, or a malformed placeholder — remains an error; only `{{sip.<header>}}` in an admitted header value is interpolated. The URI's user and host are always static.

##### User-to-User parameters

A `User-to-User` placeholder can carry authored parameters. Write `;name=value` pairs directly after the placeholder. The runtime composes them between the inbound value and `;encoding=hex`:

```yaml theme={null}
TOOLS:
  call_transfer(callTransferType: string, sipTransferId: string) -> object
    params:
      sipTransferId:
        default: "sip:premium-support@sbc.example.com?User-to-User={{sip.user-to-user}};x-art=Y;x-sessionId={{session.id}}"
        default_source: config
```

With this default, the transfer sends `<inbound value>;x-art=Y;x-sessionId=<session id>;encoding=hex`.

| Rule | Requirement |
| - | - |
| **Count** | Up to 8 parameters per destination. |
| **Names** | Letters, digits, `.`, `_` and `-`, starting with a letter or digit. Names must be unique, ignoring case. The case you write is kept. `encoding` is reserved. |
| **Values** | A literal of letters, digits, `.`, `_` and `-`, up to 64 characters, or `{{session.id}}`. |
| **Where** | Only after a `User-to-User` placeholder. `{{session.id}}` is allowed only as a parameter value. |

The compiler rejects any other form with `INVALID_SIP_TRANSFER_DESTINATION`.

##### Dynamic destinations

For a destination chosen at runtime, replace the static `default` with a `template` and an `approved_authorities` allow-list. The template is a **two-zone** SIP URI: a static shape whose authority (user/host/port) is filled from `{{route.*}}` placeholders, plus the same inbound `{{sip.<header>}}` header decoration described above. The `{{route.*}}` values are produced by a [`RESOLVE_SIP_DESTINATION`](https://koreai.mintlify.site/agent-platform/abl/reference/flow#resolve_sip_destination) flow step, which runs before the transfer and commits the chosen authority to a trusted server-side routing channel.

```yaml theme={null}
TOOLS:
  call_transfer(callTransferType: string, sipTransferId: string) -> object
    params:
      sipTransferId:
        default_source: config
        template: "sip:{{route.vdn}}@{{route.ip}}:{{route.port}};user=phone?User-to-User={{sip.user-to-user}}"
        approved_authorities:
          - "sip:521001@172.0.41.7:5060"
          - "sip:521002@172.0.41.7:5060"
          - "sip:5220[0-9][0-9]@172.0.41.7:5060"
```

* **Zone 1 — authority** (before `?`): `{{route.vdn}}`, `{{route.ip}}`, `{{route.port}}` are filled from the `RESOLVE_SIP_DESTINATION` feeder's result — its return shape must use exactly those keys.
* **Zone 2 — headers** (after `?`): `{{sip.<header>}}` placeholders, resolved server-side from trusted inbound SIP metadata, under the same rules as static defaults above.
* **`approved_authorities`** is a mandatory allow-list — the resolved destination must match one entry or the transfer is refused. Each entry must be a **literal** SIP authority with an explicit scheme, host, and port (no default-port inference, no wildcard host). The VDN (user part) may be an exact digit string or a constrained digit-class pattern using single-digit ranges only — for example, `5220[0-9][0-9]`. Regex metacharacters, alternation, anchors, groups, and any query/header/param section are rejected.

The compiler validates both surfaces against the same predicates the runtime matcher uses (so a compile-accepted entry is never runtime-rejected): a malformed template raises `INVALID_SIP_TRANSFER_DESTINATION`; a bad allow-list entry raises [`INVALID_APPROVED_SIP_AUTHORITY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#invalid_approved_sip_authority) (not a literal authority with a literal VDN, host, and explicit port) or [`UNSAFE_SIP_AUTHORITY_PATTERN`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#unsafe_sip_authority_pattern) (unsafe VDN pattern).

### Return type

The return type appears after the `->` arrow. It can be:

| Form | Syntax | Example |
| - | - | - |
| Simple type | `-> type` | `-> string` |
| Object type | `-> {field: type, ...}` | `-> {id: string, name: string}` |
| Array type | `-> type[]` | `-> Hotel[]` |
| Nested object | `-> {field: {nested: type}}` | `-> {user: {name: string, age: number}}` |
| Optional fields | `-> {field?: type}` | `-> {error?: string}` |
| Array of objects | `-> {field: type}[]` | `-> {id: string, title: string}[]` |

```yaml theme={null}
TOOLS:
  search_hotels(destination: string, checkin: date, checkout: date) -> {hotels: {id: string, name: string, price: number, rating: number}[], total: number}
    description: "Search available hotels"
```

### Description

The `description:` property provides a natural-language explanation of what the tool does. The LLM uses this description to decide when and how to call the tool.

```yaml theme={null}
TOOLS:
  verify_account(account_id: string) -> {name: string, status: string}
    description: "Retrieve account details and verify the account is active"
```

Write meaningful descriptions that help the LLM understand:

* What the tool does
* When to call it
* What data it returns

### Hints

The `hints:` block provides execution metadata that the runtime uses for optimization:

```yaml theme={null}
TOOLS:
  get_balance(account_id: string) -> {balance: number}
    description: "Get account balance"
    hints:
      cacheable: true
      side_effects: false
      latency: fast
      timeout: 5000
```

| Hint | Type | Default | Description |
| - | - | - | - |
| `cacheable` | `boolean` | *none* | Reuse the result of an identical call in the same conversation. Read-only tools only. See [Result caching](#result-caching). |
| `latency` | `"fast"` , `"medium"` , `"slow"` | *none* | Expected latency category for runtime scheduling |
| `side_effects` | `boolean` | derived | Whether the tool modifies external state. Without it, an HTTP tool follows its method, SearchAI and read-only table tools are read-only, and other non-HTTP tools count as writing. |
| `requires_auth` | `boolean` | *none* | Whether the tool requires authenticated context |
| `timeout` | `number` | *none* | Tool-specific timeout in milliseconds (overrides `EXECUTION.tool_timeout`) |

***

## HTTP tools

HTTP tools call REST API endpoints. They're the most common tool type.

```yaml theme={null}
TOOLS:
  search_flights(origin: string, destination: string, date: date) -> {flights: {id: string, price: number}[]}
    description: "Search available flights"
    type: http
    endpoint: "https://api.flights.com/v1/search"
    method: POST
    auth: bearer
    timeout: 10000
    retry: 3
    retry_delay: 1000
```

### HTTP binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"http"` | Yes | -- | Declares this as an HTTP tool |
| `endpoint` | `string` | Yes | -- | URL or path for the API call. Supports path parameters: `"/hotels/{hotel_id}"` |
| `method` | `"GET"` , `"HEAD"` , `"OPTIONS"` , `"POST"` , `"PUT"` , `"PATCH"` , `"DELETE"` | Yes | -- | HTTP method |
| `idempotency_header` | `string` | No | *none* | Header name the runtime sends a durable dedupe key under (for example `Idempotency-Key`). Must name a real HTTP header, be ≤128 characters, and cannot be a credential/cookie/transport/signing header (`Authorization`, `Cookie`, `Host`, `Content-Type`, `X-Amz-*`, `SOAPAction`, etc.) — an invalid value is a compile warning ([`HTTP_TOOL_INVALID_IDEMPOTENCY_HEADER`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#http_tool_invalid_idempotency_header)) and the runtime sends no idempotency key. Omit to keep the key internal. |
| `auth` | `string` | No | `"none"` | Authentication type (see [Auth](#auth)) |
| `timeout` | `number` | No | `EXECUTION.tool_timeout` | Request timeout in milliseconds |
| `retry` | `number` | No | *none* | Number of retry attempts on failure |
| `retry_delay` | `number` | No | *none* | Delay in milliseconds between retries |
| `retry_policy` | `object` | No | *none* | Structured backoff policy (richer alternative to `retry`/`retry_delay`). See [Retry policy](#retry-policy). |
| `headers` | `Record<string, string>` | No | *none* | Custom HTTP headers |
| `query_params` | `Record<string,string>` / `object[]` | No | *none* | Query string parameters. A `key: value` block keeps insertion order; an array of `{key, value}` also allows duplicate keys. |
| `body_type` | `"json"` , `"form"` , `"xml"` , `"text"` | No | *none* | Request body encoding. |
| `body_mode` | `"auto"` , `"none"` | No | `"auto"` | For non-GET methods: `auto` serializes remaining params as the body; `none` sends no body. |
| `body_template` | `string` | No | *none* | Custom body template with interpolation. `body` is accepted as an alias. |
| `body_schema` | `string` | No | *none* | JSON Schema for the request body (used with `use_body_schema: true`). |
| `use_body_schema` | `boolean` | No | `false` | Author/validate the request body from `body_schema`. |
| `request_variants` | `object[]` | No | *none* | Conditional request variants selected by a `when` expression. See [Request variants](#request-variants). |
| `rate_limit` | `number` | No | *none* | Maximum requests per second |
| `circuit_breaker` | `{threshold, resetMs}` | No | *none* | Circuit breaker configuration |
| `protocol` | `"rest"` , `"soap"` | No | `"rest"` | Wire protocol. Set `soap` for SOAP endpoints. See [SOAP support](#soap-support). |
| `soap_version` | `"1.1"` , `"1.2"` | No | `"1.1"` | SOAP version (when `protocol: soap`). |
| `soap_action` | `string` | No | *none* | `SOAPAction` header (1.1) or action media-type parameter (1.2). |
| `on_soap_fault` | `"error"` , `"data"` | No | *none* | How to handle `<soap:Fault>` — `error` throws, `data` returns the fault payload. |
| `wsdl_*` | see [WSDL operation binding](#wsdl-operation-binding) | No | *none* | Bind a SOAP tool to a stored WSDL operation instead of authoring the envelope. |

### Path parameters

Use curly braces in the endpoint to reference tool parameters:

```yaml theme={null}
TOOLS:
  get_hotel(hotel_id: string) -> Hotel
    type: http
    endpoint: "/hotels/{hotel_id}"
    method: GET
```

### Headers

Custom headers are specified as key-value pairs:

```yaml theme={null}
TOOLS:
  get_data(query: string) -> {results: object[]}
    type: http
    endpoint: "/api/data"
    method: POST
    headers:
      X-Api-Version: "2024-01"
      Accept: "application/json"
```

> [!WARNING]
>
> On a recognized auth header — `Authorization`, `Proxy-Authorization`, `X-Api-Key`, `Api-Key`, or `X-Auth-Token` (case-insensitive) — a literal value that looks like a real credential (a JWT, a known provider token prefix, a `Bearer `/`Basic `/`Token ` scheme, or another long opaque token) is a compile warning ([`PLAINTEXT_HTTP_HEADER_SECRET`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#plaintext_http_header_secret)). The authored request still compiles and runs unchanged, but that value can cross export, logging, or runtime boundaries with no secret-management protection. Use `{{config.API_TOKEN}}` or an auth profile instead of a literal; a `{{ }}` reference is never flagged.

### Auth

The `auth:` property specifies the authentication mechanism. The runtime resolves credentials from the project's credential store -- the ABL document never contains actual secrets.

| Auth type | Description |
| - | - |
| `none` | No authentication |
| `bearer` | Bearer token in `Authorization` header |
| `api_key` | API key (header name configurable via `auth_config`) |
| `oauth2_client` | OAuth 2.0 client credentials flow |
| `oauth2_user` | OAuth 2.0 authorization code flow (user-scoped tokens) |
| `saml` | SAML assertion-based authentication |
| `custom` | Custom authentication with configurable headers |

> [!NOTE]
>
> `saml` is accepted by the parser but is **not currently resolved at runtime** — it is dropped during compilation. Prefer an [auth profile](#auth-profiles-jit-consent-and-connections) for enterprise SSO-backed integrations.

#### Auth configuration

For auth types that require additional configuration, use the `auth_config:` block:

```yaml theme={null}
TOOLS:
  get_user_data(user_id: string) -> {name: string, email: string}
    type: http
    endpoint: "/api/users/{user_id}"
    method: GET
    auth: oauth2_client
    auth_config:
      token_url: "https://auth.example.com/oauth/token"
      client_id: "my-client-id"
      client_secret: "{{config.OAUTH_CLIENT_SECRET}}"
      scopes: "read:users"
```

```yaml theme={null}
TOOLS:
  call_partner_api(payload: string) -> {status: string}
    type: http
    endpoint: "https://partner.example.com/api"
    method: POST
    auth: api_key
    auth_config:
      header_name: "X-API-Key"
```

| Auth config property | Type | Used with | Description |
| - | - | - | - |
| `token_url` | `string` | `oauth2_client`, `oauth2_user` | OAuth token endpoint URL |
| `client_id` | `string` | `oauth2_client`, `oauth2_user` | OAuth client identifier |
| `client_secret` | `string` | `oauth2_client`, `oauth2_user` | OAuth client secret (use `{{config.X}}` placeholders) |
| `scopes` | `string` | `oauth2_client`, `oauth2_user` | Space-separated OAuth scopes |
| `header_name` | `string` | `api_key` | Custom header name for the API key |
| `provider` | `string` | `oauth2_user`, `saml` | Auth provider identifier |
| `custom_headers` | `Record<string, string>` | `custom` | Custom authentication headers |

#### Credential placeholders

Credentials use `{{config.NAME}}` placeholder syntax (with `isSecret: true` on the config var). The runtime resolves these from the project's config vars at execution time. For OAuth integrations, binding an auth profile is the preferred approach. Never embed actual credentials in ABL files.

```yaml theme={null}
auth_config:
  client_secret: "{{config.PARTNER_OAUTH_SECRET}}"
```

#### Auth profiles, JIT, consent, and connections

For OAuth and enterprise integrations, the preferred approach is to bind a pre-configured **auth profile** by name rather than declaring `auth_config` inline. These tool-level properties control credential resolution, transport security, just-in-time authorization, consent, and per-user vs. shared connections:

```yaml theme={null}
TOOLS:
  create_ticket(subject: string, body: string) -> {ticket_id: string}
    description: "Create a support ticket"
    type: http
    endpoint: "https://itsm.example.com/api/tickets"
    method: POST
    auth_profile: servicenow_oauth   # named profile resolved at runtime
    tls_profile: partner_mtls         # mTLS transport cert profile
    auth_jit: true                    # acquire credentials just-in-time
    consent: preflight                # preflight | inline
    connection: per_user              # per_user | shared
```

| Property | Type | Description |
| - | - | - |
| `auth_profile` | `string` | Name of a pre-configured auth profile; resolved at runtime (no secrets in the ABL file). |
| `tls_profile` | `string` | Name of an mTLS transport-certificate profile (independent of `auth_profile`). |
| `auth_jit` | `boolean` | Acquire credentials just-in-time at call time rather than up front. |
| `consent` | `"preflight"` , `"inline"` | When user consent is obtained — before the run (`preflight`) or during the conversation (`inline`). |
| `connection` | `"per_user"` , `"shared"` | Whether the integration uses per-end-user connections or a single shared connection. |

### Result transformation

Tool results are available in the session context after execution. You can map specific result fields to session variables using `on_result:` and handle errors with `on_error:`:

```yaml theme={null}
TOOLS:
  get_balance(account_id: string) -> {balance: number, currency: string}
    description: "Get account balance"
    type: http
    endpoint: "/api/balance"
    method: GET
    on_result:
      set:
        current_balance: result.balance
        account_currency: result.currency
    on_error:
      set:
        balance_error: error.message
```

Beyond `set:`, both `on_result:` and `on_error:` accept an ordered `do:` action block that can run `SET`, `CLEAR`, `LOG`, `RESPOND`, `CALL`, `GOTO`/`THEN`, `HANDOFF`, `DELEGATE`, `RETURN`, `FORMATS` (or its canonical alias `RICH_CONTENT`), and `COMPLETE` actions, with conditional `IF:`/`WHEN:`/`ELSE:` branches. A rich-content payload rendered this way — for example a `FEEDBACK` survey attached to a tool's result — works with either spelling.

A `do:` action's `RESPOND` can carry its own `MODEL_CONTEXT` — a text-scalar sibling, the same idea as [MODEL\_CONTEXT on a response](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#model_context-on-a-response), applied here to a tool lifecycle response instead of a FLOW step's:

```yaml theme={null}
TOOLS:
  list_products() -> object
    MODEL_CONTEXT:
      FIELDS: [products[].id, products[].name, total]
    on_result:
      do:
        - RESPOND: "{{result.widget}}"
          MODEL_CONTEXT: "Displayed {{result.total}} products in order: {{result.product_summary}}."
          COMPLETE:
    on_error:
      do:
        - RESPOND: "Product search is unavailable."
          MODEL_CONTEXT: "Product search failed; no products were displayed."
          COMPLETE:
```

The full, protected `RESPOND` is still what's delivered and retained in the customer transcript — `MODEL_CONTEXT` only replaces what a *later* model call sees of this specific assistant turn. `result`/`error`, the tool's inputs, and any earlier `SET` in the same action are available to both templates. `MODEL_CONTEXT` without a `RESPOND` in the same action is invalid ([`MODEL_CONTEXT_INVALID`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#model_context_invalid)). Omit it to keep the historical full-response behavior; an explicitly empty value omits that response from later model calls entirely. This is independent of the tool-level `MODEL_CONTEXT` block above — one shapes the raw tool result the model sees, the other shapes what the model retains of this particular lifecycle response.

### Empty and malformed responses

For a successful JSON HTTP response:

* An exactly empty body returns `null`. This includes HTTP 204 and 205. A text or other non-JSON response keeps its existing empty-string result.
* JSON `false`, `0`, strings, and `null` are preserved.
* A non-empty malformed JSON body raises `TOOL_RESPONSE_PARSE_FAILED` with the upstream status. Whitespace-only content counts as malformed. Public error envelopes can use `TOOL_SCHEMA_MISMATCH`.
* For a side-effecting tool, the HTTP executor, the reasoning agent's error handler, and FLOW tool-call handlers do not retry automatically after this error. Declared read-only tools keep their configured retry policy.
* SOAP XML parsing failures use `network_error`, not message-derived subtypes. Existing code-specific parse handlers keep priority. Otherwise `SUBTYPE: network_error` can win over a type-only handler. The scope order is unchanged.
* An authored `THEN`, a backtrack, `CHECK ... ON_FAIL`, later tool calls, and caller retries each need their own admission. A parse failure does not authorize them.

In a FLOW, an empty JSON success reaches `ON_RESULT`, not `ON_ERROR`. `CALL ... AS` normalizes the result to an empty object. Use `ON_RESULT IF has(result.field)` to check presence. `SET` inserts referenced missing dotted leaves as `null`, so `has(result.field)` can be true and `!has(result.field)` false. A null comparison treats a missing field and an explicit null the same way.

An empty success is not a returned business record, and it is not an exactly-once guarantee. An asynchronous acceptance keeps its status and body predicates and its callback requirements.

### Final synthesis recovery

After a successful regular tool call, reasoning normally produces a model-written answer. If bounded retries run out with an unusable final answer, the runtime can keep eligible text from that tool round.

* Plain text and string fields named `response`, `answer`, `text`, `content`, or `message` are eligible, including fields under `result` or `data`. Arbitrary object dumps are not.
* Preserved text is capped at 4,000 characters. A newer tool round replaces the previous round's fallback text. Recovery does not run a completed tool again.
* For a synchronous JSON HTTP call that completed with no body, the bare `null` is excluded from customer recovery text. An intentional JSON `null`, quoted strings, and authored display text stay eligible. Tool values and `ON_RESULT` are unchanged.
* Strings whose trimmed content starts with an XML declaration (`<?xml` followed by whitespace or `?>`) or a `TResult` envelope opener are excluded. This is a fallback eligibility check, not a general XML sanitizer.
* A usable model answer and an explicitly authored response keep their existing presentation behavior.
* An empty final answer uses the separate runtime-owned confirmation and return recovery path.

### SSRF protection

The platform enforces SSRF (Server-Side Request Forgery) protection on all HTTP tool endpoints. Private IP ranges, localhost, and internal network addresses are blocked at the runtime level. Only allowlisted domains and public endpoints are permitted for HTTP tool calls.

### Circuit breaker

The circuit breaker prevents cascading failures by halting requests to a failing endpoint after a threshold of consecutive errors:

```yaml theme={null}
TOOLS:
  unreliable_api(query: string) -> {data: string}
    type: http
    endpoint: "https://api.example.com/data"
    method: GET
    circuit_breaker:
      threshold: 5
      resetMs: 30000
```

| Property | Type | Description |
| - | - | - |
| `threshold` | `number` | Number of consecutive failures before the circuit opens |
| `resetMs` | `number` | Milliseconds to wait before trying the endpoint again |

### Retry policy

`retry_policy` is a structured backoff configuration — a richer alternative to the scalar `retry`/`retry_delay` fields (both forms are still accepted).

```yaml theme={null}
TOOLS:
  flaky_api(id: string) -> {data: string}
    type: http
    endpoint: "https://api.example.com/{id}"
    method: GET
    retry_policy:
      strategy: exponential     # fixed | exponential
      initial_delay_ms: 200
      multiplier: 2
      max_delay_ms: 5000
      max_retries: 4
      jitter: full              # none | full
```

| Property | Type | Default | Description |
| - | - | - | - |
| `strategy` | `"fixed"` , `"exponential"` | -- | Backoff strategy (required). |
| `initial_delay_ms` | `number` | -- | Delay before the first retry. |
| `multiplier` | `number` | -- | Growth factor per attempt (for `exponential`). |
| `max_delay_ms` | `number` | -- | Ceiling on the delay between attempts. |
| `max_retries` | `number` | -- | Maximum retry attempts. |
| `jitter` | `"none"` , `"full"` | -- | Randomization applied to the delay. |

### SOAP support

HTTP tools can call SOAP endpoints by setting `protocol: soap`.

```yaml theme={null}
TOOLS:
  lookup_policy(policy_number: string) -> {status: string, holder: string}
    description: "Look up an insurance policy"
    type: http
    endpoint: "https://legacy.example.com/PolicyService"
    method: POST
    protocol: soap
    soap_version: "1.1"
    soap_action: "urn:PolicyService#lookupPolicy"
    on_soap_fault: error       # error | data
    soap_headers: '{"Security": {"UsernameToken": {"Username": "svc"}}}'
```

| Property | Type | Default | Description |
| - | - | - | - |
| `protocol` | `"rest"` , `"soap"` | `"rest"` | Wire protocol. |
| `soap_version` | `"1.1"` , `"1.2"` | `"1.1"` | SOAP envelope version. |
| `soap_action` | `string` | *none* | `SOAPAction` header (1.1) or action media-type parameter (1.2). |
| `on_soap_fault` | `"error"` , `"data"` | *none* | `error` raises on `<soap:Fault>`; `data` returns the fault as the result. |
| `soap_headers` | JSON object (as a string) | *none* | Custom SOAP header elements, authored as a JSON string. Malformed JSON is dropped rather than failing the tool compile. |

#### WSDL operation binding

Instead of hand-writing the SOAP envelope, a SOAP tool can bind to an operation from a WSDL asset stored in the project [WSDL Repository](https://koreai.mintlify.site/agent-platform/tools/wsdl-repo.md). When bound, the runtime resolves the operation's namespace, `SOAPAction`, and SOAP version from the stored WSDL and **generates the request body from the tool's JSON input** — no manual `body` template is needed. The request `endpoint` still comes from the tool: bulk-created tools are populated with the WSDL service address (or an endpoint override), and hand-authored tools must set `endpoint` explicitly.

Reference the WSDL by name; the platform resolves it to a stable asset/version at save time:

```yaml theme={null}
TOOLS:
  lookup_policy(policy_number: string) -> {status: string, holder: string}
    description: "Look up an insurance policy"
    type: http
    endpoint: "https://legacy.example.com/PolicyService"
    method: POST
    protocol: soap
    soap_version: "1.1"
    wsdl_asset: "PolicyService"       # asset name in the WSDL Repository
    wsdl_version: latest              # version number or "latest" (default)
    wsdl_operation: "lookupPolicy"
```

| Property | Type | Required | Description |
| - | - | - | - |
| `wsdl_asset` | `string` | No | WSDL asset **name** to bind. Resolved to `wsdl_asset_id` at save time. |
| `wsdl_version` | `string` | No | Version number (for example `2`) or `latest`. Defaults to the asset's latest version. |
| `wsdl_operation` | `string` | Yes\* | Name of the WSDL operation to invoke. |
| `wsdl_asset_id` | `string` | Yes\* | Stable asset ID. Written automatically when `wsdl_asset` is resolved; may be authored directly. |
| `wsdl_version_id` | `string` | Yes\* | Stable immutable version ID. Written automatically when `wsdl_version` is resolved. |
| `wsdl_service` | `string` | No | WSDL `service` name (when an operation is ambiguous across services). |
| `wsdl_port` | `string` | No | WSDL `port` name. |
| `wsdl_binding` | `string` | No | WSDL `binding` name. |
| `wsdl_target_namespace` | `string` | No | Target namespace override for body generation. |
| `wsdl_element` | `string` | No | Root request element name, when it differs from the operation name. |
| `wsdl_response_arrays` | comma-separated `string` | No | Response paths (for example `Envelope.Body.Response.Items,Envelope.Body.Response.Errors`) that should be parsed as arrays. |

> [!NOTE]
>
> A WSDL binding requires `wsdl_operation` plus a resolved asset/version. Author either the by-name pair (`wsdl_asset` + optional `wsdl_version`) — which the platform rewrites to `wsdl_asset_id` / `wsdl_version_id` on save — or the stable IDs directly. Versions are immutable: a bound tool keeps calling its pinned version until you repoint it, so a WSDL update never silently changes behavior.

If a WSDL construct is unsupported, author a manual SOAP tool with an explicit `body` template instead — the binding fields and a manual body are mutually exclusive per tool.

### Request variants

For endpoints that vary by condition, `request_variants` selects a request shape at call time based on a `when` expression. Each variant can override the endpoint, method, headers, query params, and body.

```yaml theme={null}
TOOLS:
  submit(order: object, region: string) -> {ref: string}
    type: http
    endpoint: "https://api.example.com/us/submit"
    method: POST
    request_variants:
      - name: eu
        when: region == "EU"
        endpoint: "https://api.eu.example.com/submit"
        body_type: json
      - name: default
        default: true
```

***

## MCP tools

MCP (Model Context Protocol) tools connect to external MCP servers that expose tools dynamically. The runtime handles protocol negotiation, transport, and tool discovery.

```yaml theme={null}
TOOLS:
  web_search(query: string) -> {results: {title: string, url: string, snippet: string}[]}
    description: "Search the web"
    type: mcp
    server: "brave-search"
```

### MCP binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"mcp"` | Yes | -- | Declares this as an MCP tool |
| `server` | `string` | Yes | -- | MCP server name (resolved from runtime configuration) |
| `server_tool` | `string` | No | Tool name | Tool name on the MCP server (if different from the ABL tool name) |
| `output_schema` | JSON object (string) | No | -- | JSON Schema describing the tool's result, as a single JSON object literal — for example `{"type": "object", "properties": {...}}`. Invalid JSON is dropped ([`TOOL_OUTPUT_SCHEMA_INVALID`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#tool_output_schema_invalid)). |
| `headers` | `Record<string, string>` | No | *none* | Per-call headers, supporting `{{config.X}}` / `{{session.X}}` templates. |

### Server configuration

The `server` value is a logical name that maps to an MCP server configuration in the project's runtime settings. Server configuration (transport type, connection URL, authentication and mTLS profiles) is managed at the project level, not in the ABL file.

The platform supports these MCP transport types.

| Transport | Description |
| - | - |
| `stdio` | Standard input/output (for local MCP server processes) |
| `http` | HTTP-based transport (Streamable HTTP) |
| `websocket` | WebSocket-based transport |

#### Variable namespaces and placeholders

An MCP server can link project variable namespaces. In Studio, choose them in the registration dialog or on the Configuration tab. The API field is `variableNamespaceIds`: up to 20 namespace IDs from the same project. An update that omits the field keeps the current links. An empty array removes the restriction. A server with no links behaves as before.

* **Placeholders.** `{{env.NAME}}` (environment variable) and `{{config.NAME}}` (project config variable) resolve in the server URL, inline authentication fields and shared headers. The linked namespaces scope the lookup. Environment values win over global values.
* **When.** Values resolve when the runtime connects or runs the tool. Resolved secrets are never written back to the server configuration.
* **Limits.** A secret config variable is rejected in a URL field. Use it in authentication or a header. The runtime checks the URL for SSRF after resolution. A linked variable that is not available stops the connection or tool call.
* **Headers.** Tool headers override shared server headers of the same name, ignoring case. Auth profile headers override custom server headers.
* **Deleting a namespace.** The platform rejects deleting a namespace that an MCP server uses. Unlink or reassign the server first.
* **Project export and import.** Exports carry namespace names, not IDs. Import maps them to the destination project. Secret values are not exported. Set them in the destination before the server can connect.

### Dynamic tool discovery

MCP servers can expose multiple tools. When you declare an MCP tool in ABL, you bind a specific tool from the server. If the tool name on the MCP server differs from the tool name in your ABL file, use `server_tool:` to specify the server-side name.

```yaml theme={null}
TOOLS:
  search(query: string) -> {results: object[]}
    description: "Search using Brave"
    type: mcp
    server: "brave-search"
    server_tool: "brave_web_search"
```

***

## Lambda tools

Lambda tools invoke cloud serverless functions. The function name is a logical identifier resolved to an actual endpoint (ARN, URL) at runtime through the project's function registry.

```yaml theme={null}
TOOLS:
  process_document(document_url: string, format: string) -> {text: string, pages: number}
    description: "Extract text from a document"
    type: lambda
    function: "document-processor"
    runtime: "nodejs20"
    timeout: 30000
```

### Lambda binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"lambda"` | Yes | -- | Declares this as a lambda tool |
| `function` | `string` | Yes | -- | Logical function name (resolved at runtime) |
| `runtime` | `string` | No | *none* | Runtime hint (for example. `"nodejs20"`, `"python3.12"`) |
| `timeout` | `number` | No | Platform default | Override timeout for this function in milliseconds |

***

## Async webhook tools

Async webhook tools send an HTTP request with a callback URL injected into the payload. The external system processes the request asynchronously and posts the result back to the callback URL when complete.

```yaml theme={null}
TOOLS:
  generate_report(report_type: string, date_range: string) -> {report_url: string, status: string}
    description: "Generate a financial report (processed asynchronously)"
    type: async_webhook
    endpoint: "https://reports.internal/api/generate"
    method: POST
    callback_url_field: "callbackUrl"
    timeout_seconds: 3600
```

### Async webhook binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"async_webhook"` | Yes | -- | Declares this as an async webhook tool |
| `endpoint` | `string` | Yes | -- | URL to send the initial request |
| `method` | `"POST"` , `"PUT"` , `"PATCH"` | Yes | -- | HTTP method |
| `headers` | `Record<string, string>` | No | *none* | Custom HTTP headers |
| `callback_url_field` | `string` | No | `"callbackUrl"` | Dot-path in the request body where the callback URL is injected |
| `timeout_seconds` | `number` | No | `3600` | Timeout in seconds for the async callback response |

***

## Workflow tools

Workflow tools invoke a durable workflow on the workflow engine. Use these for long-running, stateful orchestrations (waits, polling, human approval, multi-hour processes) that shouldn't run inside the stateless agent runtime.

```yaml theme={null}
TOOLS:
  start_onboarding(customer_id: string, plan: string) -> {run_id: string, status: string}
    description: "Kick off the customer onboarding workflow"
    type: workflow
    workflow_id: "customer-onboarding"
    mode: async
    timeout_ms: 60000
    param_mapping:
      customerId: customer_id
      selectedPlan: plan
```

### Workflow binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"workflow"` | Yes | -- | Declares this as a workflow tool. |
| `workflow_id` | `string` | Yes | -- | Logical workflow identifier. Version routing comes from the deployment manifest. |
| `mode` | `"sync"` , `"async"` | No | `"sync"` | `sync` waits for completion; `async` starts the run and returns a handle. |
| `timeout_ms` | `number` | No | *none* | Maximum time to wait, in milliseconds, up to 300,000. With no value, the runtime waits 60 seconds. Supports `{{config.X}}` interpolation. |
| `param_mapping` | `Record<string,string>` | No | *none* | Maps workflow input fields to tool parameters (workflow key → tool parameter). |

> [!NOTE]
>
> The workflow must exist in the same tenant/project; this is validated at compile time. Legacy `workflow_version` / `trigger_id` fields are no longer used and are silently ignored.

> [!NOTE]
>
> HTTP tools use `timeout`. Workflow tools use `timeout_ms`. Both take milliseconds. A value such as `"30s"` is rejected.

### Sync and async

| Mode | What the agent receives | Use it for |
| - | - | - |
| `sync` (default) | The workflow's output, in the same turn, when the run completes. If `timeout_ms` passes first, the call fails. | Anything the agent needs to answer right away. |
| `async` | `{executionId, status: "running"}` straight away. The workflow's output is not returned. | Long-running work the agent does not wait for. |

* With `async`, the agent reads the result later with the `check_workflow_status` tool. The runtime adds that tool when the agent has at least one async workflow tool.
* A `SECURE_INPUT` step can deliver only to a sync workflow tool. An async one is a compile error (`SECURE_INPUT_WORKFLOW_TOOL_NOT_SYNC`).
* Studio, the tools API, and the Arch MCP `platform_workflows` `create_tool` action all create a sync tool unless you choose async. Arch MCP tools 1.6.0 to 1.8.0 were the exception: their `create_tool` created an async tool when `toolMode` was left out. With those versions, pass `toolMode: "sync"`.
* A tool keeps the mode it was saved with. To change an existing tool, edit its DSL: write `mode: sync`, or remove the `mode` line.

## Missing values in CALL arguments

A `CALL` argument (`WITH` or a named inline argument) is a value expression, evaluated against the session when the call runs. A key missing from a record reads as `null` inside it, so `COALESCE`, ternaries, object and list literals, and arithmetic over a missing path give their documented value. See [Missing paths in value expressions](https://koreai.mintlify.site/agent-platform/abl/reference/expressions-and-functions.md#missing-paths-in-value-expressions).

```yaml theme={null}
reply_list:
  REASONING: false
  CALL: od_list_send_tool
    WITH:
      kind: kind
      items: COALESCE(brief.output.orderList, order.list.items)
      session: {"language": COALESCE(ctx.output.language, ""), "channel": COALESCE(ctx.output.channel, "voice")}
    AS: listResult
  THEN: done
```

An argument is **left out of the tool input** when it has no value:

| Argument | Tool input | Trace |
| - | - | - |
| A single path that is not set: `name: order.list.kind` | `name` left out | none: there is no value to send |
| An expression that cannot be evaluated: `n: kind + 1` | `n` left out | `warning`, code `call_argument_unresolved` |
| `COALESCE(order.list.kind, "")` | `""` | none |
| `order.list.kind IS SET ? order.list.kind : "none"` | `"none"` | none |

An expression cannot be evaluated when, for example, it adds text to a number, its ternary condition is not `true` or `false`, or it uses bracket access on a missing key. The runtime never sends a partial reading of it.

> [!WARNING]
>
> **Behavior change.** An argument that cannot be evaluated is now left out instead of sent as a partial value. Wrap the path in `COALESCE(path, default)` to send an explicit default.

The `call_argument_unresolved` warning carries `argument`, `celCode` (for example `no_such_overload` or `no_such_key`), `step` (when the call runs in a FLOW step), and `tool`. It never contains the expression or any value. FLOW step CALLs, hook CALLs, and tool `on_result` / `on_error` CALLs all emit it. A tool `process` field or a `TRANSFORM` `MAP` field that cannot be evaluated emits `value_expression_unresolved` instead, with `surface` (`process_before`, `process_after`, or `transform_map`), `field`, `celCode`, and `tool` or `step`. A `MAP` field is reported once per run.

### Empty values for required parameters

An empty literal (`""` or `''`) bound to a required parameter counts as a missing value. The runtime does not call the tool. The step takes its failure route, and the `CALL` result carries `__errorCode` `TOOL_REQUIRED_INPUT_MISSING` with the names of the missing parameters. A `tool_precondition_failed` trace event records the block. It names the tool, step, and fields, never their values. A write tool can still take a gathered field of the same name when the call runs.

```yaml theme={null}
TOOLS:
  lookup_order(order_id: string, note?: string) -> object
    description: "Look up an order"

FLOW:
  find_order:
    REASONING: false
    CALL: lookup_order
      WITH:
        order_id: ""
        note: ""
      AS: orderResult
    ON_FAIL: handle_missing_order
```

Here `order_id` is required, so the compiler warns with [`CALL_WITH_REQUIRED_PARAM_EMPTY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#call_with_required_param_empty). `note` is optional, so its empty value is sent and gets no warning.

The warning does not cover a parameter that:

* has a default value, or a source other than the model
* is hidden from the model
* is filled by a `process.before` value
* is `session_id`, `tenant_id`, or `project_id`, which the runtime always supplies

To fix it, pick one:

* Declare the parameter optional (`order_id?: string`) when an empty value is valid.
* Bind a value that is never empty.
* Branch on `__errorCode == "TOOL_REQUIRED_INPUT_MISSING"` in the failure branch to handle the missing input.

***

## SearchAI tools

SearchAI tools query a SearchAI knowledge base (KB) index, letting an agent ground its answers in the indexed content.

```yaml theme={null}
TOOLS:
  search_policies(query: string) -> {results: object[]}
    description: "Search the HR policy knowledge base"
    type: searchai
    index_id: "hr-policies-v2"
    kb_name: "HR Policies"
    search_instructions: "Prefer the most recent policy version when duplicates exist."
```

### SearchAI binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"searchai"` | Yes | -- | Declares this as a SearchAI tool. |
| `index_id` | `string` | Yes | -- | SearchAI KB index to query. |
| `kb_name` | `string` | No | -- | Display name for the knowledge base. |
| `search_instructions` | `string` | No | -- | Extra instructions injected into the search/classification prompt. |
| `retrieval_profile` | `string` | No | -- | Set to `object-aware` to use object-aware retrieval against the KB index. |
| `kb_fast_path` | `"on"` \| `"off"` | No | -- | `on` runs this search before the model is called (pre-search); `off` or omitted leaves it to the model to call the tool itself. It applies only to non-supervisor agents with a single associated tool. For agents with multiple associated tools or supervisor agents, the flag is ignored. |

> [!NOTE]
>
> SearchAI tools are tenant-scoped; the tenant binding is applied by the platform. Don't hardcode a `tenant_id` in shared/exported definitions.

### Per-agent overrides and business rules

`search_instructions`, `kb_fast_path`, and `business_rules` are **per-agent** properties: when several agents share one underlying KB tool (defined once as a project tool), each agent can declare its own values for these three directly on its own `TOOLS:` entry, and that agent's declaration is what applies to its searches — it doesn't change the tool for any other agent sharing the same KB.

`business_rules` governs what a search returns — restricting results to certain sources, boosting or lowering ranked values, or hiding content entirely — without changing the agent's prompt or the underlying index. Author it as a `business_rules: |` block holding a JSON array, parallel to `search_instructions`:

```yaml theme={null}
TOOLS:
  search_policies(query: string) -> {results: object[]}
    description: "Search the HR policy knowledge base"
    type: searchai
    index_id: "hr-policies-v2"
    search_instructions: "Prefer the most recent policy version when duplicates exist."
    business_rules: |
      [
        {
          "id": "hide_drafts",
          "when": { "kind": "always" },
          "then": {
            "hide": [{ "field": "status", "operator": "eq", "value": "draft" }]
          }
        },
        {
          "id": "boost_official_pricing",
          "when": { "kind": "intent", "anyOf": ["pricing_question"] },
          "then": {
            "boost": [{ "field": "source", "value": "official_pricing_guide", "weight": 2.5 }]
          }
        }
      ]
```

**Rule shape.** Each entry in the array is an object:

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique within the array — appears in traces so you can tell which rule fired. |
| `when` | `object` | Yes | The condition that must hold for the rule to apply. See below. |
| `then` | `object` | Yes | The effect(s) to apply when `when` holds. See below. |
| `label` | `string` | No | A human-readable name, for your own reference. |
| `enabled` | `boolean` | No | Set `false` to author a rule without it taking effect yet. |
| `priority` | `number` | No | Evaluation order hint among rules that could both fire. |
| `relaxable` | `boolean` | No | Whether this rule's filters may be relaxed if they leave zero results. |

**`when` (one condition kind):**

| `kind` | Shape | Matches when |
| - | - | - |
| `always` | `{ "kind": "always" }` | Every search. |
| `intent` | `{ "kind": "intent", "anyOf": [...ids], "minConfidence"?: 0-1 }` | The classified caller intent is one of `anyOf`. |
| `query` | `{ "kind": "query", "operator": "contains"\|"not_contains", "value"?: string, "anyOf"?: [...phrases] }` | The search query text contains (or doesn't contain) the phrase, or any phrase in `anyOf` — declare exactly one of `value`/`anyOf`. |
| `value` | `{ "kind": "value", "name": string, "operator": "eq"\|"neq"\|"gt"\|"gte"\|"lt"\|"lte"\|"in"\|"not_in"\|"exists"\|"not_exists", "value"?: ... }` | A named caller/session value compares as specified. |

**`then` (one or more effects):**

| Key | Shape | Effect |
| - | - | - |
| `filters` | `[{ "field", "operator", "value" }, ...]` (or a `{ "mode": "all"\|"any", "filters": [...] }` group) | Restrict results to matching documents. `operator` is one of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`, `not_contains`, `exists`, `not_exists`. |
| `hide` | Same filter shape as `filters` | Exclude matching documents from the results entirely. |
| `boost` | `[{ "field", "value", "weight" }, ...]` | Increase the ranking of documents where `field` equals `value`, by `weight`. |
| `lower` | Same shape as `boost` | Decrease ranking instead of increasing it. |

> [!WARNING]
>
> Validation differs by where the rules are declared. On the **project tool's own**`business_rules`, an invalid rule set (bad JSON, or any rule failing the grammar above) fails that tool to load entirely — loud, by design, so ungoverned results are never served silently. On an **agent's own override** of `business_rules`, an invalid rule set is instead dropped with a logged warning, and the agent falls back to whatever the shared project tool already declares — a mistake in one agent's override can't take down every agent sharing that KB tool. Either way, a rule that fails validation is never partially applied.

***

## Table tools

Table tools perform structured CRUD against an **Agent Table** — a project-, user-, or session-scoped datastore.

```yaml theme={null}
TOOLS:
  save_note(title: string, body: string) -> {id: string}
    description: "Store a customer note"
    type: table
    table: customer_notes
    scope: end_user
    operations: [get, query, insert, update]
```

### Table binding properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `"table"` | Yes | -- | Declares this as a table tool. |
| `table` | `string` | Yes | -- | Primary table slug (`^[a-z_][a-z0-9_]*$`). `table_name` is an alias. |
| `scope` | `string` | No | -- | `project`, `end_user`, or `session`. The scope key is derived from trusted session context, never authored in the binding. |
| `operations` | `string[]` | No | read-only (`get`/`query`/`count`) | Allowed operations: `get`, `query`, `count`, `insert`, `update`, `delete`, `upsert`, `bulkInsert`, `bulkUpsert`. |
| `tables` | `string[]` | No | -- | Additional tables to JOIN (max 8). |
| `query_template` | `string` | No | -- | Optional query template. |

***

## Tool file imports

You can organize the tool definitions into reusable `.tools.abl` files and import it into agent documents. This lets you share tool definitions across multiple agents.

### Tool file format

A `.tools.abl` file starts with a `TOOLS:` section that can include shared defaults:

```yaml theme={null}
TOOLS:
  base_url: "https://api.hotels.com/v1"
  auth: bearer
  timeout: 5000
  retry: 3

  search_hotels(destination: string, checkin: date, checkout: date) -> Hotel[]
    type: http
    endpoint: "/search"
    method: POST
    description: "Search available hotels"

  get_hotel(hotel_id: string) -> Hotel
    type: http
    endpoint: "/hotels/{hotel_id}"
    method: GET
    description: "Get hotel details by ID"
```

### Shared defaults

The following defaults can be set at the top of a `.tools.abl` file and apply to all tools in the file.

| Default | Type | Description |
| - | - | - |
| `base_url` | `string` | Base URL prepended to all relative endpoint paths |
| `auth` | `string` | Default auth type for all tools |
| `timeout` | `number` | Default timeout in milliseconds |
| `retry` | `number` | Default retry count |
| `retry_delay` | `number` | Default retry delay in milliseconds |
| `rate_limit` | `number` | Default rate limit (requests per second) |
| `headers` | `Record<string, string>` | Default headers applied to all tools |

### Import syntax

Import tools from a `.tools.abl` file into an agent using the `file:` directive within the `TOOLS:` section.

```yaml theme={null}
TOOLS:
  file: "./tools/hotels-api.tools.abl" [search_hotels, get_hotel]
```

The import specifies:

* The path to the `.tools.abl` file (relative to the agent file)
* An optional list of specific tool names to import (in brackets). If omitted, all tools from the file are imported.

Project bundle import can also synthesize tool stubs from inline agent `TOOLS:` signatures during apply. That keeps imported agents compileable even when the bundle didn't include companion `.tools.abl` files, and the next export writes those synthesized stubs back out as `tools/<name>.tools.abl`.

### Example

Given the file `tools/hotels-api.tools.abl`.

```yaml expandable=true theme={null}
TOOLS:
  base_url: "https://api.hotels.com/v1"
  auth: bearer

  search_hotels(destination: string, checkin: date, checkout: date) -> Hotel[]
    type: http
    endpoint: "/search"
    method: POST
    description: "Search available hotels"

  get_hotel(hotel_id: string) -> Hotel
    type: http
    endpoint: "/hotels/{hotel_id}"
    method: GET
    description: "Get hotel details by ID"

  get_hotel_reviews(hotel_id: string, limit: number = 10) -> Review[]
    type: http
    endpoint: "/hotels/{hotel_id}/reviews"
    method: GET
    description: "Get reviews for a hotel"
```

An agent file can import selected tools:

```yaml theme={null}
AGENT: Hotel_Search

TOOLS:
  file: "./tools/hotels-api.tools.abl" [search_hotels, get_hotel]

  # Additional agent-specific tools
  check_availability(hotel_id: string, dates: string) -> {available: boolean}
    description: "Check real-time availability"
    type: http
    endpoint: "/api/availability"
    method: POST
```

***

## Tool features

### Confirmation

The `confirmation:` block configures whether the agent should ask the user for confirmation before executing a tool. This is particularly important for tools with side effects (for example. executing a payment, deleting a record).

```yaml theme={null}
TOOLS:
  execute_payment(amount: number, recipient: string) -> {confirmation_id: string}
    description: "Execute a payment"
    type: http
    endpoint: "/api/payments"
    method: POST
    confirmation:
      require: always
      immutable_params: [recipient]
```

| Property | Type | Default | Description |
| - | - | - | - |
| `require` | `"always"` , `"never"` , `"when_side_effects"` | *none* | When to require user confirmation |
| `immutable_params` | `string[]` | *none* | Parameters that can't be changed after confirmation |
| `consent_required_in` | `"conversation"` , `"explicit_prompt"` | *none* | Where consent must be obtained. |
| `consent_scope` | `string[]` | *none* | Consent scopes required before executing. |

\[!NOTE] Without a `consent_action`, a required confirmation's question is built from the first sentence of the tool's `description` ("Shall I `<description>`…?"). A `description` that opens with a noun phrase or a third-person verb reads as a broken question (compile warning [`TOOL_CONFIRMATION_PHRASE_NOT_ACTION`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#tool_confirmation_phrase_not_action)) — write the description starting with an imperative verb ("Transfer the amount to the beneficiary"), or set `consent_action` explicitly to control the confirmation wording.
\| `consent_action`      | `string`                                         | *none*  | Named consent action to trigger.                     |
\| `consent_fallback`    | `"explicit_prompt"` , `"block"`                  | *none*  | What to do if consent isn't granted.                |

Only `always`, `never`, and `when_side_effects` turn on a confirmation rule. Any other value, such as `yes`, means no confirmation.

#### What the customer is asked

When a call needs approval, the customer sees a plain-language question in chat and in cascaded voice (speech-to-text, reasoning, text-to-speech). The runtime builds it from the `tool_confirmation_request` message, your `consent_action` (if you set one), and a readable label for each parameter value. The default wording is:

```yaml theme={null}
Please confirm before I go ahead{{action_suffix}}.{{details}}

Shall I proceed?
```

For the `create_order` tool with `consent_action: "create order"`, the customer sees:

```yaml theme={null}
Please confirm before I go ahead (create order).

- Account id: 4411
- Amount: 25

Shall I proceed?
```

* `consent_action` appears in parentheses after "go ahead". Set it to a short, customer-friendly phrase such as "create order". If you leave it out, the parenthetical is omitted.
* Each parameter appears on its own line with a humanized label: `account_id`, `accountId`, and `account-id` all display as "Account id". Empty values are skipped, and values of sensitive gather fields are masked.
* The tool name, parameter lock markers (`immutable_params`), and the instructions the runtime gives the model are never shown to the customer.
* If the tool already ran earlier in the conversation and the agent is about to repeat it, the customer is asked "I already completed this earlier in our conversation (create order). Would you like me to do it again?" instead. Override it with the `tool_confirmation_duplicate_effect` key.

To change the wording, override `tool_confirmation_request` in the agent's [`MESSAGES:`](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks#messages) block. The template supports `{{action_suffix}}` and `{{details}}`:

```yaml theme={null}
MESSAGES:
  tool_confirmation_request: "Before I continue{{action_suffix}}, please check these details:{{details}}\n\nIs that correct?"
```

> [!NOTE]
>
> Realtime speech-to-speech sessions leave approval to the model provider, so this wording does not apply there.

### State authority and provided fields

The `effect` property declares a tool's authority over session state, and `provides` lists the fields the tool is authoritative to supply. These help the runtime reason about which values a tool is allowed to write.

```yaml theme={null}
TOOLS:
  set_shipping_address(address: object) -> {saved: boolean}
    description: "Persist the customer's shipping address"
    type: http
    endpoint: "/api/shipping-address"
    method: PUT
    effect: state_write          # read_only | state_write | side_effect
    provides: [shipping_address, shipping_zone]
```

| Property | Type | Values | Description |
| - | - | - | - |
| `effect` | `string` | `read_only`, `state_write`, `side_effect` | The tool's authority over external/session state. |
| `provides` | `string[]` | -- | Fields this tool is authoritative to provide. |

> [!NOTE]
>
> `effect` is optional by default, but a project can opt into a **strict realtime effect metadata mode** at compile time. Under that mode, every non-system tool must declare an explicit `effect` — an undeclared one is a compile error ([`REALTIME_TOOL_EFFECT_REQUIRED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#realtime_tool_effect_required)): *"Tool must declare an explicit effect (read\_only, state\_write, or side\_effect) for strict realtime effect metadata mode."* This lets the compiler safely select the guarded scheduler lane a tool runs on. Strict mode is off by default for backward compatibility; declare `effect` on every tool to stay compatible with it regardless.

> [!NOTE]
>
> When neither `effect` nor `hints.side_effects` is declared, the runtime infers one: for an HTTP tool, `GET`, `HEAD`, and `OPTIONS` default to read-only and every other method defaults to side-effecting; SearchAI and read-only table bindings default to read-only; any other non-HTTP tool defaults conservatively to side-effecting. An explicit `effect`/`side_effects` always wins over the inferred default.

> [!WARNING]
>
> A workflow or MCP tool with no declared effect counts as a write. It's held while another action waits for a confirmation. Declare `effect: read_only` on every read tool.

### Concurrent tool execution

A reasoning agent works in steps. At each step, the model chooses which tools to call. When it requests more than one tool in the same step, the platform runs them at the same time. A tool whose arguments depend on another tool's result can't be requested until that result exists, so it is naturally called in a later step.

```yaml theme={null}
TOOLS:
  get_profile(customer_id: string) -> {name: string, tier: string}
    description: "Fetch the customer profile"
    effect: read_only

  get_orders(customer_id: string) -> {last_order_id: string, orders: array}
    description: "Fetch recent orders"
    effect: read_only

  get_delivery_status(order_id: string) -> {status: string, eta: string}
    description: "Get delivery status for one order"
    effect: read_only

INSTRUCTIONS: |
  For an account and order update:
  1. Call get_profile and get_orders together in the same step.
  2. When get_orders returns, call get_delivery_status with its last_order_id.
  3. Then answer using all three results.
```

`effect: read_only` marks a tool as a pure lookup. A read-only tool executes immediately: it is never held back while a separate call is waiting on customer [confirmation](#confirmation).

The model decides which tools to request together, so `INSTRUCTIONS` is what makes the grouping consistent: tell it which calls are independent and can run together, and which call needs another call's result first. Instructions guide this grouping; they don't enforce it, since the model still chooses what to call at each step. For a fixed, guaranteed execution order, attach the calls as a [workflow tool](#workflow-tools) instead and define the order on the workflow canvas. See [Build workflow logic](https://koreai.mintlify.site/agent-platform/workflows.md#build-workflow-logic) for how nodes on the same branch run concurrently.

> [!NOTE]
>
> This concurrency is automatic and needs no extra configuration. It's unrelated to a workflow tool's `mode` property (`sync` or `async`), which controls whether the calling agent waits for a long-running workflow run to finish, not whether multiple tool calls run together.

To confirm which calls ran together, open the session trace: tool calls that ran at the same time show overlapping start and end times.

### Result compaction

The per-tool `compaction:` block controls how this tool's results are compacted in conversation history (independent of the agent-wide `EXECUTION.compaction` policy).

```yaml theme={null}
TOOLS:
  search_catalog(query: string) -> {items: object[]}
    type: http
    endpoint: "/api/catalog/search"
    method: GET
    compaction:
      essential_fields: [items.id, items.name, items.price]
      max_description_length: 500
      summary_timeout_ms: 3000
```

| Property | Type | Description |
| - | - | - |
| `essential_fields` | `string[]` | Fields to preserve verbatim when compacting this tool's result. |
| `max_description_length` | `number` | Maximum characters kept for descriptive fields. |
| `summary_timeout_ms` | `number` | Timeout for LLM summarization of this tool's result. |
| `max_search_tokens` | `number` | Token budget for SearchAI knowledge-base result context sent to the LLM. |

### MODEL\_CONTEXT on a tool result

An optional `MODEL_CONTEXT` block on a tool chooses the view of its result supplied to **later model calls** — independent of [result compaction](#result-compaction) above, which is an automatic LLM-assisted summarization fallback for oversized results. `MODEL_CONTEXT` is an author-declared, deterministic replacement that always applies, regardless of result size.

```yaml theme={null}
TOOLS:
  list_products(category: string) -> object
    type: http
    endpoint: "/api/products"
    method: GET
    model_context:
      fields: [products[].id, products[].name, total]
```

| Property | Type | Description |
| - | - | - |
| `fields` | `string[]` | Result paths to keep, 1-64 entries. Paths may traverse arrays with `[]` (for example `products[].id`); each segment is an identifier, at most 16 segments deep. No path may be a prefix of (or overlap) another. |
| `template` | `string` | A text template (`{{}}` interpolation against `result`) rendered instead of the raw result — for example `"{{result.total}} products found"`. |

`fields` and `template` are mutually exclusive — choose one. The full, unprojected tool result is still available everywhere else: `CALL AS`, `ON_RESULT`, assignments, response templates, and client delivery. Omit `MODEL_CONTEXT` entirely to keep the historical full-result behavior. An invalid or empty policy (both or neither of `fields`/`template`, an empty/overlapping `fields` list, or an empty `template`) fails validation (`MODEL_CONTEXT_INVALID`); if a *valid* policy can't be projected at runtime (a path doesn't resolve, say), the model receives a bounded "unavailable" marker instead of the full result — it never silently falls back to exposing everything.

> [!NOTE]
>
> A rendered, non-empty view is **preserved exactly** through later history compaction and summarization, evaluated once and reused on later turns rather than re-rendered — see [MODEL\_CONTEXT on a response](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#model_context-on-a-response) for the full preservation contract and the `AUTHORED_MODEL_CONTEXT_CAPACITY_EXCEEDED` capacity limit, which applies to both forms identically.

> [!NOTE]
>
> Legacy `.agent.abl` format: `MODEL_CONTEXT:` with nested `FIELDS:`/`TEMPLATE:` keys, directly under the tool signature. `MODEL_CONTEXT` can also sit beside a FLOW step's `RESPOND` or a `COMPLETE` condition's `RESPOND` — see [MODEL\_CONTEXT on a response](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#model_context-on-a-response) for that (separate) use.

### Input/output transforms (`process`)

The `process:` block defines pure input (`before`) and output (`after`) transform stages that run around the tool call — remapping parameters, enforcing preconditions, and reshaping results.

```yaml theme={null}
TOOLS:
  quote_fx(amount: number, from: string, to: string) -> {converted: number}
    type: http
    endpoint: "/api/fx/quote"
    method: POST
    process:
      before:
        params:
          amount_cents: "amount * 100"
        require: [amount > 0]
        on_fail: reask("Please provide a positive amount.")
      after:
        result:
          converted: "result.amount_cents / 100"
        on_fail: warn("Could not normalize the quote.")
```

`before` supports `params` (computed parameter map), `require` (precondition expressions), `on_fail` (one of `block("msg")`, `reask("msg")`, `warn("msg")`, `use_original`, `fallback("msg")`), and `use` (a named transform). `after` supports `result` (output remapping) and `on_fail`.

> [!WARNING]
>
> Don't put a `before``require` check on a runtime input (a parameter with `default_source: runtime`). The `before` stage runs before runtime inputs are filled.

### Result caching

`cacheable: true` on a read-only tool lets the Runtime reuse the result of an identical call in the same conversation. The backend is not called again. It is the only switch. A tool without it is never cached.

```yaml theme={null}
TOOLS:
  get_exchange_rate(from: string, to: string) -> {rate: number}
    description: "Get current exchange rate"
    type: http
    endpoint: "https://fx.example.com/api/fx/rate"
    method: GET
    hints:
      cacheable: true
      side_effects: false
      latency: fast
    cache_ttl_ms: 120000
    cache_invalidated_by: [book_transfer]
```

An agent-level tool with no project tool binding counts as writing, unless it states `side_effects: false` or `effect: read_only`, as above. A bound tool follows its binding. For example, an HTTP `GET` is read-only.

In a project tool file, write `cacheable: true` under the tool, next to `cache_ttl_ms` and `cache_invalidated_by`.

| Property | Type | Default | Description |
| - | - | - | - |
| `cacheable` | `boolean` or variable | *none* | Turns caching on for this tool. A variable reference makes the value depend on the environment. See [Set caching with variables](#set-caching-with-variables). |
| `cache_ttl_ms` | `number` or variable | `60000` | How long a stored result stays valid, from 1000 to 3600000 ms. When the agent and the tool file both set it, the smaller value applies. |
| `cache_invalidated_by` | `string[]` | All write tools | Only these tools clear this tool's cached results. Each name must be a write tool of the project. |

#### Set caching with variables

Write `cacheable` or `cache_ttl_ms` as one `{{env.NAME}}` or `{{config.NAME}}` reference. Each environment can then use its own value, and you can change the value without publishing the agent again.

```yaml theme={null}
cacheable: {{env.ORDERS_CACHE_ENABLED}}
cache_ttl_ms: {{config.ORDERS_CACHE_TTL_MS}}
```

* The runtime reads the variables on every call.
* A tool with `cacheable: {{env.NAME}}` caches only on a call where the variable reads `true`. Any other value turns caching off for that call.
* A `cache_ttl_ms` variable must read as a whole number. A value out of range is moved to the nearest bound. A value that is not a whole number keeps the default lifetime.
* The reference must be the whole value. Text around it, or a name that is not `env` or `config`, is not a valid `cacheable` value and caching stays off. The compiler reports `TOOL_CACHE_INVALID`.
* If the runtime cannot read a variable, that call runs the tool live and caches nothing.
* In Studio, the **Result caching** section of the project tool page sets the same values and lists the write tools that clear the cache. The Debug panel and the Sessions page mark cached calls and show their age.

What is reused, and for how long:

* A result is reused only in the same conversation, for the same caller identity, credential owner, deployment, tool definition and arguments. A child agent shares its parent's conversation.
* Every write tool in the conversation clears the cached results before and after it runs. With `cache_invalidated_by`, only the listed tools clear this tool's results.
* A verified identity change clears every cached result. The results are deleted when the session ends.
* The Runtime does not store results that report an error, results larger than 64 KiB, or results that are not plain JSON. A conversation keeps at most 64 results.
* A reused result goes through the same output guardrails, PII redaction and `on_result` mapping as a live one.
* Simulations, the public Tools API and tool tests in Studio always call the backend.

Only read-only tools can be cached. These tools compile with the warning `TOOL_CACHE_INELIGIBLE` when authored with `cacheable: true`. They always call the backend:

* a tool that writes (an HTTP `POST`, `PUT`, `PATCH` or `DELETE`, a write effect, or `side_effects: true`);
* an MCP, lambda,  or workflow tool without `effect: read_only`;
* a workflow tool that does not run synchronously;
* a connector, platform or async webhook tool.

`TOOL_CACHE_INVALID` reports a `cache_ttl_ms` that is not a whole number or is out of range, and a `cache_invalidated_by` entry that is not a write tool of the project. For a bad `cache_ttl_ms`, the compiler uses the default or the nearest bound. Studio rejects the save. The compiler warns.

Caching starts at the next compile of the agent: on publish, in preview, and when a pinned deployment reloads. Each `tool_call` trace shows the outcome in `cache.status` (`hit`, `miss_stored`, `miss_not_stored`, `bypass` or `error`). It also shows a reason, the age of a reused result and a short key digest. Argument values never appear.

### PII access

The `pii_access:` property declares what level of personally identifiable information (PII) a tool can access.

```yaml theme={null}
TOOLS:
  verify_identity(ssn_last4: string, dob: string) -> {verified: boolean}
    description: "Verify customer identity"
    type: http
    endpoint: "/api/identity/verify"
    method: POST
    pii_access: user
```

| Value | Description |
| - | - |
| `original` | Tool can access the original, unredacted PII values (broadest access). |
| `tools` | Tool can access PII data from other tool results |
| `user` | Tool can access user-provided PII |
| `logs` | PII from this tool may appear in logs |
| `llm` | PII from this tool is sent to the LLM |

### Secret scrubbing

An always-on scrubber masks credentials (API keys, bearer tokens, private keys, passwords) in a tool's output. Set `scrub_secrets: false` to opt a specific tool out (for example, when the tool's job is to return a token your flow needs). This is independent of `pii_access`, which governs PII rather than credentials.

```yaml theme={null}
TOOLS:
  mint_token(scope: string) -> {token: string}
    type: http
    endpoint: "/api/token"
    method: POST
    scrub_secrets: false
```

### Context access

The `context_access:` block declares which session context variables a tool reads from and writes to. This enables the runtime to automatically inject context into HTTP requests and apply result values back to session state.

```yaml theme={null}
TOOLS:
  update_profile(name: string) -> {updated: boolean}
    description: "Update user profile"
    type: http
    endpoint: "/api/profile"
    method: PUT
    context_access:
      read: [user.id, user.email]
      write: [user.name, user.updated_at]
```

> [!WARNING]
>
> `context_access` is validated against your `MEMORY:` declarations. A tool that declares a `read` of a **write-only** memory path (or a `write` of a **read-only** path) now fails compilation, and  at runtime a tool is blocked from executing if its declared memory is unavailable. Declare the   matching `MEMORY:` access mode for every path a tool reads or writes.

> [!WARNING]
>
> A `read` key that is only ever populated by this **same tool's own**`on_result`/`on_error` writes can never be satisfied on the tool's first call in a session — that key doesn't exist yet, so the runtime fails the call closed every time. The compiler warns [`TOOL_CONTEXT_ACCESS_READ_BEFORE_WRITE`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#tool_context_access_read_before_write) for this. The key needs a producer other than the tool itself: another tool, `ON_START`, a FLOW `SET`, or a `GATHER` field.

### Store result

The `store_result:` property controls whether the raw tool result blob is stored in the session context. Defaults to `true`.

```yaml theme={null}
TOOLS:
  log_event(event: string) -> {logged: boolean}
    description: "Log an audit event"
    type: http
    endpoint: "/api/audit"
    method: POST
    store_result: false
```

When `store_result` is `true` (the default), the raw result is kept as a session value named `last_<tool>_result`. It surfaces in `## Current Context` on later turns, but only for the agent that called the tool, and cut to 4,000 characters. This is separate from the within-turn shaping in [Result compaction](#result-compaction) and [MODEL\_CONTEXT on a tool result](#model_context-on-a-tool-result) above, which apply only while the call is in progress -- `last_<tool>_result` is what carries the result forward once the turn ends.

> [!WARNING]
>
> Declaring an `on_result: SET:` block on the tool changes the default: `store_result` becomes `false` and `last_<tool>_result` is no longer written, unless `store_result: true` is set explicitly alongside it. If a later turn needs a field from the result, either keep `store_result: true` or capture that field into a session value with `on_result: SET:`.

In reasoning mode, the runtime does not bind result fields to top-level variables such as `refund_id`. Use `on_result: SET:` for that. A scripted `FLOW` `CALL` step differs:

* It also binds the result under the tool's own name (`<tool_name>`), whatever `store_result` says. Without `AS`, it also binds each top-level result field. These bindings serve expressions and later steps.
* When the step's `AS` name is declared in the agent's memory, that declaration governs the result's automatic model context. The result appears once, in the memory section, or not at all with `MODEL_VISIBLE: false`. An equal `last_<tool_name>_result` or `<tool_name>` binding from the same tool is left out of `## Current Context`. A different result, such as one from a later call to the same tool, stays visible.

Retained working state is not automatic model visibility. A tool result from an earlier agent, including a FLOW `AS` alias, is not added to the next agent's generated prompt just because it stays in session state or appears in an ancestor's FLOW. Pass the data the next agent needs explicitly. Authorized authored references, memory grants, and authored broad-context prompts keep their existing permissions. Explicit denials and privacy filtering still apply. This rule does not delete result bindings that tools, conditions, assignments, or return handling use.

For the agent-wide limits on how many compacted tool rounds survive in history, and how tool results are compacted across turns, see [Compaction policy overrides](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#compaction-policy-overrides).

### Voice reply policy

On KoreVG pipeline voice, a tool on a reasoning agent can declare a `VOICE` block with `BARGE_IN` and `STREAMING`. The block governs the model reply generated in the same turn after the tool returns a successful result.

```yaml theme={null}
TOOLS:
  get_payment_status(ref: string) -> object
    description: "Look up the status of a payment"
    type: http
    endpoint: "https://payments.example.com/api/status"
    method: GET
    VOICE:
      BARGE_IN: disallow
      STREAMING: false
```

* **Keys.** `BARGE_IN` is `allow` or `disallow`, in lowercase. `STREAMING` is `true` or `false`. Any other key warns with [`TOOL_VOICE_UNKNOWN_KEY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#tool_voice_unknown_key) and is ignored.
* **Which reply.** Only the reply after a successful result. A tool error does not apply the policy.
* **Several tools in one round.** Each key merges on its own. The protective value wins: `disallow` over `allow`, `STREAMING: false` over `true`.
* **Scope.** The reply only. The policy never applies to a later reply, a handoff child or the next turn.
* **Agent and tool file.** When both declare a `VOICE` block for one tool, the agent's value wins for each key.
* **Errors.** An invalid `BARGE_IN` is [`VOICE_INVALID_BARGE_IN`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_invalid_barge_in). A non-boolean `STREAMING` warns with [`VOICE_INVALID_STREAMING`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_invalid_streaming). `LISTENING` is [`VOICE_LISTENING_CALL_LEVEL_ONLY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_listening_call_level_only).
* **Runtime support.** The agent is published with the IR marker `voice_tool_reply_policy`. A runtime without the marker refuses the agent at publish, deploy and activation. Upgrade every runtime first.
* **Scripted steps.** A FLOW step that calls a tool owns its replies. Set the policy on the step or on the nested `VOICE` block of its reply. See [Scoped barge-in](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#scoped-barge-in).

### Reuse secrets across tools (SecretRef)

Some flows need a credential produced by one tool (a one-time token, session key, or OTP) to be sent to a later tool — without ever exposing the raw value to the LLM. SecretRef captures such values into an encrypted, session-scoped **secret vault** and restores them into downstream tool calls.

* **Producer** — the tool that returns the secret declares a `RESULT_SECRETS:` block. Each entry captures a result field into the vault under a key, in the form `<result_path> -> <vault_key> (options)`. Capture works on **every tool type** — HTTP and `workflow` tools can all produce vaulted secrets.
* **Consumer** — a downstream tool declares a `SECRET_ACCESS:` block listing the vault keys it may read, then references them with the `{{_secret.<key>}}` placeholder in its `headers` or `body_template`. Only **HTTP tools** can consume secrets — `{{_secret.<key>}}` resolves in the HTTP request path alone.

> [!WARNING]
>
> Declaring `SECRET_ACCESS` on a non-HTTP tool (a `workflow`) is a **compile error** ([`SECRET_REF_UNSUPPORTED_CONSUMER_TYPE`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#secret_ref_unsupported_consumer_type)): the executor cannot resolve `{{_secret.<key>}}`, so the single-use vault entry would be consumed without delivering the value, and the next authorized consumer would fail with "already used". If you reached for a workflow tool to assemble a variable-length batch payload from a secret, build it directly in an HTTP tool with `{{#each input.<parameter>}}` in the `body_template` instead. (`RESULT_SECRETS` capture is unaffected and still works on workflow tools.)

```yaml expandable=true theme={null}
TOOLS:
  # Producer: capture the OTP token into the vault, never exposing it to the model
  request_otp(account_id: string) -> {otp_token: string, expires_in: number}
    type: http
    endpoint: "/api/otp/request"
    method: POST
    RESULT_SECRETS:
      otp_token -> txn_otp (consumers: [convert_transaction_to_emi], ttl: 300, single_use: true)

  # Consumer: restore the vaulted secret into a header — the model never sees it
  convert_transaction_to_emi(txn_id: string) -> {status: string}
    type: http
    endpoint: "/api/txn/convert"
    method: POST
    SECRET_ACCESS:
      READ: [txn_otp]
    headers:
      X-OTP-Token: "{{_secret.txn_otp}}"
```

#### `RESULT_SECRETS` entry options

| Option | Type | Description |
| - | - | - |
| `<path>` | `string` | Result field to capture (left of `->`). |
| `<vault_key>` | `string` | Vault key to store it under (right of `->`). |
| `consumers` | `string[]` | Tool names allowed to restore this secret. Omit to allow any consumer that declares `SECRET_ACCESS`. |
| `ttl` | `number` | Time-to-live in seconds before the vaulted secret expires. |
| `single_use` | `boolean` | When `true`, the secret is consumed (invalidated) after its first use. |

> [!NOTE]
>
> SecretRef is **fail-closed**: the vault is invisible to the LLM, `{{_secret.X}}` resolves only in `headers` and `body_template` (never forwarded as a query/body param on its own), and an unresolved reference substitutes an empty string — the literal `{{_secret.X}}` placeholder is never sent upstream as a credential.

## Inbuilt tools

Inbuilt tools are tools that the Artemis runtime provides. They cover voice transfers, IVR and DTMF, human-agent handoff, and attachment handling. These tools do not require an HTTP endpoint or a Tool Library entry for them. They are available to all agents by default.

To use these tools, declare them in the `TOOLS:` section of your agent, with its input fields and return type. Then use them as required in the agent.

For the full list of built-in tools and how to use them, see [Inbuilt tools](https://koreai.mintlify.site/agent-platform/inbuilt-tools/index.md).

***

**Related articles:**

* [Language overview](https://koreai.mintlify.site/agent-platform/abl/reference/language-overview.md) -- file structure and syntax.
* [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md) -- `tool_timeout` and model settings in EXECUTION.
* [GATHER](https://koreai.mintlify.site/agent-platform/abl/reference/gather.md) -- information collection (often used alongside tools).
* [FLOW](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md) -- `CALL` action for invoking tools within flow steps.
* [Inbuilt tools](https://koreai.mintlify.site/agent-platform/inbuilt-tools/index.md) -- Inbuilt tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.