---
title: Index search tools in Elastic Agent Builder
description: Create custom tools that allow agents to intelligently search specific Elasticsearch index patterns using natural language.
url: https://www.elastic.co/elastic/docs-builder/docs/3513/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 in Elastic Agent Builder
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/3513/manage-data/data-store/index-basics), [aliases](https://www.elastic.co/elastic/docs-builder/docs/3513/manage-data/data-store/aliases), or [data streams](https://www.elastic.co/elastic/docs-builder/docs/3513/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 selects a single index from the configured pattern based on the query intent and available index metadata
3. It automatically orchestrates built-in tools to:
   - Explore the selected index's 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

<important>
  Even when the configured pattern matches multiple indices, the tool selects only one index per query. It does not search across all matching indices simultaneously.If your use case requires searching across multiple indices in a single query, use the built-in [search tool](/elastic/docs-builder/docs/3513/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference#agent-builder-builtin-search-tool) instead, which supports multi-index ES|QL queries across index patterns. <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
</important>

To help agents make better decisions during the source selection phase, you can optimize your index metadata and tool configurations.

## Add index metadata to improve agent search

You can add metadata to your index mappings to help agents make better decisions. Index-level [`_meta.description`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3513/reference/elasticsearch/mapping-reference/mapping-meta-field) helps agents select the appropriate indices.

#### Example: Add index-level metadata

```json

{
  "_meta": {
    "description": "Primary dataset for North American customer orders in 2025. Use this for questions about order values, shipping status, or customer purchase history. Do not use for real-time inventory levels—use the inventory index instead. RELATIONSHIPS: 'customer_id' links to 'customer-profiles' index. NOTES: 'total_amount' includes tax; use 'subtotal' for pre-tax calculations." <1>
  },
  "properties": {
    "order_id": { "type": "keyword" },
    "total_amount": { "type": "double" }, <2>
    "created_at": { "type": "date" },
    "customer_support_notes": { "type": "text" }
  }
}
```

<important>
  Keep descriptions concise (a few sentences) to avoid [context overflow](https://www.elastic.co/elastic/docs-builder/docs/3513/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded).
</important>


## Best practices

- **Add index [metadata](#add-index-metadata-to-improve-agent-search) descriptions**: Include `_meta.description` fields in your index mappings. Keep descriptions concise (a few sentences) to avoid [context overflow](https://www.elastic.co/elastic/docs-builder/docs/3513/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded).
  - Explain what entities or events the index covers
- Note what types of questions it can answer
- Document how fields link to other indices
- State what the index should NOT be used for
- Clarify non-obvious field meanings or calculations
- **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. In enterprise environments with hundreds of indices, creating scoped search tools prevents the agent from wasting tokens scanning irrelevant data. For example, a "Finance Agent" should not search through "Customer Support" logs.
- **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/3513/explore-analyze/ai-features/agent-builder/tools/custom-tools#best-practices).
<tip>
  Creating scoped, domain-specific tools also helps prevent [context length issues](https://www.elastic.co/elastic/docs-builder/docs/3513/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded) by reducing the volume of data the agent needs to process.
</tip>


## Common patterns

The following examples show typical index patterns and domain-specific tool configurations.

### Index pattern syntax

- **Wildcard patterns**: `logs-*`, `metrics-*`, `events-*`
- **Specific indices**: `products`, `users`, `orders`
- **Cross-cluster patterns** <applies-to>Elastic Stack: Generally available since 9.4</applies-to>: `remote_cluster:logs-*`, `cluster_a:events-*`. For previous versions, refer to [Cross-cluster search support](/elastic/docs-builder/docs/3513/explore-analyze/ai-features/agent-builder/limitations-known-issues#cross-cluster-search-support).

Instead of creating a single generic search tool, consider creating multiple focused tools that target specific data domains. This gives the agent a smaller, higher-quality list of potential data sources, reducing the chance of retrieving irrelevant data.
<dropdown title="Support logs tool example">
  **Tool name**: `Search Support Logs`**Pattern**: `logs-support-*`**Description**: "Search through server and application logs for error traces, stack traces, and diagnostic information. Use this when troubleshooting technical support tickets or investigating system issues."
</dropdown>

<dropdown title="Finance invoices tool example">
  **Tool name**: `Search Invoices`**Pattern**: `finance-invoices-*`**Description**: "Search through settled and pending invoices. Use this to retrieve payment status, billing addresses, or invoice details for accounting queries."
</dropdown>

<dropdown title="Cross-cluster search tool example">
  **Tool name**: `Search Remote Logs`**Pattern**: `remote_cluster:logs-*`**Description**: "Search log data stored on remote_cluster. Use this tool when the user asks about remote logs or logs on a specific remote cluster."Index search tools only search remote clusters when you explicitly configure a cross-cluster pattern. Without a remote pattern, the tool resolves indices locally.
</dropdown>

<dropdown title="Security alerts tool example">
  **Tool name**: `Search Security Alerts`**Pattern**: `security-alerts-*`**Description**: "Search security detection alerts and findings. Use this for questions about threat detection, suspicious activity, or security incidents."
</dropdown>


<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/3513/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded) for tips on diagnosing and resolving these issues.
</warning>