[Obs AI] Improvements to tool descriptions and params (elastic#247723)

This PR makes various improvements the o11y tools: better descriptions,
summary, and consistent terminology.

### Enhanced descriptions
Added "When to use" guidance to help the LLM select the right tool
(`get_alerts`, `get_anomaly_detection_jobs`, `get_correlated_logs`,
`get_downstream_dependencies`, `get_services`)

### Simplified `get_correlated_logs` API
  - `logsFilter` → `kqlFilter` (consistent with other tools)
  - `interestingEventFilter` → `errorLogsOnly`

### Optional time range
`get_downstream_dependencies` and `get_services` now defaults to last
hour instead of requiring a time range

---------

Co-authored-by: Arturo Lidueña <arturo.liduena@elastic.co>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

Author: 3 people

x-pack/solutions/observability/plugins/observability_agent_builder/server/tools/get_alerts/tool.ts

@@ -77,7 +77,14 @@ export function createGetAlertsTool({
   const toolDefinition: BuiltinToolDefinition<typeof getAlertsSchema> = {
     id: OBSERVABILITY_GET_ALERTS_TOOL_ID,
     type: ToolType.builtin,
-    description: `Retrieves Observability alerts within a specified time range. Supports filtering by status (active/recovered) and KQL queries to find specific alert instances.`,
+    description: `Retrieves Observability alerts within a specified time range.
+
+When to use:
+- Checking if there are active alerts for a service or host
+- Investigating what triggered during an incident
+- Finding alerts related to specific infrastructure or services
+
+Supports filtering by status (active/recovered) and KQL queries.`,
     schema: getAlertsSchema,
     tags: ['observability', 'alerts'],
     availability: {
@@ -86,16 +93,15 @@ export function createGetAlertsTool({
         return getAgentBuilderResourceAvailability({ core, request, logger });
       },
     },
-    handler: async (
-      {
+    handler: async (toolParams, { request }) => {
+      const {
         start = DEFAULT_TIME_RANGE.start,
         end = DEFAULT_TIME_RANGE.end,
         kqlFilter,
         includeRecovered,
         query,
-      },
-      { request }
-    ) => {
+      } = toolParams;
+
       try {
         const { alerts, selectedFields, total } = await getToolHandler({
           core,

x-pack/solutions/observability/plugins/observability_agent_builder/server/tools/get_anomaly_detection_jobs/tool.ts

@@ -33,7 +33,7 @@ export interface GetAnomalyDetectionJobsToolResult {
   type: ToolResultType.other;
   data: {
     jobs: Awaited<ReturnType<typeof getToolHandler>>;
-    totalReturned: number;
+    total: number;
     message?: string;
   };
 }
@@ -72,8 +72,12 @@ export function createGetAnomalyDetectionJobsTool({
   const toolDefinition: BuiltinToolDefinition<typeof getAnomalyDetectionJobsSchema> = {
     id: OBSERVABILITY_GET_ANOMALY_DETECTION_JOBS_TOOL_ID,
     type: ToolType.builtin,
-    description:
-      'Retrieves Machine Learning anomaly detection jobs and their top anomaly records for a given time range. Use this to identify unusual patterns or outliers in observability data.',
+    description: `Retrieves Machine Learning anomaly detection jobs and their top anomaly records.
+
+When to use:
+- Investigating anomalies in logs, metrics, or traces
+- Finding outliers that might indicate problems
+- Answering "is anything behaving abnormally?"`,
     schema: getAnomalyDetectionJobsSchema,
     tags: ['observability', 'machine_learning', 'anomaly_detection'],
     availability: {
@@ -83,16 +87,17 @@ export function createGetAnomalyDetectionJobsTool({
       },
     },
     handler: async (
-      {
-        jobIds,
-        limit: jobsLimit = DEFAULT_JOBS_LIMIT,
-        start: rangeStart = DEFAULT_TIME_RANGE.start,
-        end: rangeEnd = DEFAULT_TIME_RANGE.end,
-      },
+      toolParams,
       { esClient, request }
     ): Promise<{
       results: (GetAnomalyDetectionJobsToolResult | Omit<ErrorResult, 'tool_result_id'>)[];
     }> => {
+      const {
+        jobIds,
+        limit: jobsLimit = DEFAULT_JOBS_LIMIT,
+        start: rangeStart = DEFAULT_TIME_RANGE.start,
+        end: rangeEnd = DEFAULT_TIME_RANGE.end,
+      } = toolParams;
       const scopedEsClient = esClient.asCurrentUser;
       const mlClient = scopedEsClient.ml;
 
@@ -109,28 +114,13 @@ export function createGetAnomalyDetectionJobsTool({
           rangeEnd,
         });
 
-        if (!mlJobs.length) {
-          return {
-            results: [
-              {
-                type: ToolResultType.other,
-                data: {
-                  jobs: [],
-                  totalReturned: 0,
-                  message: 'No anomaly detection jobs found for the provided filters.',
-                },
-              },
-            ],
-          };
-        }
-
         return {
           results: [
             {
               type: ToolResultType.other,
               data: {
                 jobs: mlJobs,
-                totalReturned: mlJobs.length,
+                total: mlJobs.length,
               },
             },
           ],

x-pack/solutions/observability/plugins/observability_agent_builder/server/tools/get_correlated_logs/README.md

@@ -1,70 +1,54 @@
 # get_correlated_logs
 
-Retrieves logs and their surrounding context based on shared correlation identifiers (e.g. trace.id). Can start from a specific log ID or find error logs within a time range to use as anchors. Returns chronologically sorted groups of logs, providing visibility into the sequence of events leading up to and following the anchor log.
+Retrieves log sequences around error events to understand what happened. By default, anchors on error logs (ERROR, WARN, FATAL, HTTP 5xx). Set `errorLogsOnly: false` to anchor on any (non-error) logs.
 
 ## Examples
 
 ### Find correlated logs for errors in the payment-service
 
-```
-POST kbn://api/agent_builder/tools/_execute
-{
-  "tool_id": "observability.get_correlated_logs",
-  "tool_params": {
-    "logsFilter": "service.name: \"payment-service\""
-  }
-}
-```
-
-### Find correlated logs for a specific log ID
-
-```
+```jsonc
 POST kbn://api/agent_builder/tools/_execute
 {
   "tool_id": "observability.get_correlated_logs",
   "tool_params": {
-    "logId": "c8f9d2a1-4b3e-4a1c-9d8e-7f6a5b4c3d2e",
-    "index": "logs-payment-service"
+    "kqlFilter": "service.name: payment-service"
   }
 }
 ```
 
-### Limit the returned logs to specific fields only
+### Find correlated logs for slow requests (non-errors)
 
-```
+```jsonc
 POST kbn://api/agent_builder/tools/_execute
 {
   "tool_id": "observability.get_correlated_logs",
   "tool_params": {
-    "start": "now-15m",
-    "end": "now",
-    "logSourceFields": ["@timestamp", "message", "log.level", "service.name"],
-    "maxSequences": 20
+    "kqlFilter": "service.name: payment-service AND event.duration > 1000000",
+    "errorLogsOnly": false
   }
 }
 ```
 
-### Specify non-standard correlation identifiers to correlate by
+### Find correlated logs for a specific log ID
 
-```
+```jsonc
 POST kbn://api/agent_builder/tools/_execute
 {
   "tool_id": "observability.get_correlated_logs",
   "tool_params": {
-    "correlationFields": ["my_custom_correlation_identifier"]
+    "logId": "c8f9d2a1-4b3e-4a1c-9d8e-7f6a5b4c3d2e"
   }
 }
 ```
 
-### Find correlated logs for non-error events (e.g. slow transactions)
+### Use custom correlation fields
 
-```
+```jsonc
 POST kbn://api/agent_builder/tools/_execute
 {
   "tool_id": "observability.get_correlated_logs",
   "tool_params": {
-    "logsFilter": "service.name: \"payment-service\"",
-    "interestingEventFilter": "event.duration > 1000000000"
+    "correlationFields": ["my_custom_correlation_id"]
   }
 }
 ```

x-pack/solutions/observability/plugins/observability_agent_builder/server/tools/get_correlated_logs/fetch_anchor_logs/fetch_anchor_logs.ts

@@ -15,8 +15,8 @@ export async function getAnchorLogs({
   logsIndices,
   startTime,
   endTime,
-  logsFilter,
-  interestingEventFilter,
+  kqlFilter,
+  errorLogsOnly,
   correlationFields,
   logger,
   logId,
@@ -26,8 +26,8 @@ export async function getAnchorLogs({
   logsIndices: string[];
   startTime: number;
   endTime: number;
-  logsFilter: string | undefined;
-  interestingEventFilter: string | undefined;
+  kqlFilter: string | undefined;
+  errorLogsOnly: boolean;
   correlationFields: string[];
   logger: Logger;
   logId?: string;
@@ -49,8 +49,8 @@ export async function getAnchorLogs({
     logsIndices,
     startTime,
     endTime,
-    logsFilter,
-    interestingEventFilter,
+    kqlFilter,
+    errorLogsOnly,
     correlationFields,
     logger,
     maxSequences,

x-pack/solutions/observability/plugins/observability_agent_builder/server/tools/get_correlated_logs/fetch_anchor_logs/get_anchor_logs_for_time_range.ts

@@ -10,7 +10,7 @@ import { createHash } from 'crypto';
 import type { IScopedClusterClient, Logger } from '@kbn/core/server';
 import type { AggregationsAggregationContainer } from '@elastic/elasticsearch/lib/api/types';
 import { getTypedSearch } from '../../../utils/get_typed_search';
-import { kqlFilter, timeRangeFilter } from '../../../utils/dsl_filters';
+import { kqlFilter as buildKqlFilter, timeRangeFilter } from '../../../utils/dsl_filters';
 import type { AnchorLog } from '../types';
 import { DEFAULT_ERROR_SEVERITY_FILTER } from '../constants';
 import type { CorrelationFieldAggregations } from './types';
@@ -20,8 +20,8 @@ export async function getAnchorLogsForTimeRange({
   logsIndices,
   startTime,
   endTime,
-  logsFilter,
-  interestingEventFilter,
+  kqlFilter,
+  errorLogsOnly,
   correlationFields,
   logger,
   maxSequences,
@@ -30,8 +30,8 @@ export async function getAnchorLogsForTimeRange({
   logsIndices: string[];
   startTime: number;
   endTime: number;
-  logsFilter: string | undefined;
-  interestingEventFilter: string | undefined;
+  kqlFilter: string | undefined;
+  errorLogsOnly: boolean;
   correlationFields: string[];
   logger: Logger;
   maxSequences: number;
@@ -48,7 +48,7 @@ export async function getAnchorLogsForTimeRange({
       bool: {
         filter: [
           ...timeRangeFilter('@timestamp', { start: startTime, end: endTime }),
-          ...kqlFilter(logsFilter),
+          ...buildKqlFilter(kqlFilter),
 
           // must have at least one correlation field
           {
@@ -58,10 +58,8 @@ export async function getAnchorLogsForTimeRange({
             },
           },
 
-          // must be an interesting event (error by default, or match the provided filter)
-          ...(interestingEventFilter
-            ? kqlFilter(interestingEventFilter)
-            : [DEFAULT_ERROR_SEVERITY_FILTER]),
+          // filter by error severity (default) or include all logs
+          ...(errorLogsOnly ? [DEFAULT_ERROR_SEVERITY_FILTER] : []),
         ],
       },
     },

x-pack/solutions/observability/plugins/observability_agent_builder/server/tools/get_correlated_logs/handler.ts

@@ -16,50 +16,41 @@ import { parseDatemath } from '../../utils/time';
 import { DEFAULT_CORRELATION_IDENTIFIER_FIELDS, DEFAULT_LOG_SOURCE_FIELDS } from './constants';
 import { getAnchorLogs } from './fetch_anchor_logs/fetch_anchor_logs';
 import { getCorrelatedLogsForAnchor } from './get_correlated_logs_for_anchor';
-import type { LogSequence } from './types';
 
-function getNoResultsMessage({
-  sequences,
+export function getNoResultsMessage({
   logId,
-  logsFilter,
-  interestingEventFilter,
+  kqlFilter,
+  errorLogsOnly,
   correlationFields,
   start,
   end,
 }: {
-  sequences: LogSequence[];
   logId: string | undefined;
-  logsFilter: string | undefined;
-  interestingEventFilter: string | undefined;
+  kqlFilter: string | undefined;
+  errorLogsOnly: boolean;
   correlationFields: string[];
   start: string;
   end: string;
-}): string | undefined {
-  if (sequences.length > 0) {
-    return undefined;
-  }
-
+}): string {
   const isUsingDefaultCorrelationFields =
     correlationFields === DEFAULT_CORRELATION_IDENTIFIER_FIELDS;
 
   const correlationFieldsDescription = isUsingDefaultCorrelationFields
     ? 'Matching logs exist but lack the default correlation fields (trace.id, request.id, transaction.id, etc.). Try using `correlationFields` for specifying custom correlation fields.'
     : `Matching logs exist but lack the custom correlation fields: ${correlationFields.join(', ')}`;
 
-  const isUsingDefaultEventFilter = !interestingEventFilter;
-  const eventFilterDescription = isUsingDefaultEventFilter
-    ? 'The default `interestingEventFilter` (log.level: ERROR/WARN/FATAL, HTTP 5xx, syslog severity ≤3, etc.) did not match any documents.'
-    : `The 
-interestingEventFilter" option "${interestingEventFilter}" did not match any documents.`;
-
   if (logId) {
     return `The log ID "${logId}" was not found, or the log does not have any of the ${correlationFieldsDescription}.`;
   }
 
   const suggestions = [
     `No matching logs exist in this time range (${start} to ${end})`,
-    ...(logsFilter ? ['`logsFilter` is too restrictive'] : []),
-    eventFilterDescription,
+    ...(kqlFilter ? ['`kqlFilter` is too restrictive'] : []),
+    ...(errorLogsOnly
+      ? [
+          'No error logs found (errorLogsOnly=true filters for ERROR/WARN/FATAL, HTTP 5xx, etc.). Try errorLogsOnly=false to include all log levels.',
+        ]
+      : []),
     correlationFieldsDescription,
   ];
 
@@ -74,8 +65,8 @@ export async function getToolHandler({
   esClient,
   start,
   end,
-  logsFilter,
-  interestingEventFilter,
+  kqlFilter,
+  errorLogsOnly = true,
   index,
   correlationFields = DEFAULT_CORRELATION_IDENTIFIER_FIELDS,
   logId,
@@ -91,8 +82,8 @@ export async function getToolHandler({
   esClient: IScopedClusterClient;
   start: string;
   end: string;
-  logsFilter?: string;
-  interestingEventFilter?: string;
+  kqlFilter?: string;
+  errorLogsOnly?: boolean;
   index?: string;
   correlationFields?: string[];
   logId?: string;
@@ -109,8 +100,8 @@ export async function getToolHandler({
     logsIndices,
     startTime,
     endTime,
-    logsFilter,
-    interestingEventFilter,
+    kqlFilter,
+    errorLogsOnly,
     correlationFields,
     logger,
     logId,
@@ -137,15 +128,5 @@ export async function getToolHandler({
     })
   );
 
-  const message = getNoResultsMessage({
-    sequences,
-    logId,
-    logsFilter,
-    interestingEventFilter,
-    correlationFields,
-    start,
-    end,
-  });
-
-  return { sequences, message };
+  return { sequences };
 }