@@ -28,6 +28,35 @@ describe('isAgentToolBlock', () => {
       false
     )
   })
+
+  /**
+   * The set stores base types, so a superseded version does not have to be
+   * re-listed at cutover time. `table_v2` shipped while the set still named
+   * only `table`, which kept it out of the picker entirely.
+   */
+  it('includes a versioned core block whose base type is listed', () => {
+    expect(isAgentToolBlock({ type: 'table_v2', category: 'blocks', hideFromToolbar: false })).toBe(
+      true
+    )
+  })
+
+  it('excludes a superseded version of a listed core block', () => {
+    expect(isAgentToolBlock({ type: 'table', category: 'blocks', hideFromToolbar: true })).toBe(
+      false
+    )
+  })
+
+  it('does not admit a versioned block whose base type is unlisted', () => {
+    expect(
+      isAgentToolBlock({ type: 'memory_v2', category: 'blocks', hideFromToolbar: false })
+    ).toBe(false)
+  })
+
+  it('includes every tools-category block regardless of version', () => {
+    expect(
+      isAgentToolBlock({ type: 'confluence_v2', category: 'tools', hideFromToolbar: false })
+    ).toBe(true)
+  })
 })
 
 describe('isMcpToolAlreadySelected', () => {
 
@@ -1,6 +1,14 @@
+import { stripVersionSuffix } from '@sim/utils/string'
 import type { StoredTool } from '@/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/tool-input/types'
 import type { BlockConfig } from '@/blocks/types'
 
+/**
+ * Core blocks the agent tool picker offers even though they are not
+ * `category: 'tools'`. Stored as BASE types and matched after stripping the
+ * `_vN` suffix, so a superseded version never has to be re-listed here at
+ * cutover time. Naming a specific version instead is what kept `table_v2` out
+ * of the picker while the toolbar had already moved to it.
+ */
 const CORE_AGENT_TOOL_TYPES = new Set([
   'api',
   'webhook_request',
@@ -9,18 +17,22 @@ const CORE_AGENT_TOOL_TYPES = new Set([
   'knowledge',
   'function',
   'table',
-  'file_v5',
+  'file',
 ])
 
 /**
  * Checks whether a registered block should appear in the agent tool picker.
+ *
+ * The `hideFromToolbar` guard is what keeps older versions out: superseded
+ * blocks carry it statically, and `getAllBlocks()` projects unrevealed
+ * `preview` blocks into clones that carry it too.
  */
 export function isAgentToolBlock(
   block: Pick<BlockConfig, 'category' | 'hideFromToolbar' | 'type'>
 ): boolean {
-  return (
-    !block.hideFromToolbar && (block.category === 'tools' || CORE_AGENT_TOOL_TYPES.has(block.type))
-  )
+  if (block.hideFromToolbar) return false
+  if (block.category === 'tools') return true
+  return CORE_AGENT_TOOL_TYPES.has(stripVersionSuffix(block.type))
 }
 
 /**
 
@@ -662,6 +662,7 @@ export const BUILT_IN_TOOL_TYPES = new Set([
   'stt',
   'memory',
   'table',
+  'table_v2',
   'webhook_request',
   'workflow',
 ])
 
@@ -0,0 +1,118 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { enrichTableToolDescription, enrichTableToolParameters } from '@/lib/table/llm/enrichment'
+import type { TableSummary } from '@/lib/table/types'
+
+const TABLE: TableSummary = {
+  name: 'Players',
+  columns: [
+    { name: 'status', type: 'string' },
+    { name: 'wins', type: 'number' },
+  ],
+}
+
+const V2_SCHEMA = {
+  properties: {
+    filter: { type: 'object' },
+    order: { type: 'array' },
+    columns: { type: 'array' },
+    limit: { type: 'number' },
+    cursor: { type: 'string' },
+  },
+  required: [] as string[],
+}
+
+describe('enrichTableToolDescription for table_query_rows_v2', () => {
+  const enriched = enrichTableToolDescription('Query rows.', TABLE, 'table_query_rows_v2')
+
+  it('names the real columns', () => {
+    expect(enriched).toContain('status (string)')
+    expect(enriched).toContain('wins (number)')
+  })
+
+  it('teaches the predicate grammar built from a real column', () => {
+    expect(enriched).toContain('{"field":"wins","op":"gte","value":10}')
+    expect(enriched).toContain('"all"')
+  })
+
+  it('never teaches the v1 MongoDB grammar or offset paging', () => {
+    expect(enriched).not.toContain('$eq')
+    expect(enriched).not.toContain('offset')
+  })
+
+  it('describes order rather than sort', () => {
+    expect(enriched).toContain('Example order: [{"field":"wins","direction":"desc"}]')
+  })
+
+  it('omits the example rather than naming a placeholder column', () => {
+    const bare = enrichTableToolDescription(
+      'Query rows.',
+      { name: 'Blobs', columns: [{ name: 'payload', type: 'json' }] },
+      'table_query_rows_v2'
+    )
+    expect(bare).toContain('payload (json)')
+    expect(bare).not.toContain('Example filter')
+  })
+})
+
+describe('enrichTableToolParameters for table_query_rows_v2', () => {
+  const { properties, required } = enrichTableToolParameters(
+    V2_SCHEMA,
+    TABLE,
+    'table_query_rows_v2'
+  )
+
+  /**
+   * The v1 branch force-pushes `filter` into `required` because a v1 query
+   * without one fails. A v2 query without a filter is valid and returns every
+   * row, so forcing it would make the model invent a filter for "list all".
+   */
+  it('leaves filter optional', () => {
+    expect(required).not.toContain('filter')
+  })
+
+  it('describes filter with the predicate grammar and real columns', () => {
+    expect(properties.filter.description).toContain('status, wins')
+    expect(properties.filter.description).toContain('"op"')
+    expect(properties.filter.description).not.toContain('$eq')
+  })
+
+  it('enriches order, columns, limit, and cursor', () => {
+    expect(properties.order.description).toContain('direction')
+    expect(properties.columns.description).toContain('status, wins')
+    expect(properties.limit.description).toContain('5MB')
+    expect(properties.cursor.description).toContain('nextCursor')
+  })
+
+  it('does not enrich a sort property that v2 does not have', () => {
+    expect(properties.sort).toBeUndefined()
+  })
+})
+
+describe('v1 enrichment is unchanged', () => {
+  it('still forces filter required and teaches $eq', () => {
+    const { properties, required } = enrichTableToolParameters(
+      { properties: { filter: { type: 'object' }, sort: { type: 'object' } }, required: [] },
+      TABLE,
+      'table_query_rows'
+    )
+    expect(required).toContain('filter')
+    expect(properties.filter.description).toContain('$eq')
+  })
+
+  /**
+   * Both Table blocks expose the bulk tools and the rows route accepts either
+   * grammar, so these keep teaching $eq — enrichment cannot tell which block
+   * called it.
+   */
+  it('keeps the shared bulk tools on the v1 grammar', () => {
+    const { properties } = enrichTableToolParameters(
+      { properties: { filter: { type: 'object' } }, required: [] },
+      TABLE,
+      'table_update_rows_by_filter'
+    )
+    expect(properties.filter.description).toContain('$eq')
+  })
+})
@@ -9,14 +9,59 @@ import { columnTypeById } from '@/lib/table/column-types'
 import type { TableSummary } from '@/lib/table/types'
 
 /**
- * Operations that use filters and need filter-specific enrichment.
+ * Operations that take a v1 MongoDB-style filter (`{"col": {"$eq": v}}`) and
+ * need filter-specific enrichment.
+ *
+ * The two bulk operations stay here even though the v2 Table block also exposes
+ * them: `resolveBulkFilter` in the rows route accepts either grammar, and
+ * enrichment is keyed on tool id alone — it cannot see which block invoked it —
+ * so one grammar has to be taught, and `$eq` is the one that works for both.
+ * Only the query tool has a v2-exclusive id, which is why it is the only one
+ * that gets a predicate-grammar branch.
  */
 export const FILTER_OPERATIONS = new Set([
   'table_query_rows',
   'table_update_rows_by_filter',
   'table_delete_rows_by_filter',
 ])
 
+/**
+ * The v2 row query. Its filter is a typed predicate
+ * (`{"field":"wins","op":"gte","value":10}`) with `all`/`any` groups, it orders
+ * via `order` rather than `sort`, and it pages by opaque `cursor` rather than
+ * offset — so none of the v1 enrichment above applies to it.
+ */
+const TABLE_QUERY_ROWS_V2 = 'table_query_rows_v2'
+
+/**
+ * Builds a predicate example from real columns, preferring a numeric `gte` over
+ * a string `eq` because ranking and threshold questions are what the grammar
+ * most often gets wrong. Returns an empty string when the table has no column
+ * to name, so the model is never shown a placeholder it might copy literally.
+ */
+function v2PredicateExample(table: TableSummary): string {
+  const stringCol = table.columns.find((c) => c.type === 'string')
+  const numberCol = table.columns.find((c) => c.type === 'number')
+
+  if (numberCol && stringCol) {
+    return `
+
+Example filter (one condition): {"field":"${numberCol.name}","op":"gte","value":10}
+Example filter (AND group): {"all":[{"field":"${numberCol.name}","op":"gte","value":10},{"field":"${stringCol.name}","op":"eq","value":"active"}]}`
+  }
+  if (numberCol) {
+    return `
+
+Example filter: {"field":"${numberCol.name}","op":"gte","value":10}`
+  }
+  if (stringCol) {
+    return `
+
+Example filter: {"field":"${stringCol.name}","op":"eq","value":"active"}`
+  }
+  return ''
+}
+
 /**
  * Operations that need column info for data construction.
  */
@@ -41,6 +86,32 @@ export function enrichTableToolDescription(
 
   const columnList = table.columns.map((col) => `  - ${col.name} (${col.type})`).join('\n')
 
+  if (toolId === TABLE_QUERY_ROWS_V2) {
+    const numberCol = table.columns.find((c) => c.type === 'number')
+    const orderExample = numberCol
+      ? `
+Example order: [{"field":"${numberCol.name}","direction":"desc"}] for highest first, "asc" for lowest first`
+      : ''
+
+    return `${originalDescription}
+
+INSTRUCTIONS:
+1. Build the filter yourself from the user's question - do NOT ask for confirmation
+2. A single condition is a plain object: {"field":"<column>","op":"<operator>","value":<value>}
+3. For multiple conditions wrap them in {"all":[...]} for AND or {"any":[...]} for OR; groups nest
+4. Operators: eq, ne, gt, gte, lt, lte, in, nin, like, ilike, nlike, nilike, contains, startsWith, endsWith, isNull, isNotNull, isEmpty, isNotEmpty
+5. like/ilike use * as the wildcard, e.g. {"field":"name","op":"ilike","value":"*jo*"}
+6. There are no array columns - for substring matching use ilike with *x*
+7. For ranking queries (highest, lowest, Nth, top N) set order and a small limit, e.g. limit 1 for the highest, 2 for the second highest
+8. Omit limit to return every matching row; the query fails if the result exceeds 5MB, so narrow with a filter instead of guessing a limit
+9. With a limit, a page can end early at the byte budget - a non-null nextCursor means more rows remain, so pass it back as cursor and loop until it is null. Never infer completion from page size
+10. Omit the filter only when the user genuinely wants every row
+
+Table "${table.name}" columns:
+${columnList}
+${v2PredicateExample(table)}${orderExample}`
+  }
+
   if (FILTER_OPERATIONS.has(toolId)) {
     const stringCols = table.columns.filter((c) => c.type === 'string')
     const numberCols = table.columns.filter((c) => c.type === 'number')
@@ -140,6 +211,50 @@ export function enrichTableToolParameters(
   const enrichedProperties = { ...llmSchema.properties }
   const enrichedRequired = llmSchema.required ? [...llmSchema.required] : []
 
+  if (toolId === TABLE_QUERY_ROWS_V2) {
+    if (enrichedProperties.filter) {
+      enrichedProperties.filter = {
+        ...enrichedProperties.filter,
+        description: `Predicate built from the user's question using columns: ${columnNames}. One condition is {"field":"<column>","op":"<operator>","value":<value>}; combine with {"all":[...]} for AND or {"any":[...]} for OR. Operators: eq, ne, gt, gte, lt, lte, in, nin, like, ilike, nlike, nilike, contains, startsWith, endsWith, isNull, isNotNull, isEmpty, isNotEmpty. Omit only to match every row.`,
+      }
+    }
+
+    if (enrichedProperties.order) {
+      enrichedProperties.order = {
+        ...enrichedProperties.order,
+        description: `Sort spec as [{"field":"<column>","direction":"asc"|"desc"}] over columns: ${columnNames}. REQUIRED for ranking queries (highest, lowest, Nth).`,
+      }
+    }
+
+    if (enrichedProperties.columns) {
+      enrichedProperties.columns = {
+        ...enrichedProperties.columns,
+        description: `Column names to include in each row. Available: ${columnNames}. Omit to return all columns.`,
+      }
+    }
+
+    if (enrichedProperties.limit) {
+      enrichedProperties.limit = {
+        ...enrichedProperties.limit,
+        description: `Maximum rows per page (min: 1). Omit to return every matching row; the query fails if the result exceeds 5MB, so narrow with a filter rather than guessing. For ranking queries: 1 for the highest/lowest, 2 for the second highest.`,
+      }
+    }
+
+    if (enrichedProperties.cursor) {
+      enrichedProperties.cursor = {
+        ...enrichedProperties.cursor,
+        description: `Opaque cursor from a prior page's nextCursor. Omit for the first page. A non-null nextCursor means more rows remain even if the page came back short - loop until it is null.`,
+      }
+    }
+
+    /*
+     * Deliberately NOT pushed into `required`: unlike v1, a v2 query with no
+     * filter is valid and returns every row. Forcing it would make the model
+     * invent a filter for "list everything".
+     */
+    return { properties: enrichedProperties, required: enrichedRequired }
+  }
+
   if (enrichedProperties.filter && FILTER_OPERATIONS.has(toolId)) {
     enrichedProperties.filter = {
       ...enrichedProperties.filter,
 
@@ -1,5 +1,6 @@
 import { normalizeTablePredicate } from '@/lib/table/query-builder/predicate'
 import { validatePredicateShape } from '@/lib/table/query-builder/validate'
+import { enrichTableToolSchema } from '@/tools/schema-enrichers'
 import type { TableQueryV2Response, TableRowQueryV2Params } from '@/tools/table/types'
 import type { InternalToolConfig } from '@/tools/types'
 
@@ -22,6 +23,17 @@ export const tableQueryRowsV2Tool: InternalToolConfig<TableRowQueryV2Params, Tab
       'as cursor to continue; never infer completion from page size.',
     version: '1.0.0',
 
+    /**
+     * Without this the model never sees the table's real column names and has
+     * to guess field values for the predicate. Every other table tool enriches;
+     * v2's query shipped without it.
+     */
+    toolEnrichment: {
+      dependsOn: 'tableId',
+      enrichTool: (tableId, schema, desc, context) =>
+        enrichTableToolSchema(tableId, 'table_query_rows_v2', schema, desc, context),
+    },
+
     params: {
       tableId: {
         type: 'string',