﻿---
title: ES|QL tools
description: ES|QL query tools enable you to create parameterized queries that execute directly against your Elasticsearch data. These custom tools provide precise...
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4472/solutions/search/agent-builder/tools/esql-tools
---

# ES|QL tools
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/elasticsearch/tree/main/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


## 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:
- **String types**: `text`, `keyword`
- **Numeric types**: `long`, `integer`, `double`, `float`
- **Other types**: `boolean`, `date`, `object`, `nested`


## Parameter options

Parameters can be configured as:
- **Required**: The agent must provide a value when calling the tool
- **Optional**: The agent doesn't need to provide a value when calling the tool
  <applies-switch>
  <applies-item title="{ "stack": "ga 9.3" }">
  - You can specify a [default value](#default-values-for-optional-parameters) for optional parameters to prevent query errors when agents don't provide them
  </applies-item>

  <applies-item title="{ "stack": "preview 9.2" }">
  - You don't need to specify a default value, the agent uses `null` when not provided
  </applies-item>
  </applies-switch>


### Default values for optional parameters

```
stack: ga 9.3
```

<important>
  Support for optional parameters with default values in ES|QL tools is an API-only feature initially. While default values are not required by the API, they are strongly recommended for all optional parameters to prevent query syntax errors.
</important>

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 parameters, it automatically uses the defaults.
When the agent provides a value, it overrides the default.
Refer to the [API documentation](https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-agent-builder-tools) for details about the ES|QL tools API.

## 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://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4472/solutions/search/agent-builder/images/create-esql-tool-query.png)

<note>
  For API examples, refer to [Work with Elastic Agent Builder using the APIs > Tools](/elastic/docs-content/pull/4472/solutions/search/agent-builder/kibana-api#tools)
</note>


## Best practices

- **Include [`LIMIT`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/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 `stack: ga 9.3`


## 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-content/pull/4472/solutions/search/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/elasticsearch/tree/main/reference/query-languages/esql).