[Agent Builder] Provide tools docs (elastic#3441)

Co-authored-by: Liam Thompson <[email protected]>

Author: 2 people

solutions/search/agent-builder/tools.md

@@ -68,8 +68,9 @@ Tool namespacing helps organize and identify tools by their source. Built-in too
 
 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:
 
-- **Scoped 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
-- **Explicit query tools**: Define tools with explicit {{esql}} queries for precise, pre-defined data retrieval operations
+- **[Index search tools](tools/index-search-tools.md)**: 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](tools/esql-tools.md)**: Define tools with explicit {{esql}} 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.
 
@@ -110,7 +111,7 @@ You can create custom tools to help agents interact with your data in specific w
 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 **{{esql}}** query or **Index search**
+   - **Tool type**: Choose either **[{{esql}}](tools/esql-tools.md)** or **[Index search](tools/index-search-tools.md)**
    - **Parameters**: For tools with {{esql}} queries, define any parameters your query needs
    - **Tags**: (Optional) Add labels to categorize and organize your tools
 5. Choose how to save your tool:
@@ -211,4 +212,4 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access.
 :width: 250px
 :::
 
-For detailed MCP server configuration, refer to [MCP server](mcp-server.md).
+For detailed MCP server configuration, refer to [MCP server](mcp-server.md).

solutions/search/agent-builder/tools/esql-tools.md

@@ -0,0 +1,64 @@
+---
+navigation_title: "ES|QL tools"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+:::{warning}
+These pages are currently hidden from the docs TOC and have `noindexed` meta headers.
+
+**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).**
+:::
+
+# {{esql}} tools
+
+{{esql}} query tools enable you to create parameterized queries that execute directly against your {{es}} data. These custom tools provide precise control over data retrieval through templated [{{esql}}](elasticsearch://reference/query-languages/esql.md) statements.
+
+## When to use {{esql}} tools
+
+Use custom **{{esql}} 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 {{esql}} 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
+
+{{esql}} 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**: Must be provided by the agent when calling the tool
+* **Optional**: Can be omitted; uses `null` if no default is specified
+
+## Query syntax
+
+In your {{esql}} query, reference parameters using the `?parameter_name` syntax. The agent will automatically interpolate parameter values when executing the query.
+
+
+## Best practices
+
+- **Include LIMIT clauses**: Prevent returning excessive results by setting reasonable limits
+- **Use meaningful parameter names**: Choose names that clearly indicate what the parameter represents (e.g., `start_date` instead of `date1`)
+- **Provide clear descriptions**: Help agents understand when and how to use each parameter
+
+## {{esql}} documentation
+
+To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md).

solutions/search/agent-builder/tools/index-search-tools.md

@@ -0,0 +1,69 @@
+---
+navigation_title: "Index search tools"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+:::{warning}
+These pages are currently hidden from the docs TOC and have `noindexed` meta headers.
+
+**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).**
+:::
+
+# Index search tools
+
+Index search tools provide intelligent, natural language-driven search over specified {{es}} resources. Instead of defining explicit queries, you specify a pattern of [indices](/manage-data/data-store/index-basics.md), [aliases](/manage-data/data-store/aliases.md), or [data streams](/manage-data/data-store/data-streams.md), and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests.
+
+## 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, ad-hoc 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 require only a single configuration parameter:
+
+* **`pattern`**: An index pattern string (e.g., `logs-*`, `my-index`, `.alerts-*`) specifying which indices, aliases, or data streams to search
+
+## How it works
+
+When an agent calls an index search tool:
+
+1. The agent provides a natural language query (e.g., "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 ({{esql}} 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 (e.g., `logs-myapp-*` instead of `logs-*`)
+- **Write descriptive tool names**: Help agents select the right tool for the query (e.g., "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
+
+
+## Common patterns
+
+* **Wildcard patterns**: `logs-*`, `metrics-*`, `events-*`
+* **Specific indices**: `products`, `users`, `orders`
+* **System indices**: `.alerts-security-*`, `.ml-anomalies-*`
+* **All resources**:  `*`

solutions/toc.yml

@@ -1,4 +1,4 @@
-project: 'Solutions and use cases'
+project: "Solutions and use cases"
 toc:
   - file: index.md
   - file: search.md
@@ -50,6 +50,8 @@ toc:
       - hidden: search/agent-builder/chat.md
       - hidden: search/agent-builder/agent-builder-agents.md
       - hidden: search/agent-builder/tools.md
+      - hidden: search/agent-builder/tools/esql-tools.md
+      - hidden: search/agent-builder/tools/index-search-tools.md
       - hidden: search/agent-builder/programmatic-access.md
       - hidden: search/agent-builder/kibana-api.md
       - hidden: search/agent-builder/mcp-server.md
@@ -458,13 +460,13 @@ toc:
               - file: observability/logs/logs-index-template-defaults.md
           - file: observability/streams/streams.md
             children:
-            - file: observability/streams/management/extract.md
-              children:
-                - file: observability/streams/management/extract/date.md
-                - file: observability/streams/management/extract/dissect.md
-                - file: observability/streams/management/extract/grok.md
-            - file: observability/streams/management/retention.md
-            - file: observability/streams/management/advanced.md
+              - file: observability/streams/management/extract.md
+                children:
+                  - file: observability/streams/management/extract/date.md
+                  - file: observability/streams/management/extract/dissect.md
+                  - file: observability/streams/management/extract/grok.md
+              - file: observability/streams/management/retention.md
+              - file: observability/streams/management/advanced.md
       - file: observability/incident-management.md
         children:
           - file: observability/incident-management/alerting.md
@@ -747,4 +749,4 @@ toc:
               - file: security/advanced-entity-analytics/privileged-user-monitoring-setup.md
               - file: security/advanced-entity-analytics/monitor-privileged-user-activitites.md
       - file: security/asset-management.md
-      - file: security/apis.md
+      - file: security/apis.md