diff --git a/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/shared.ts b/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/shared.ts
index d874e0f0ab2b0..2ce1777ac0170 100644
--- a/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/shared.ts
+++ b/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/shared.ts
@@ -140,14 +140,20 @@ export function mergeAllMetricsWithChartDimensionSchemaWithStaticOps<T extends P
   ]);
 }
 
-export function mergeAllBucketsWithChartDimensionSchema<T extends Props>(baseSchema: T) {
-  return schema.oneOf([
-    bucketDateHistogramOperationSchema.extends(baseSchema),
-    bucketTermsOperationSchema.extends(baseSchema),
-    bucketHistogramOperationSchema.extends(baseSchema),
-    bucketRangesOperationSchema.extends(baseSchema),
-    bucketFiltersOperationSchema.extends(baseSchema),
-  ]);
+export function mergeAllBucketsWithChartDimensionSchema<T extends Props>(
+  baseSchema: T,
+  oneOfOptions?: { meta?: { description?: string } }
+) {
+  return schema.oneOf(
+    [
+      bucketDateHistogramOperationSchema.extends(baseSchema),
+      bucketTermsOperationSchema.extends(baseSchema),
+      bucketHistogramOperationSchema.extends(baseSchema),
+      bucketRangesOperationSchema.extends(baseSchema),
+      bucketFiltersOperationSchema.extends(baseSchema),
+    ],
+    oneOfOptions
+  );
 }
 
 /**
diff --git a/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/xy.ts b/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/xy.ts
index 2a243dacc187b..71a1308154145 100644
--- a/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/xy.ts
+++ b/src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/xy.ts
@@ -593,24 +593,48 @@ const xyDataLayerSchemaNoESQL = schema.object(
     ...dataSourceSchema,
     ...xyDataLayerSharedSchema,
     breakdown_by: schema.maybe(
-      mergeAllBucketsWithChartDimensionSchema({
-        collapse_by: schema.maybe(collapseBySchema),
-        color: schema.maybe(colorMappingSchema),
-        aggregate_first: schema.maybe(
-          schema.boolean({
-            meta: { description: 'Whether to aggregate before splitting series' },
-          })
-        ),
-      })
+      mergeAllBucketsWithChartDimensionSchema(
+        {
+          collapse_by: schema.maybe(collapseBySchema),
+          color: schema.maybe(colorMappingSchema),
+          aggregate_first: schema.maybe(
+            schema.boolean({
+              meta: { description: 'Whether to aggregate before splitting series' },
+            })
+          ),
+        },
+        {
+          meta: {
+            description:
+              'Splits each y metric into multiple series by the values of this dimension. For example, breaking down by a host.name field creates one series per host. Unlike x (which defines the domain axis), breakdown_by creates separate visual series within the same chart.',
+          },
+        }
+      )
     ),
     y: schema.arrayOf(
       mergeAllMetricsWithChartDimensionSchemaWithRefBasedOps({
         axis_id: schema.maybe(yAxisIdReferenceSchema),
         color: schema.maybe(staticColorSchema),
       }),
-      { meta: { description: 'Array of metrics to display on Y-axis' }, maxSize: 100 }
+      {
+        meta: {
+          description:
+            'Dependent axis (metric): the measured values. Always use y for metrics regardless of chart orientation — chart orientation is controlled by the type field (e.g. bar vs bar_horizontal), not by swapping x and y.',
+        },
+        maxSize: 100,
+      }
+    ),
+    x: schema.maybe(
+      mergeAllBucketsWithChartDimensionSchema(
+        {},
+        {
+          meta: {
+            description:
+              'Independent axis (dimension): the variable that data is grouped or bucketed by. Always use x for the dimension regardless of chart orientation — for horizontal bar charts, set type to bar_horizontal instead of swapping x and y.',
+          },
+        }
+      )
     ),
-    x: schema.maybe(mergeAllBucketsWithChartDimensionSchema({})),
   },
   {
     meta: {
@@ -635,7 +659,12 @@ const xyDataLayerSchemaESQL = schema.object(
           color: schema.maybe(colorMappingSchema),
           collapse_by: schema.maybe(collapseBySchema),
         },
-        { meta: { description: 'ES|QL column for breakdown' } }
+        {
+          meta: {
+            description:
+              'Splits each y metric into multiple series by the values of this ES|QL column. For example, breaking down by a host.name column creates one series per host. Unlike x (which defines the domain axis), breakdown_by creates separate visual series within the same chart.',
+          },
+        }
       )
     ),
     y: schema.arrayOf(
@@ -646,9 +675,25 @@ const xyDataLayerSchemaESQL = schema.object(
         },
         { meta: { description: 'ES|QL column for Y-axis metric' } }
       ),
-      { meta: { description: 'Array of ES|QL columns for Y-axis metrics' }, maxSize: 100 }
+      {
+        meta: {
+          description:
+            'Dependent axis (metric): the measured values. Always use y for metrics regardless of chart orientation — chart orientation is controlled by the type field (e.g. bar vs bar_horizontal), not by swapping x and y.',
+        },
+        maxSize: 100,
+      }
+    ),
+    x: schema.maybe(
+      esqlColumnWithFormatSchema.extends(
+        {},
+        {
+          meta: {
+            description:
+              'Independent axis (dimension): the variable that data is grouped or bucketed by. Always use x for the dimension regardless of chart orientation — for horizontal bar charts, set type to bar_horizontal instead of swapping x and y.',
+          },
+        }
+      )
     ),
-    x: schema.maybe(esqlColumnWithFormatSchema),
   },
   {
     meta: {