﻿---
title: Index search tools
description: Index search tools provide intelligent, natural language-driven search over specified Elasticsearch resources. Instead of defining explicit queries, you...
url: https://www.elastic.co/elastic/docs-builder/docs/2666/explore-analyze/ai-features/agent-builder/tools/index-search-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
---

# Index search tools
Index search tools provide intelligent, natural language-driven search over specified Elasticsearch resources. Instead of defining explicit queries, you specify a pattern of [indices](https://www.elastic.co/elastic/docs-builder/docs/2666/manage-data/data-store/index-basics), [aliases](https://www.elastic.co/elastic/docs-builder/docs/2666/manage-data/data-store/aliases), or [data streams](https://www.elastic.co/elastic/docs-builder/docs/2666/manage-data/data-store/data-streams), and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests. The tool automatically generates queries in Query DSL or ES|QL format based on the search intent.

## When to use index search tools

Use custom **Index search tools** when:
- You want agents to handle diverse, exploratory queries
- The search intent varies significantly across requests
- Users need flexible, dynamic search functionality
- You want to scope general search capabilities to specific indices


## Key characteristics

- Accept natural language queries from the agent
- Automatically determine optimal search strategy (full-text, semantic)
- Leverage built-in tools like index exploration, query generation, and semantic search
- Ideal for flexible, user-driven exploratory searches
- No need to pre-define query logic


## Configuration

Index search tools support the following configuration parameters:
<definitions>
  <definition term="pattern">
    An index pattern string specifying which indices, aliases, or data streams to search. Examples: `logs-myapp-*`, `my-index`, `.alerts-security-*`.
    <tip>
      [Avoid overly broad wildcard patterns](#wildcard-warning) like `*` or `logs-*` across large datasets.
    </tip>
  </definition>
  <definition term="row_limit (optional)">
    Maximum number of rows to return from ES|QL queries. This helps control the amount of data retrieved and prevents exceeding context length limits.
  </definition>
  <definition term="custom_instructions (optional)">
    Domain-specific guidance for ES|QL query generation. For example: `"Always include @timestamp and filter out records where environment='test'"`.
  </definition>
</definitions>


## How it works

When an agent calls an index search tool:
1. The agent provides a natural language query (for example, "find recent errors related to authentication")
2. The tool analyzes the query intent and available indices
3. It automatically orchestrates built-in tools to:
   - Explore the index structure and mappings
- Generate appropriate queries (ES|QL or query DSL)
- Execute semantic search if relevant
- Rank and format results
4. Returns results in a format the agent can interpret and present


## Best practices

- **Use specific patterns**: Scope tools to relevant index patterns rather than broad wildcards (for example, `logs-myapp-*` instead of `logs-*`)
- **Write descriptive tool names**: Help agents select the right tool for the query (for example, "Search Security Alerts" vs. "Search Tool")
- **Provide context in descriptions**: Explain what data the indices contain and what types of questions the tool can answer
- **Create domain-specific tools**: Build separate tools for different data domains (logs, metrics, alerts) rather than one general-purpose tool
- **Add custom instructions**: Use the custom instructions parameter to guide ES|QL query generation with domain-specific requirements, such as always including certain fields, applying specific filters, or handling time ranges in a particular way
- **Set appropriate row limits**: Configure row limits to prevent retrieving excessive data that could exceed context length limits

For general guidance on naming tools and writing effective descriptions, refer to [Custom tools best practices](/elastic/docs-builder/docs/2666/explore-analyze/ai-features/agent-builder/tools/custom-tools#best-practices).

## Common patterns

- **Wildcard patterns**: `logs-*`, `metrics-*`, `events-*`
- **Specific indices**: `products`, `users`, `orders`


<warning>
  Avoid overly broad patterns like `*` or `logs-*` across large datasets. Broad wildcards can cause the agent to retrieve more data than the LLM can process, resulting in slow responses or errors. Refer to [Context length exceeded](https://www.elastic.co/elastic/docs-builder/docs/2666/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded) for tips on diagnosing and resolving these issues.
</warning>