Tools in Elastic Agent Builder

Serverless Elasticsearch Preview Serverless Observability Unavailable Serverless Security Unavailable Stack Preview 9.2.0

Agents use tools to search, retrieve, and take meaningful steps on your behalf.

Tools can be thought of as functions: modular, reusable actions that agents can call to interact with your Elasticsearch data.

Each tool is defined by several key fields:

• id: The unique identifier that agents use to reference the tool (e.g., .get_document_by_id)
• type: Specifies whether the tool is builtin (pre-defined) or esql (custom)
• description: Natural language explanation of what the tool does, used by the AI to determine when to use it
• configuration: Contains the tool's logic - empty for built-in tools, or query and parameters for custom ESQL tools
• schema: Defines the input parameters the tool requires, written in JSON Schema format

Tools enable agents to work with Elasticsearch data. When an agent receives a natural language query, it does the following:

1. Analyzes the semantic intent of the request
2. Selects appropriate tools from its available toolset
3. Maps the request parameters to tool input parameters
4. Executes the tools in sequence as needed
5. Processes the structured output data

Each tool is an atomic operation with a defined signature - accepting typed parameters and returning structured results in a format the agent can parse, transform, and incorporate into its response generation.

Elastic Agent Builder ships with a comprehensive set of built-in tools that provide core capabilities for working with your Elasticsearch data. These tools are ready to use. They cannot be modified or deleted.

Key built-in tools include:

• .execute_esql: Executes an ES|QL query and returns the results in a tabular format
• .generate_esql: Generates an ES|QL query from a natural language query
• .get_document_by_id: Retrieves the full content of an Elasticsearch document based on its ID and index name
• .get_index_mapping: Retrieves mappings for the specified index or indices
• .index_explorer: Lists relevant indices and corresponding mappings based on a natural language query
• .list_indices: Lists the indices in the Elasticsearch cluster the current user has access to
• .search: A powerful tool for searching and analyzing data within a specific Elasticsearch index

Built-in tools serve as building blocks for more complex interactions and provide the foundation for agent capabilities.

You can extend the built-in tool catalog with your own custom tool definitions. Custom tools offer flexibility in how they interact with your data:

• Index search tools: Define tools that are scoped to a specific index or pattern, allowing the LLM to decide how to query those indices based on the user's request.
• ES|QL tools: Define tools with explicit ES|QL queries for precise, pre-defined data retrieval operations.

This flexibility allows you to create tools that match your specific use cases and data access patterns.

Parameters enable tools to be dynamic and adaptable to different queries. Each parameter has:

• A name that identifies it
• A type (such as keyword, number, boolean)
• A description that helps the agent understand when and how to use it

For ES|QL tools, parameters are defined in the query using the syntax ?parameter_name and must be configured when creating the tool.

Parameters can be:

• Manually defined: You explicitly define the parameters a tool needs
• Inferred from query: For ES|QL tools, you can use the "Infer parameters from query" button to automatically detect parameters in your query statement

The tool's schema field defines these parameters using JSON Schema format, specifying:

• type: Always "object" for tool parameters
• properties: Dictionary defining each parameter's type and description
• required: Array listing mandatory parameters
• additionalProperties: Set to false to reject undefined parameters

Providing clear, descriptive parameter names and descriptions helps agents properly use your tools when answering queries.

You can create custom tools to help agents interact with your data in specific ways. This section covers how to create and test tools in the UI

1. Navigate to the Tools section on the Agents page in Kibana.
2. Click New tool.

×

4. Fill in the required fields:

   • Name: Enter a descriptive name for your tool.
   • Description: Write a clear explanation of what the tool does and when it should be used.
   • Tool type: Choose either ES|QL or Index search.
   • Parameters: For tools with ES|QL queries, define any parameters your query needs.
   • Tags: (Optional) Add labels to categorize and organize your tools.

5. Choose how to save your tool:

   • Select Save to create the tool.
   • Select Save and test to create the tool and immediately open the testing interface
   
   ×

Before assigning tools to agents, verify they work correctly by testing them. Testing helps ensure your tool returns useful results and handles parameters correctly.

If you didn't select Save and test immediately:

1. Find your tool in the Tools list.
2. Click the test icon (play button) associated with your tool.

×

3. Enter test data based on your tool type:
   • For ES|QL tools with parameters: Enter realistic test values for each parameter in the Inputs section.
   • For Index search tools: Enter a sample search query to test the search functionality.
4. Select Submit to run the test.
5. Review the Response section to verify:
   • The tool executes without errors.
   • Results are returned in the expected format.
   • The data matches your expectations.
6. Now you can assign the tool to an agent.

1. Write descriptive names: Use clear, action-oriented names.
2. Provide detailed descriptions: Explain when and how the tool should be used.
3. Limit scope: Focus each tool on a specific task rather than creating overly complex tools.
4. Use meaningful parameter names: Choose names that clearly indicate what the parameter represents.
5. Add comprehensive parameter descriptions: Help the agent understand what values to use.
6. Include LIMIT clauses in ES|QL queries: Prevent returning excessive results.
7. Use appropriate tags: Add relevant tags to make tools easier to find and organize.
8. Limit tool count: More tools are not always better. Try to keep each agent focused with a limited number of relevant tools.

Find the list of available tools on the Tools landing page in the UI, or use Tools API.

×

Access the complete list of available tools from the Tools page in Kibana. This view shows:

• Tool names and descriptions
• Tool types
• Associated tags
• Actions (edit, delete, test)

Tools must be assigned to agents before they can be used:

1. Navigate to the agent configuration page.
2. Select the Tools tab.
3. Add the desired tools to the agent.
4. Save the agent configuration.

Custom tools can be modified or removed as needed:

1. From the Tools page, find the tool you want to modify.
2. Select the edit icon to update the tool or the delete icon to remove it.
3. For updates, modify the tool properties and save your changes.

Note that built-in tools cannot be modified or deleted.

For a quick overview of how to work programmatically with tools, refer to Tools API.

For the complete API reference, refer to the Kibana API reference.

Tools can also be accessed through the Model Context Protocol (MCP) server, which provides a standardized interface for external clients to use Agent Builder tools.

The Tools UI provides a Copy your MCP server URL button for easy access.

×

For detailed MCP server configuration, refer to MCP server.