diff --git a/packages/ai/src/tools/communication-tools/done-tool/helpers/done-tool-file-selection.ts b/packages/ai/src/tools/communication-tools/done-tool/helpers/done-tool-file-selection.ts
index cf6602014..44d2f9acc 100644
--- a/packages/ai/src/tools/communication-tools/done-tool/helpers/done-tool-file-selection.ts
+++ b/packages/ai/src/tools/communication-tools/done-tool/helpers/done-tool-file-selection.ts
@@ -1,9 +1,9 @@
 import type { ChatMessageResponseMessage } from '@buster/server-shared/chats';
 import type { ModelMessage } from 'ai';
-import type { CreateDashboardsOutput } from '../../../visualization-tools/create-dashboards-tool/create-dashboards-tool';
-import type { CreateMetricsOutput } from '../../../visualization-tools/create-metrics-tool/create-metrics-tool';
-import type { ModifyDashboardsOutput } from '../../../visualization-tools/modify-dashboards-tool/modify-dashboards-tool';
-import type { ModifyMetricsOutput } from '../../../visualization-tools/modify-metrics-tool/modify-metrics-tool';
+import type { CreateDashboardsOutput } from '../../../visualization-tools/dashboards/create-dashboards-tool/create-dashboards-tool';
+import type { ModifyDashboardsOutput } from '../../../visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-tool';
+import type { CreateMetricsOutput } from '../../../visualization-tools/metrics/create-metrics-tool/create-metrics-tool';
+import type { ModifyMetricsOutput } from '../../../visualization-tools/metrics/modify-metrics-tool/modify-metrics-tool';
 
 // File tracking type similar to ExtractedFile from file-selection.ts
 interface ExtractedFile {
diff --git a/packages/ai/src/tools/index.ts b/packages/ai/src/tools/index.ts
index 3ddc834aa..71070e043 100644
--- a/packages/ai/src/tools/index.ts
+++ b/packages/ai/src/tools/index.ts
@@ -3,10 +3,10 @@ export { createIdleTool } from './communication-tools/idle-tool/idle-tool';
 export { createSubmitThoughtsTool } from './communication-tools/submit-thoughts-tool/submit-thoughts-tool';
 export { createSequentialThinkingTool } from './planning-thinking-tools/sequential-thinking-tool/sequential-thinking-tool';
 // Visualization tools - factory functions
-export { createCreateMetricsTool } from './visualization-tools/create-metrics-tool/create-metrics-tool';
-export { createModifyMetricsTool } from './visualization-tools/modify-metrics-tool/modify-metrics-tool';
-export { createCreateDashboardsTool } from './visualization-tools/create-dashboards-tool/create-dashboards-tool';
-export { createModifyDashboardsTool } from './visualization-tools/modify-dashboards-tool/modify-dashboards-tool';
+export { createCreateMetricsTool } from './visualization-tools/metrics/create-metrics-tool/create-metrics-tool';
+export { createModifyMetricsTool } from './visualization-tools/metrics/modify-metrics-tool/modify-metrics-tool';
+export { createCreateDashboardsTool } from './visualization-tools/dashboards/create-dashboards-tool/create-dashboards-tool';
+export { createModifyDashboardsTool } from './visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-tool';
 export { executeSql, createExecuteSqlTool } from './database-tools/execute-sql/execute-sql';
 export { executeSqlDocsAgent } from './database-tools/super-execute-sql/super-execute-sql';
 // File tools - factory functions
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-delta.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-delta.test.ts
similarity index 99%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-delta.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-delta.test.ts
index 1f44bf943..0423b1853 100644
--- a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-delta.test.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-delta.test.ts
@@ -30,7 +30,7 @@ describe('createCreateDashboardsDelta', () => {
     const database = await import('@buster/database');
     updateMessageEntriesSpy = vi.mocked(database.updateMessageEntries);
 
-    const streaming = await import('../../../utils/streaming/optimistic-json-parser');
+    const streaming = await import('../../../../utils/streaming/optimistic-json-parser');
     OptimisticJsonParser = streaming.OptimisticJsonParser as unknown as {
       parse: ReturnType<typeof vi.fn>;
     };
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-delta.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-delta.ts
similarity index 97%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-delta.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-delta.ts
index 09a7fe723..5d041dff7 100644
--- a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-delta.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-delta.ts
@@ -4,7 +4,7 @@ import type { ToolCallOptions } from 'ai';
 import {
   OptimisticJsonParser,
   getOptimisticValue,
-} from '../../../utils/streaming/optimistic-json-parser';
+} from '../../../../utils/streaming/optimistic-json-parser';
 import type {
   CreateDashboardsContext,
   CreateDashboardsFile,
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-execute.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-execute.ts
similarity index 99%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-execute.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-execute.ts
index d7f53a142..321b0b4cc 100644
--- a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-execute.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-execute.ts
@@ -11,7 +11,7 @@ import { wrapTraced } from 'braintrust';
 import { inArray } from 'drizzle-orm';
 import * as yaml from 'yaml';
 import { z } from 'zod';
-import { trackFileAssociations } from '../file-tracking-helper';
+import { trackFileAssociations } from '../../file-tracking-helper';
 import { createInitialDashboardVersionHistory } from '../version-history-helpers';
 import type { DashboardYml } from '../version-history-types';
 import type {
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-finish.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-finish.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-finish.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-finish.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-finish.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-finish.ts
similarity index 94%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-finish.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-finish.ts
index 132f4a6fc..a34dc1dea 100644
--- a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-finish.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-finish.ts
@@ -1,7 +1,7 @@
 import { updateMessageEntries } from '@buster/database';
 import type { ChatMessageReasoningMessage } from '@buster/server-shared/chats';
 import type { ToolCallOptions } from 'ai';
-import type { DoneToolInput } from '../../communication-tools/done-tool/done-tool';
+import type { DoneToolInput } from '../../../communication-tools/done-tool/done-tool';
 import type {
   CreateDashboardsContext,
   CreateDashboardsInput,
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-start.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-start.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-start.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-start.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-start.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-start.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-start.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-start.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-streaming.int.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-streaming.int.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-streaming.int.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-streaming.int.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-tool.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-tool.ts
similarity index 97%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-tool.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-tool.ts
index d2b785fd8..a4219ed11 100644
--- a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/create-dashboards-tool.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/create-dashboards-tool.ts
@@ -4,7 +4,7 @@ import { createCreateDashboardsDelta } from './create-dashboards-delta';
 import { createCreateDashboardsExecute } from './create-dashboards-execute';
 import { createCreateDashboardsFinish } from './create-dashboards-finish';
 import { createCreateDashboardsStart } from './create-dashboards-start';
-import { getDashboardToolDescription } from './get-dashboard-tool-descripton';
+import { getDashboardToolDescription } from '../helpers/get-dashboard-tool-descripton';
 
 // Input schema for the create dashboards tool
 const CreateDashboardsInputSchema = z.object({
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.ts b/packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/create-dashboards-tool/helpers/create-dashboards-tool-transform-helper.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/dashboard-tool-description.txt b/packages/ai/src/tools/visualization-tools/dashboards/helpers/dashboard-tool-description.txt
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/dashboard-tool-description.txt
rename to packages/ai/src/tools/visualization-tools/dashboards/helpers/dashboard-tool-description.txt
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/get-dashboard-tool-descripton.ts b/packages/ai/src/tools/visualization-tools/dashboards/helpers/get-dashboard-tool-descripton.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/get-dashboard-tool-descripton.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/helpers/get-dashboard-tool-descripton.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-dashboards-tool/get-dashboard-tool-prompt.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/helpers/get-dashboard-tool-prompt.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-dashboards-tool/get-dashboard-tool-prompt.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/helpers/get-dashboard-tool-prompt.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/helpers/modify-dashboards-transform-helper.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-delta.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-delta.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-delta.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-delta.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-delta.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-delta.ts
similarity index 98%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-delta.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-delta.ts
index 5d6bd7f2f..7d6ae18fe 100644
--- a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-delta.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-delta.ts
@@ -4,7 +4,7 @@ import { wrapTraced } from 'braintrust';
 import {
   OptimisticJsonParser,
   getOptimisticValue,
-} from '../../../utils/streaming/optimistic-json-parser';
+} from '../../../../utils/streaming/optimistic-json-parser';
 import {
   TOOL_KEYS,
   createDashboardsReasoningMessage,
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-execute.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-execute.ts
similarity index 99%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-execute.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-execute.ts
index 16065b785..1324b9e54 100644
--- a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-execute.ts
+++ b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-execute.ts
@@ -6,7 +6,7 @@ import { wrapTraced } from 'braintrust';
 import { and, eq, inArray, isNull } from 'drizzle-orm';
 import * as yaml from 'yaml';
 import { z } from 'zod';
-import { trackFileAssociations } from '../file-tracking-helper';
+import { trackFileAssociations } from '../../file-tracking-helper';
 import { addDashboardVersionToHistory, getLatestVersionNumber } from '../version-history-helpers';
 import type { DashboardYml, VersionHistory } from '../version-history-types';
 import {
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-finish.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-finish.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-finish.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-finish.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-finish.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-finish.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-finish.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-finish.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-start.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-start.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-start.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-start.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-start.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-start.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-start.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-start.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-streaming.int.test.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-streaming.int.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-streaming.int.test.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-streaming.int.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-tool.ts b/packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-tool.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-dashboards-tool/modify-dashboards-tool.ts
rename to packages/ai/src/tools/visualization-tools/dashboards/modify-dashboards-tool/modify-dashboards-tool.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-delta.test.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-delta.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-delta.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-delta.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-delta.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-delta.ts
similarity index 98%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-delta.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-delta.ts
index 057415599..25f0cb9c2 100644
--- a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-delta.ts
+++ b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-delta.ts
@@ -3,7 +3,7 @@ import type { ChatMessageReasoningMessage } from '@buster/server-shared/chats';
 import {
   OptimisticJsonParser,
   getOptimisticValue,
-} from '../../../utils/streaming/optimistic-json-parser';
+} from '../../../../utils/streaming/optimistic-json-parser';
 import type {
   CreateMetricsContext,
   CreateMetricsInput,
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-execute.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-execute.ts
similarity index 99%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-execute.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-execute.ts
index 73ceb33fb..80dd80c2f 100644
--- a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-execute.ts
+++ b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-execute.ts
@@ -7,12 +7,12 @@ import { wrapTraced } from 'braintrust';
 import { inArray } from 'drizzle-orm';
 import * as yaml from 'yaml';
 import { z } from 'zod';
-import { getDataSource } from '../../../utils/get-data-source';
+import { getDataSource } from '../../../../utils/get-data-source';
 import {
   createPermissionErrorMessage,
   validateSqlPermissions,
-} from '../../../utils/sql-permissions';
-import { trackFileAssociations } from '../file-tracking-helper';
+} from '../../../../utils/sql-permissions';
+import { trackFileAssociations } from '../../file-tracking-helper';
 import { validateAndAdjustBarLineAxes } from '../helpers/bar-line-axis-validator';
 import { ensureTimeFrameQuoted } from '../helpers/time-frame-helper';
 import type {
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-finish.test.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-finish.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-finish.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-finish.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-finish.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-finish.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-finish.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-finish.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-start.test.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-start.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-start.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-start.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-start.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-start.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-start.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-start.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-streaming.int.test.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-streaming.int.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-streaming.int.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-streaming.int.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-tool.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-tool.ts
similarity index 97%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-tool.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-tool.ts
index 5b8c0c06c..1c7afe0d9 100644
--- a/packages/ai/src/tools/visualization-tools/create-metrics-tool/create-metrics-tool.ts
+++ b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/create-metrics-tool.ts
@@ -4,7 +4,7 @@ import { createCreateMetricsDelta } from './create-metrics-delta';
 import { createCreateMetricsExecute } from './create-metrics-execute';
 import { createCreateMetricsFinish } from './create-metrics-finish';
 import { createCreateMetricsStart } from './create-metrics-start';
-import { getMetricToolDescription } from './get-metric-tool-description';
+import { getMetricToolDescription } from '../helpers/get-metric-tool-description';
 
 const CreateMetricsInputSchema = z.object({
   files: z
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/helpers/create-metrics-transform-helper.test.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/helpers/create-metrics-transform-helper.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/helpers/create-metrics-transform-helper.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/helpers/create-metrics-transform-helper.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/helpers/create-metrics-transform-helper.ts b/packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/helpers/create-metrics-transform-helper.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/helpers/create-metrics-transform-helper.ts
rename to packages/ai/src/tools/visualization-tools/metrics/create-metrics-tool/helpers/create-metrics-transform-helper.ts
diff --git a/packages/ai/src/tools/visualization-tools/helpers/bar-line-axis-validator.test.ts b/packages/ai/src/tools/visualization-tools/metrics/helpers/bar-line-axis-validator.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/helpers/bar-line-axis-validator.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/bar-line-axis-validator.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/helpers/bar-line-axis-validator.ts b/packages/ai/src/tools/visualization-tools/metrics/helpers/bar-line-axis-validator.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/helpers/bar-line-axis-validator.ts
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/bar-line-axis-validator.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/get-metric-tool-description.test.ts b/packages/ai/src/tools/visualization-tools/metrics/helpers/get-metric-tool-description.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/get-metric-tool-description.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/get-metric-tool-description.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/get-metric-tool-description.ts b/packages/ai/src/tools/visualization-tools/metrics/helpers/get-metric-tool-description.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/get-metric-tool-description.ts
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/get-metric-tool-description.ts
diff --git a/packages/ai/src/tools/visualization-tools/create-metrics-tool/metric-tool-description.txt b/packages/ai/src/tools/visualization-tools/metrics/helpers/metric-tool-description.txt
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/create-metrics-tool/metric-tool-description.txt
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/metric-tool-description.txt
diff --git a/packages/ai/src/tools/visualization-tools/helpers/time-frame-helper.test.ts b/packages/ai/src/tools/visualization-tools/metrics/helpers/time-frame-helper.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/helpers/time-frame-helper.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/time-frame-helper.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/helpers/time-frame-helper.ts b/packages/ai/src/tools/visualization-tools/metrics/helpers/time-frame-helper.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/helpers/time-frame-helper.ts
rename to packages/ai/src/tools/visualization-tools/metrics/helpers/time-frame-helper.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.test.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/helpers/modify-metrics-tool-transform-helper.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-delta.test.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-delta.test.ts
similarity index 94%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-delta.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-delta.test.ts
index cf2b66cb7..31ce8bbff 100644
--- a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-delta.test.ts
+++ b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-delta.test.ts
@@ -46,7 +46,7 @@ describe('createModifyMetricsDelta', () => {
   describe('string delta handling', () => {
     it('should accumulate string deltas in argsText', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       (OptimisticJsonParser.parse as any).mockReturnValue({
         parsed: null,
@@ -64,7 +64,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should update parsedArgs when JSON is parsed', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       const parsedData = { files: [{ id: 'metric-1', yml_content: 'content' }] };
       (OptimisticJsonParser.parse as any).mockReturnValue({
@@ -82,7 +82,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should update state files from parsed array', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       (OptimisticJsonParser.parse as any).mockReturnValue({
         parsed: {},
@@ -114,7 +114,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should update existing files in state', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
 
       // Pre-populate state with a file
@@ -142,7 +142,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should handle partial file data', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       (OptimisticJsonParser.parse as any).mockReturnValue({
         parsed: {},
@@ -166,7 +166,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should update database when messageId and reasoningEntryId exist', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       (OptimisticJsonParser.parse as any).mockReturnValue({
         parsed: {},
@@ -191,7 +191,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should not update database when messageId is missing', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       context.messageId = undefined;
 
@@ -210,7 +210,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should not update database when reasoningEntryId is missing', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       state.reasoningEntryId = undefined;
 
@@ -229,7 +229,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should filter undefined entries before creating reasoning message', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
 
       // State with undefined entries
@@ -262,7 +262,7 @@ describe('createModifyMetricsDelta', () => {
 
     it('should handle database update errors gracefully', async () => {
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
       (updateMessageFields as any).mockRejectedValue(new Error('Database error'));
 
@@ -319,7 +319,7 @@ describe('createModifyMetricsDelta', () => {
     it('should log correct information', async () => {
       const consoleSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
       const { OptimisticJsonParser, getOptimisticValue } = await import(
-        '../../../utils/streaming/optimistic-json-parser'
+        '../../../../utils/streaming/optimistic-json-parser'
       );
 
       (OptimisticJsonParser.parse as any).mockReturnValue({
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-delta.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-delta.ts
similarity index 98%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-delta.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-delta.ts
index f3fb4f4f9..e612c7a74 100644
--- a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-delta.ts
+++ b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-delta.ts
@@ -2,7 +2,7 @@ import { updateMessageFields } from '@buster/database';
 import {
   OptimisticJsonParser,
   getOptimisticValue,
-} from '../../../utils/streaming/optimistic-json-parser';
+} from '../../../../utils/streaming/optimistic-json-parser';
 import {
   MODIFY_METRICS_KEYS,
   createModifyMetricsReasoningMessage,
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-execute.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-execute.ts
similarity index 99%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-execute.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-execute.ts
index 643c31100..e2f83a792 100644
--- a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-execute.ts
+++ b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-execute.ts
@@ -4,12 +4,12 @@ import { wrapTraced } from 'braintrust';
 import { eq, inArray } from 'drizzle-orm';
 import * as yaml from 'yaml';
 import { z } from 'zod';
-import { getDataSource } from '../../../utils/get-data-source';
+import { getDataSource } from '../../../../utils/get-data-source';
 import {
   createPermissionErrorMessage,
   validateSqlPermissions,
-} from '../../../utils/sql-permissions';
-import { trackFileAssociations } from '../file-tracking-helper';
+} from '../../../../utils/sql-permissions';
+import { trackFileAssociations } from '../../file-tracking-helper';
 import { validateAndAdjustBarLineAxes } from '../helpers/bar-line-axis-validator';
 import { ensureTimeFrameQuoted } from '../helpers/time-frame-helper';
 import {
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-finish.test.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-finish.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-finish.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-finish.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-finish.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-finish.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-finish.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-finish.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-start.test.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-start.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-start.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-start.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-start.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-start.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-start.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-start.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-streaming.int.test.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-streaming.int.test.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-streaming.int.test.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-streaming.int.test.ts
diff --git a/packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-tool.ts b/packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-tool.ts
similarity index 100%
rename from packages/ai/src/tools/visualization-tools/modify-metrics-tool/modify-metrics-tool.ts
rename to packages/ai/src/tools/visualization-tools/metrics/modify-metrics-tool/modify-metrics-tool.ts