fix(tables): pass enriched query schema to agents

Author: TheodoreSpeaks

apps/sim/executor/handlers/agent/agent-handler.test.ts

@@ -29,6 +29,7 @@ import { SIM_AUTO_MODEL_ID } from '@/providers/models'
 import { getProviderFromModel, transformBlockTool } from '@/providers/utils'
 import type { SerializedBlock, SerializedWorkflow } from '@/serializer/types'
 import { executeTool } from '@/tools'
+import { ToolSchemaEnrichmentError } from '@/tools/params'
 
 process.env.NEXT_PUBLIC_APP_URL = 'http://localhost:3000'
 
@@ -289,6 +290,24 @@ describe('AgentBlockHandler', () => {
       expect(result).toEqual(expectedOutput)
     })
 
+    it('fails fast when a configured tool schema cannot be enriched', async () => {
+      const error = new ToolSchemaEnrichmentError(
+        'table_query_rows',
+        new Error('table metadata unavailable')
+      )
+      mockTransformBlockTool.mockRejectedValueOnce(error)
+
+      await expect(
+        handler.execute(mockContext, mockBlock, {
+          model: 'gpt-4o',
+          userPrompt: 'Query the table',
+          apiKey: 'test-api-key',
+          tools: [{ type: 'table', operation: 'query_rows', usageControl: 'auto' }],
+        })
+      ).rejects.toBe(error)
+      expect(mockExecuteProviderRequest).not.toHaveBeenCalled()
+    })
+
     it('reports a sim-auto run under the sim-auto identity, not the model that served it', async () => {
       mockExecuteProviderRequest.mockResolvedValue({
         content: 'Mocked response content',

apps/sim/executor/handlers/agent/agent-handler.ts

@@ -6,6 +6,7 @@ import { sleep } from '@sim/utils/helpers'
 import { isPlainRecord } from '@sim/utils/object'
 import { truncate } from '@sim/utils/string'
 import { and, eq, inArray, isNull } from 'drizzle-orm'
+import { isDev } from '@/lib/core/config/env-flags'
 import { normalizeStringRecord, normalizeWorkflowVariables } from '@/lib/core/utils/records'
 import { createMcpToolId } from '@/lib/mcp/utils'
 import {
@@ -67,7 +68,7 @@ import {
 import { isAutoModel, SIM_AUTO_MODEL_ID } from '@/providers/models'
 import { getProviderFromModel, transformBlockTool } from '@/providers/utils'
 import type { SerializedBlock } from '@/serializer/types'
-import { filterSchemaForLLM, type ToolSchema } from '@/tools/params'
+import { filterSchemaForLLM, type ToolSchema, ToolSchemaEnrichmentError } from '@/tools/params'
 import { getTool } from '@/tools/utils'
 import { getToolAsync } from '@/tools/utils.server'
 
@@ -247,6 +248,32 @@ export class AgentBlockHandler implements BlockHandler {
       streaming: streamingConfig.shouldUseStreaming ?? false,
     })
 
+    if (isDev) {
+      const tableQueryRowsV1Tools = formattedTools.filter((tool) => {
+        const toolId = tool?.id
+        if (typeof toolId !== 'string') return false
+
+        const isTableQueryRows =
+          toolId === 'table_query_rows' || toolId.startsWith('table_query_rows_')
+        const isV2 = toolId === 'table_query_rows_v2' || toolId.startsWith('table_query_rows_v2_')
+        return isTableQueryRows && !isV2
+      })
+
+      if (tableQueryRowsV1Tools.length > 0) {
+        logger.info('Passing table_query_rows v1 tool schema to agent provider', {
+          blockId: block.id,
+          executionId: ctx.executionId,
+          providerId,
+          model,
+          tools: tableQueryRowsV1Tools.map((tool) => ({
+            id: tool.id,
+            description: tool.description,
+            parameters: tool.parameters,
+          })),
+        })
+      }
+    }
+
     const result = await this.executeProviderRequest(ctx, providerRequest, block, responseFormat)
 
     if (autoRouting && autoRouting.billableRoutingCost > 0) {
@@ -526,6 +553,7 @@ export class AgentBlockHandler implements BlockHandler {
           }
           return this.transformBlockTool(ctx, tool, canonicalModes, toolIndex)
         } catch (error) {
+          if (error instanceof ToolSchemaEnrichmentError) throw error
           logger.error(
             '[AgentHandler] Error creating tool',
             projectAgentDiagnosticMetadata(
@@ -952,6 +980,12 @@ export class AgentBlockHandler implements BlockHandler {
         }),
       getTool,
       canonicalModes,
+      enrichmentContext: {
+        workflowId: ctx.workflowId,
+        workspaceId: ctx.workspaceId,
+        executionId: ctx.executionId,
+        userId: ctx.userId,
+      },
       toolIndex,
       resolveCustomBlockBinding: (blockType: string) =>
         resolveCustomBlockToolBinding(blockType, ctx.workspaceId),

apps/sim/executor/handlers/pi/sim-tools.test.ts

@@ -16,6 +16,7 @@ vi.mock('@/tools/utils.server', () => ({ getToolAsync: vi.fn() }))
 import { buildSimToolSpecs } from '@/executor/handlers/pi/sim-tools'
 import type { ExecutionContext } from '@/executor/types'
 import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
+import { ToolSchemaEnrichmentError } from '@/tools/params'
 
 function executionContext(registry: ResolvedSecretTraceRegistry | undefined): ExecutionContext {
   return {
@@ -76,6 +77,20 @@ describe('buildSimToolSpecs', () => {
     expect(mockTransformBlockTool).not.toHaveBeenCalled()
   })
 
+  it('fails fast when a tool schema cannot be enriched', async () => {
+    const error = new ToolSchemaEnrichmentError(
+      'table_query_rows',
+      new Error('table metadata unavailable')
+    )
+    mockTransformBlockTool.mockRejectedValueOnce(error)
+
+    await expect(
+      buildSimToolSpecs(completeExecutionContext(), [
+        { type: 'table', operation: 'query_rows', usageControl: 'auto' },
+      ])
+    ).rejects.toBe(error)
+  })
+
   it('forwards a trusted _context that an LLM-supplied _context cannot override', async () => {
     mockTransformBlockTool.mockResolvedValue({
       id: 'exa_search',

apps/sim/executor/handlers/pi/sim-tools.ts

@@ -22,6 +22,7 @@ import type { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secr
 import { transformBlockTool } from '@/providers/utils'
 import { executeTool } from '@/tools'
 import { mergeToolParameters } from '@/tools/merge-params'
+import { ToolSchemaEnrichmentError } from '@/tools/params'
 import type { ToolResponse } from '@/tools/types'
 import { getTool } from '@/tools/utils'
 import { getToolAsync } from '@/tools/utils.server'
@@ -97,6 +98,12 @@ export async function buildSimToolSpecs(
         getAllBlocks,
         getTool,
         getToolAsync,
+        enrichmentContext: {
+          workflowId: ctx.workflowId,
+          workspaceId: ctx.workspaceId,
+          executionId: ctx.executionId,
+          userId: ctx.userId,
+        },
         resolveCustomBlockBinding: (blockType: string) =>
           resolveCustomBlockToolBinding(blockType, ctx.workspaceId),
       })
@@ -171,6 +178,7 @@ export async function buildSimToolSpecs(
         },
       })
     } catch (error) {
+      if (error instanceof ToolSchemaEnrichmentError) throw error
       logger.warn('Failed to adapt Sim tool for Pi', {
         type: tool.type,
         error: getErrorMessage(error),

apps/sim/providers/utils.test.ts

@@ -1622,6 +1622,78 @@ describe('transformBlockTool multi-instance unique IDs', () => {
     expect(result?.id).toBe('table_query_rows_tbl_abc')
   })
 
+  it('resolves the canonical table id before enriching the LLM tool schema', async () => {
+    const enrichTool = vi.fn(
+      async (
+        tableId: string,
+        schema: {
+          type: 'object'
+          properties: Record<string, unknown>
+          required: string[]
+        }
+      ) => ({
+        description: `Query rows from ${tableId}`,
+        parameters: {
+          ...schema,
+          properties: {
+            ...schema.properties,
+            customer_name: { type: 'string' },
+          },
+        },
+      })
+    )
+    const result = await transformBlockTool(
+      {
+        type: 'table',
+        operation: 'query_rows',
+        params: { tableSelector: 'tbl_abc' },
+      },
+      {
+        selectedOperation: 'query_rows',
+        getAllBlocks,
+        enrichmentContext: {
+          workspaceId: 'workspace-1',
+          userId: 'user-1',
+        },
+        getTool: (id: string) => ({
+          id,
+          name: 'Query Rows',
+          description: 'Query table rows',
+          params: {
+            tableId: { type: 'string', required: true, visibility: 'user-only' },
+            filter: { type: 'object', visibility: 'user-or-llm' },
+          },
+          toolEnrichment: {
+            dependsOn: 'tableId',
+            enrichTool,
+          },
+        }),
+      }
+    )
+
+    expect(enrichTool).toHaveBeenCalledWith(
+      'tbl_abc',
+      expect.objectContaining({
+        properties: expect.objectContaining({ filter: expect.any(Object) }),
+      }),
+      'Query table rows',
+      {
+        workspaceId: 'workspace-1',
+        userId: 'user-1',
+      }
+    )
+    expect(result).toMatchObject({
+      id: 'table_query_rows_tbl_abc',
+      description: 'Query rows from tbl_abc',
+      params: { tableSelector: 'tbl_abc' },
+      parameters: {
+        properties: {
+          customer_name: { type: 'string' },
+        },
+      },
+    })
+  })
+
   it('appends the table id resolved from the advanced manual input', async () => {
     const result = await transformTable(
       { manualTableId: 'tbl_xyz' },

apps/sim/providers/utils.ts

@@ -5,7 +5,7 @@ import type OpenAI from 'openai'
 import type { BillingAttributionSnapshot } from '@/lib/billing/core/billing-attribution'
 import { formatCreditCost } from '@/lib/billing/credits/conversion'
 import { env } from '@/lib/core/config/env'
-import { getBlacklistedProvidersFromEnv, isHosted } from '@/lib/core/config/env-flags'
+import { getBlacklistedProvidersFromEnv, isDev, isHosted } from '@/lib/core/config/env-flags'
 import {
   normalizeRecord,
   normalizeStringRecord,
@@ -53,6 +53,7 @@ import {
 import type { ProviderId, ProviderToolConfig } from '@/providers/types'
 import { useProvidersStore } from '@/stores/providers/store'
 import { mergeToolParameters } from '@/tools/merge-params'
+import type { WorkflowToolExecutionContext } from '@/tools/types'
 
 const logger = createLogger('ProviderUtils')
 
@@ -629,6 +630,7 @@ export async function transformBlockTool(
     getTool: (toolId: string) => any
     getToolAsync?: (toolId: string) => Promise<any>
     canonicalModes?: Record<string, 'basic' | 'advanced'>
+    enrichmentContext?: WorkflowToolExecutionContext
     /**
      * Server-only resolver for a custom (deploy-as-block) tool's binding (bound
      * workflow + input schema), org-scoped to the consumer. Injected as a dependency
@@ -646,8 +648,15 @@ export async function transformBlockTool(
     toolIndex?: number
   }
 ): Promise<ProviderToolConfig | null> {
-  const { selectedOperation, getAllBlocks, getTool, getToolAsync, canonicalModes, toolIndex } =
-    options
+  const {
+    selectedOperation,
+    getAllBlocks,
+    getTool,
+    getToolAsync,
+    canonicalModes,
+    enrichmentContext,
+    toolIndex,
+  } = options
   const scopedCanonicalModes = scopeCanonicalModesForTool(canonicalModes, toolIndex, block.type)
 
   const blockDef = getAllBlocks().find((b: any) => b.type === block.type)
@@ -755,12 +764,6 @@ export async function transformBlockTool(
 
   const userProvidedParams = block.params || {}
 
-  const {
-    schema: llmSchema,
-    enrichedDescription,
-    modelBlockedParams,
-  } = await createLLMToolSchema(toolConfig, userProvidedParams)
-
   const canonicalGroups: CanonicalGroup[] = blockDef?.subBlocks
     ? Object.values(buildCanonicalIndex(blockDef.subBlocks).groupsById).filter(isCanonicalPair)
     : []
@@ -771,6 +774,12 @@ export async function transformBlockTool(
     scopedCanonicalModes
   )
 
+  const {
+    schema: llmSchema,
+    enrichedDescription,
+    modelBlockedParams,
+  } = await createLLMToolSchema(toolConfig, resolvedResourceParams, enrichmentContext)
+
   let uniqueToolId = toolConfig.id
   let toolName = toolConfig.name
   let toolDescription = enrichedDescription || toolConfig.description
@@ -857,6 +866,16 @@ export async function transformBlockTool(
       }
     : undefined
 
+  if (isDev && toolConfig.id === 'table_query_rows') {
+    logger.info('Prepared table_query_rows v1 tool schema', {
+      toolId: uniqueToolId,
+      tableId: resolvedResourceParams.tableId,
+      enrichmentApplied: Boolean(enrichedDescription),
+      description: toolDescription,
+      parameters: llmSchema,
+    })
+  }
+
   return {
     id: uniqueToolId,
     name: toolName,

apps/sim/tools/params.test.ts

@@ -12,6 +12,7 @@ import {
   isPasswordParameter,
   type ToolParameterConfig,
   type ToolSchema,
+  ToolSchemaEnrichmentError,
   type ValidationResult,
   validateToolParameters,
 } from '@/tools/params'
@@ -130,6 +131,27 @@ describe('Tool Parameters Utils', () => {
       expect(schema.required).not.toContain('apiKey') // user-only, never required for LLM
       expect(schema.required).toContain('message') // user-or-llm + required: true
     })
+
+    it('wraps tool enrichment failures so execution boundaries can fail fast', async () => {
+      const cause = new Error('table metadata unavailable')
+      const toolConfig = {
+        ...mockToolConfig,
+        toolEnrichment: {
+          dependsOn: 'tableId',
+          enrichTool: vi.fn().mockRejectedValue(cause),
+        },
+      }
+
+      const error = await createLLMToolSchema(toolConfig, { tableId: 'tbl_123' }).catch(
+        (caught) => caught
+      )
+
+      expect(error).toBeInstanceOf(ToolSchemaEnrichmentError)
+      expect(error).toMatchObject({
+        message: 'Failed to enrich schema for tool "test_tool"',
+        cause,
+      })
+    })
   })
 
   describe('createUserToolSchema', () => {