[agent builder] Document default values for optional params in ESQL tools

solutions/search/agent-builder/kibana-api.md

@@ -12,7 +12,7 @@ applies_to:
 
 This page provides a quick overview of the main {{kib}} API endpoints for {{agent-builder}}. For complete details including all available parameters, request/response schemas, and error handling, refer to the [{{kib}} API reference](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-agent-builder).
 
-These APIs allow you to programmatically work with the {{agent-builder}} abstractions.
+These APIs enable you to programmatically work with the {{agent-builder}} abstractions.
 
 ## Using the APIs
 
@@ -147,6 +147,94 @@ curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \
        }
      }'
 ```
+:::
+
+::::
+
+**Example:** Create a tool with [default values](/solutions/search/agent-builder/tools/esql-tools.md#default-values-for-optional-parameters) for optional parameters {applies_to}`stack: ga 9.3`
+
+This example creates an ES|QL tool with optional parameters that have default values, which are automatically used when the agent doesn't provide them.
+
+::::{tab-set}
+:group: api-examples-defaults
+
+:::{tab-item} Console
+:sync: console-defaults
+```console
+POST kbn://api/agent_builder/tools
+{
+  "id": "sales-analysis-tool",
+  "type": "esql",
+  "description": "Analyze sales data with optional time filtering and automatic defaults for unspecified parameters",
+  "tags": ["analytics", "sales"],
+  "configuration": {
+    "query": "FROM sales | WHERE timestamp >= ?start_date AND region == ?region | STATS total_sales=SUM(amount) BY product | LIMIT ?limit",
+    "params": {
+      "start_date": {
+        "type": "date",
+        "description": "Start date for analysis. When not provided by the agent, defaults to '2024-01-01T00:00:00Z'",
+        "optional": true,
+        "defaultValue": "2024-01-01T00:00:00Z"
+      },
+      "region": {
+        "type": "keyword",
+        "description": "Sales region to filter by. If omitted, defaults to 'ALL' to include all regions",
+        "optional": true,
+        "defaultValue": "ALL"
+      },
+      "limit": {
+        "type": "integer",
+        "description": "Maximum results to return. When not specified, automatically limits to 50 results",
+        "optional": true,
+        "defaultValue": 50
+      }
+    }
+  }
+}
+```
+:::
+
+:::{tab-item} curl
+:sync: curl-defaults
+```bash
+curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \
+     -H "Authorization: ApiKey ${API_KEY}" \
+     -H "kbn-xsrf: true" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "id": "sales-analysis-tool",
+       "type": "esql",
+       "description": "Analyze sales data with optional time filtering and automatic defaults for unspecified parameters",
+       "tags": ["analytics", "sales"],
+       "configuration": {
+         "query": "FROM sales | WHERE timestamp >= ?start_date AND region == ?region | STATS total_sales=SUM(amount) BY product | LIMIT ?limit",
+         "params": {
+           "start_date": {
+             "type": "date",
+             "description": "Start date for analysis. When not provided by the agent, defaults to \"2024-01-01T00:00:00Z\"",
+             "optional": true,
+             "defaultValue": "2024-01-01T00:00:00Z"
+           },
+           "region": {
+             "type": "keyword",
+             "description": "Sales region to filter by. If omitted, defaults to \"ALL\" to include all regions",
+             "optional": true,
+             "defaultValue": "ALL"
+           },
+           "limit": {
+             "type": "integer",
+             "description": "Maximum results to return. When not specified, automatically limits to 50 results",
+             "optional": true,
+             "defaultValue": 50
+           }
+         }
+       }
+     }'
+```
+:::
+
+::::
+
 :::{include} _snippets/spaces-api-note.md
 :::
 :::

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

@@ -8,9 +8,7 @@
     security: unavailable
 ---
 
-
-
 # {{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.
 
@@ -43,8 +41,42 @@
 
 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
+* **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} { "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} { "stack": "preview 9.2" }
+
+  * You don't need to specify a default value, the agent uses `null` when not provided
+
+  :::
+
+  ::::
+
+
+
+### Default values for optional parameters
+```{applies_to}
+stack: ga 9.3
+```
+
+:::{important}
+Support for optional parameters with default values in {{esql}} 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.
+:::
+
+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 {{esql}} tools API.
 
 ## Query syntax
 
@@ -67,17 +99,22 @@
 :alt: Creating an ES|QL tool with a parameterized query
 :::
 
+:::{note}
+For API examples, refer to [](/solutions/search/agent-builder/kibana-api.md#tools)
+:::
+
 ## Best practices
 
 - **Include [`LIMIT`](elasticsearch://reference/query-languages/esql/commands/limit.md) 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`)
+- **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 {applies_to}`stack: ga 9.3`
 
 ## Limitations
 
 {{esql}} tools are subject to the current limitations of the {{esql}} language itself. For more information, refer to [{{esql}} tool limitations](../limitations-known-issues.md#esql-limitations).
 
 ## {{esql}} documentation
 
-To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md).
+To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md).