---
title: ES|QL tools in Elastic Agent Builder
description: Create custom tools that execute parameterized ES|QL queries for precise data retrieval and analysis.
url: https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/tools/esql-tools
products:
  - Elastic Cloud Serverless
  - Elastic Observability
  - Elastic Security
  - Elasticsearch
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.3, Preview in 9.2
---

# ES|QL tools in Elastic Agent Builder
ES|QL query tools enable you to create parameterized queries that execute directly against your Elasticsearch data. These custom tools provide precise control over data retrieval through templated [ES|QL](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3016/reference/query-languages/esql) statements.

## When to use ES|QL tools

Use custom **ES|QL tools** when:
- You need precise control over the query logic
- Your use case involves repeatable analytical patterns
- You want to expose specific, parameterized queries to agents
- Results should be in a predictable tabular format
- You have well-defined data retrieval requirements

While agents can generate ES|QL queries dynamically using [index search tools](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/tools/index-search-tools), custom ES|QL tools ensure syntax correctness and enforce critical business rules that an LLM might occasionally miss. For strategies to avoid data retrieval issues, refer to [Context length exceeded](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded).

## Key characteristics

- Execute pre-defined ES|QL queries with dynamic parameters
- Support typed parameters
- Return results in tabular format for structured data analysis
- Ideal for repeatable analytical queries with variable inputs


## Parameter types

ES|QL tools support the following parameter types:
<applies-switch>
  <applies-item title="{ stack: ga 9.2-9.3 }" applies-to="Elastic Stack: Generally available from 9.2 to 9.3">
    ES|QL tools support the following parameter types:
    - **String types**: `text`, `keyword`
    - **Numeric types**: `long`, `integer`, `double`, `float`
    - **Other types**: `boolean`, `date`, `object`, `nested`
  </applies-item>

  <applies-item title="{ stack: ga 9.4+, serverless: ga }" applies-to="Elastic Cloud Serverless: Generally available, Elastic Stack: Planned">
    ES|QL tools support the following parameter types:
    - **Textual types**: `string`
    - **Numeric types**: `integer`, `float`
    - **Other types**: `boolean`, `date`, `array`
  </applies-item>
</applies-switch>


## Parameter options

Parameters can be configured as:
- **Required**: The agent must provide a value when calling the tool
- **Optional**: The agent can omit the parameter when calling the tool. You can set [default values for optional parameters](#default-values-for-optional-parameters).


### Default values for optional parameters

Optional parameters can have default values that are automatically applied when the agent doesn't provide a value. This ensures valid query syntax and consistent behavior.
When an agent calls a tool without specifying optional parameters, it automatically uses the defaults.
When the agent provides a value, it overrides the default.

#### Set default values in UI

<applies-to>
  - Elastic Stack: Planned
</applies-to>

When creating ES|QL tools in the Kibana UI, you must specify default values for all optional parameters. This requirement ensures that tools have sensible fallback behavior and prevents configuration errors that could cause queries to fail at runtime.

#### Set default values with API

<applies-to>
  - Elastic Stack: Generally available since 9.3
</applies-to>

When creating ES|QL tools via the API, default values for optional parameters are not required. However, they are strongly recommended to prevent query syntax errors when agents don't provide values. Without defaults, optional parameters that agents don't specify will be `null`, which can cause queries to fail.
For details about the ES|QL tools API, refer to the [API documentation](https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-agent-builder-tools).

## Query syntax

In your ES|QL query, reference parameters using the `?parameter_name` syntax. The agent will automatically interpolate parameter values when executing the query.

### Example

Here's an example ES|QL tool that searches for books using full-text search. `?search_terms` is a named parameter that the agent will provide when executing the query.
```esql
FROM books
| WHERE MATCH(title, ?search_terms)
| KEEP title, author, year
| LIMIT 10
```

You can ask the LLM to infer the parameters for the query or add them manually.
![Creating an ES|QL tool with a parameterized query](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/images/create-esql-tool-query.png)

<note>
  For API examples, refer to [Elastic Agent Builder Kibana APIs overview > Tools APIs](/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/kibana-api#tools-apis)
  <dropdown title="Complex analytical query example">
    For high-stakes or complex analytical queries, pre-defining the ES|QL logic guarantees correctness and enforces business rules.**Tool name**: `Calculate Quarterly Revenue`**Description**: "Calculates confirmed revenue for a specific region broken down by quarter. Input requires a region code (e.g., 'US', 'EU')."**Query**:
    ```esql
    FROM finance-orders-*
    | WHERE order_status == "completed" AND region == ?region 
    | STATS total_revenue = SUM(amount) BY quarter
    | LIMIT 5
    ```
  </dropdown>
</note>


## Best practices

- **Include [`LIMIT`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3016/reference/query-languages/esql/commands/limit) clauses**: Prevent returning excessive results by setting reasonable limits
- **Use meaningful parameter names**: Choose names that clearly indicate what the parameter represents (for example, `start_date` instead of `date1`)
- **Define parameter types**: Ensure parameters have the correct type to avoid runtime errors
- **Provide clear descriptions**: Help agents understand when and how to use each parameter
- **Use [default values](#default-values-for-optional-parameters)** for optional parameters: Set sensible defaults for optional parameters to reduce complexity for agents and ensure consistent behavior when parameters are omitted <applies-to>Elastic Stack: Generally available since 9.3</applies-to>

For general guidance on naming tools and writing effective descriptions, refer to [Custom tools best practices](/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/tools/custom-tools#best-practices).
<tip>
  If queries are slow or failing, you might be retrieving more data than the LLM can process. Refer to [Context length exceeded](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded) for tips on diagnosing and resolving these issues.
</tip>


## Limitations

ES|QL tools are subject to the current limitations of the ES|QL language itself. For more information, refer to [ES|QL tool limitations](/elastic/docs-builder/docs/3016/explore-analyze/ai-features/agent-builder/limitations-known-issues#esql-limitations).

## ES|QL documentation

To learn more about the language, refer to the [ES|QL docs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3016/reference/query-languages/esql).