@@ -2,47 +2,58 @@
 
 import {
   createGroundedComparisonTableComponent,
+  criteriaFromAttributes,
   defaultComparisonTableTranslations,
 } from './createGroundedComparisonTable';
 
-import type { Renderer } from '../../../types';
+import type { RecordWithObjectID, Renderer } from '../../../types';
 import type { ClientSideToolComponentProps } from '../types';
-import type { ComparisonTableTranslations } from './createGroundedComparisonTable';
+import type {
+  ComparisonCriterion,
+  ComparisonTableTranslations,
+  GroundedComparisonTableProps,
+} from './createGroundedComparisonTable';
 
 /**
  * Builtin comparison tool (`algolia_compare_products`).
  *
- * The agent triggers this client-side tool when it detects a comparison
- * request. Its arguments name ONLY the products (by objectID) and the attribute
- * *keys* to compare — never the values. Every cell is hydrated from the chat
- * records store (`context.records`, filled by the shopper's comparison
- * selection and by the search tools), so the model physically cannot type
- * (and therefore cannot hallucinate) a price or spec.
- * This is the "grounded table" fix from the agentic-evals comparison study,
- * promoted from the display-block prototype to a first-class tool.
+ * The agent calls this client-side tool to lay out a comparison as a table:
+ * the compared products across the top (hydrated from the chat records store,
+ * `context.records`, so the header never shows a product that isn't in the
+ * catalog) and model-authored criteria down the side. Each criterion carries
+ * one value per product; the agent fills them from the records it has (an
+ * attribute, a detail from the description, a derived verdict), so the table
+ * can say everything a Markdown table could — with a proper layout.
  *
  * Tool-call input it consumes:
  *
  *   {
- *     objectIDs: ['A', 'B'],                    // 2+ products, one row each
- *     attributes: ['price', 'rating'],          // attribute KEYS (also headers)
- *     columns?: ['Product', 'Price', 'Rating'], // optional display labels
- *     intro?: 'Both are great for...'           // optional one-line lead-in
+ *     objectIDs: ['A', 'B'],                   // 2+ products, one column each
+ *     criteria: [                              // one row each, values aligned
+ *       { label: 'Price', values: ['$199', '$299'] },
+ *       { label: 'Battery', values: ['4000 mAh', null] },   // null → "—"
+ *     ],
+ *     intro?: 'Both are great for...'          // optional one-line lead-in
  *   }
  *
- * Any other input field (e.g. smuggled attribute values) is ignored by
- * construction: the renderer never reads values off the input.
+ * The attribute-based shape (`attributes: ['price']`, values read off the
+ * records) is still accepted for agents configured with the previous tool
+ * definition.
  */
 
 export type CompareProductsToolInput = {
   objectIDs?: unknown;
+  criteria?: unknown;
   attributes?: unknown;
   columns?: unknown;
   intro?: unknown;
 };
 
-export type CompareProductsToolProps = {
+export type CompareProductsToolProps<
+  THit extends RecordWithObjectID = RecordWithObjectID,
+> = {
   toolProps: ClientSideToolComponentProps;
+  itemComponent?: GroundedComparisonTableProps<THit>['itemComponent'];
   translations?: Partial<ComparisonTableTranslations>;
 };
 
@@ -56,18 +67,68 @@ function stringList(value: unknown): string[] {
   );
 }
 
-export function createCompareProductsToolComponent({
-  createElement,
-  Fragment,
-}: Renderer) {
-  const GroundedComparisonTable = createGroundedComparisonTableComponent({
+/** Keeps only well-formed `{ label, values[] }` rows. */
+function criteriaList(value: unknown): ComparisonCriterion[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((entry): ComparisonCriterion[] => {
+    if (
+      !entry ||
+      typeof entry !== 'object' ||
+      typeof (entry as ComparisonCriterion).label !== 'string' ||
+      (entry as ComparisonCriterion).label === ''
+    ) {
+      return [];
+    }
+    const values = (entry as ComparisonCriterion).values;
+    return [
+      {
+        label: (entry as ComparisonCriterion).label,
+        values: Array.isArray(values) ? values : [],
+      },
+    ];
+  });
+}
+
+/**
+ * Previous tool contract: `attributes` (keys read off the records) plus an
+ * optional `columns` list labelling `[product, ...attributes]`.
+ */
+function legacyCriteria(
+  objectIDs: string[],
+  input: CompareProductsToolInput,
+  records: ClientSideToolComponentProps['context']['records']
+): ComparisonCriterion[] {
+  const attributes = stringList(input.attributes);
+  const columns = Array.isArray(input.columns)
+    ? stringList(input.columns)
+    : undefined;
+  const labels =
+    columns && columns.length === attributes.length + 1
+      ? columns.slice(1)
+      : columns;
+
+  return criteriaFromAttributes(objectIDs, attributes, records, labels);
+}
+
+export function createCompareProductsToolComponent<
+  THit extends RecordWithObjectID = RecordWithObjectID,
+>({ createElement, Fragment }: Renderer) {
+  const GroundedComparisonTable = createGroundedComparisonTableComponent<THit>({
     createElement,
     Fragment,
   });
 
-  return function CompareProductsTool(userProps: CompareProductsToolProps) {
-    const { toolProps, translations: userTranslations } = userProps;
-    const { message, records } = toolProps.context;
+  return function CompareProductsTool(
+    userProps: CompareProductsToolProps<THit>
+  ) {
+    const {
+      toolProps,
+      itemComponent,
+      translations: userTranslations,
+    } = userProps;
+    const { message, records, sendEvent } = toolProps.context;
 
     const translations: ComparisonTableTranslations = {
       ...defaultComparisonTableTranslations,
@@ -85,23 +146,25 @@ export function createCompareProductsToolComponent({
 
     const input = (message.input ?? {}) as CompareProductsToolInput;
     const objectIDs = stringList(input.objectIDs);
-    const attributes = stringList(input.attributes);
-    const columns = Array.isArray(input.columns)
-      ? stringList(input.columns)
-      : undefined;
     const intro = typeof input.intro === 'string' ? input.intro : undefined;
 
     if (objectIDs.length === 0) {
       return <Fragment />;
     }
 
+    const criteria =
+      input.criteria !== undefined
+        ? criteriaList(input.criteria)
+        : legacyCriteria(objectIDs, input, records);
+
     return (
       <GroundedComparisonTable
         intro={intro}
         objectIDs={objectIDs}
-        attributes={attributes}
-        columns={columns}
+        criteria={criteria}
         records={records}
+        itemComponent={itemComponent}
+        sendEvent={sendEvent}
         translations={translations}
       />
     );
 
@@ -2,6 +2,7 @@
 
 import {
   createGroundedComparisonTableComponent,
+  criteriaFromAttributes,
   defaultComparisonTableTranslations,
 } from './createGroundedComparisonTable';
 
@@ -29,9 +30,9 @@ import type { ComparisonTableTranslations } from './createGroundedComparisonTabl
  *     }
  *   ]
  *
- * The first column is always the product (its `name`/`title`, sourced from the
- * hit). Remaining columns are the requested attributes, read off the hit. A
- * missing attribute renders as an explicit em-dash, never a fabricated value.
+ * Products run across the top (their `name`/`title`, sourced from the hit) and
+ * the requested attributes run down the side, read off the hit. A missing
+ * attribute renders as an explicit em-dash, never a fabricated value.
  */
 
 type MarkdownTableRow = {
@@ -104,12 +105,25 @@ export function createComparisonTableToolComponent({
       return <Fragment />;
     }
 
+    const objectIDs = table.rows.map((row) => row.objectID);
+    const attributes = table.attributes ?? [];
+    // `columns` labels `[product, ...attributes]`; the product label is now
+    // the header row, so only the attribute labels are kept.
+    const labels =
+      table.columns && table.columns.length === attributes.length + 1
+        ? table.columns.slice(1)
+        : table.columns;
+
     return (
       <GroundedComparisonTable
         intro={intro}
-        objectIDs={table.rows.map((row) => row.objectID)}
-        attributes={table.attributes ?? []}
-        columns={table.columns}
+        objectIDs={objectIDs}
+        criteria={criteriaFromAttributes(
+          objectIDs,
+          attributes,
+          records,
+          labels
+        )}
         records={records}
         translations={translations}
       />