@sealab/mcp-server 1.0.2 → 1.0.3

package/src/tools/ai-drawing.test.ts

@@ -0,0 +1,3061 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import * as apiClientModule from '../client/api-client';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { normalizeMcpJsonSchema } from '../schema-normalizer';
+
+vi.mock('../client/api-client', () => ({
+  aiDrawingClient: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() },
+  handleAxiosError: vi.fn((e) => { throw e; }),
+  McpApiError: class McpApiError extends Error {
+    constructor(public status: number, message: string) { super(message); }
+  },
+}));
+
+vi.mock('./ai-drawing-session-review-renderer', () => ({
+  renderAiDrawingSessionReview: vi.fn(),
+}));
+
+import * as rendererModule from './ai-drawing-session-review-renderer';
+import {
+  AiCabinetCoordinateInputSchema,
+  AiCabinetCoordinatePatchInputSchema,
+  AiCabinetCoordinatesDeleteInputSchema,
+  AiCabinetCoordinatesPatchInputListSchema,
+  AiCabinetCoordinatesReplaceInputSchema,
+  AiCanvasImageDeleteInputSchema,
+  AiCanvasImageUploadInputSchema,
+  AiCanvasCabinetPlacementInputSchema,
+  AiCanvasCabinetPlacementPatchSchema,
+  AiCanvasCabinetPlacementsByCanvasInputSchema,
+  AiCanvasCabinetPlacementsDeleteInputSchema,
+  AiCanvasCabinetPlacementsPatchInputSchema,
+  AiCanvasCabinetPlacementsReplaceInputSchema,
+  AiCanvasCabinetPlacementsUpsertInputSchema,
+  AiCartIdParamSchema,
+  AiCartCreateInputSchema,
+  AiCartItemIdParamSchema,
+  AiCartItemInputSchema,
+  AiCartItemPatchSchema,
+  AiCartSnapshotInputSchema,
+  AiCanvasImageInputSchema,
+  AiCanvasMetadataInputSchema,
+  AiCanvasMetaSchema,
+  AiCanvasProjectionCalibrationSchema,
+  ConfigureAiCabinetInputSchema,
+  DeleteAiCabinetInputSchema,
+  DuplicateAiCabinetInputSchema,
+  AiOrderReadyPayloadClearInputSchema,
+  AiOrderReadyPayloadReadInputSchema,
+  AiOrderReadyPayloadSetInputSchema,
+  AiReduxCartImportInputSchema,
+  AiDrawingSessionReviewRenderInputSchema,
+  AiDrawingSessionCreateInputSchema,
+  LinkAiCartToDrawingSessionInputSchema,
+  clearAiCartItemOrderReadyPayload,
+  configureAiCabinet,
+  createAiDrawingSession,
+  deleteAiCabinet,
+  getAiCartItemOrderReadyPayload,
+  importReduxCartItemsToAiCart,
+  linkAiCartToDrawingSession,
+  setAiCartItemOrderReadyPayload,
+  upsertAiCanvasMetadata,
+  upsertAiCanvasImage,
+  uploadAiCanvasImage,
+  deleteAiCanvasImage,
+  getAiCanvasCabinetPlacements,
+  getAiCanvasCabinetPlacementsByCanvas,
+  replaceAiCanvasCabinetPlacements,
+  upsertAiCanvasCabinetPlacements,
+  patchAiCanvasCabinetPlacements,
+  deleteAiCanvasCabinetPlacements,
+  replaceAiCabinetCoordinates,
+  patchAiCabinetCoordinates,
+  deleteAiCabinetCoordinates,
+  createAiCart,
+  getAiCart,
+  getAiCartBySession,
+  syncAiCartSnapshot,
+  patchAiCartItem,
+  deleteAiCartItem,
+  duplicateAiCabinet,
+  getAiDrawingState,
+  renderAiDrawingSessionReviewTool,
+  aiDrawingTools,
+} from './ai-drawing';
+
+describe('getAiDrawingState', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('calls the AI drawing session state endpoint', async () => {
+    const sessionId = '11111111-1111-4111-8111-111111111111';
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({
+      data: {
+        session: { id: sessionId, drawingRevision: 2 },
+        revisions: { drawingRevision: 2 },
+      },
+    });
+
+    const result = await getAiDrawingState({ sessionId });
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(`/sessions/${sessionId}/state`);
+    expect(result).toContain(sessionId);
+    expect(result).toContain('drawingRevision');
+  });
+
+  it('returns API error text from the shared error handler', async () => {
+    const sessionId = '11111111-1111-4111-8111-111111111111';
+    const err = new (apiClientModule.McpApiError as any)(404, 'AI drawing session not found');
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockRejectedValue(err);
+    vi.mocked(apiClientModule.handleAxiosError).mockImplementation(() => { throw err; });
+
+    const result = await getAiDrawingState({ sessionId });
+
+    expect(result).toContain('AI drawing session not found');
+  });
+});
+
+describe('renderAiDrawingSessionReviewTool', () => {
+  const sessionId = '11111111-1111-4111-8111-111111111111';
+
+  beforeEach(() => vi.clearAllMocks());
+
+  it('fetches stored AI drawing state and passes it into the renderer', async () => {
+    const state = {
+      session: { id: sessionId },
+      activeCanvases: ['plan'],
+      activeCart: { items: [{ id: '22222222-2222-4222-8222-222222222222', positionName: 'BASE_01' }] },
+      canvasImages: [],
+      canvasCabinetPlacements: [],
+    };
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({ data: state });
+    vi.mocked(rendererModule.renderAiDrawingSessionReview).mockReturnValue({
+      sessionId,
+      generatedAt: '2026-05-07T00:00:00.000Z',
+      visualInspectionRequired: true,
+      visualReviewStatus: 'requires_native_vision',
+      completionBlockedUntil: 'Open every full-canvas outputImagePath with native vision, record PASS/FAIL/UNCERTAIN per canvas and placement, patch failures, and rerender.',
+      visualInspectionChecklist: [
+        'Open every full-canvas overlay with native vision.',
+        'Separate cabinet boxes must not overlap each other.',
+        'Do not include appliances, fixtures, counters, toe kicks, walls, dimension strings, labels, or blank/context areas.',
+      ],
+      manifestPath: 'D:\\review\\manifest.json',
+      canvases: [
+        {
+          canvasType: 'plan',
+          outputImagePath: 'D:\\review\\plan.png',
+          imageWidth: 100,
+          imageHeight: 80,
+          renderedPlacementCount: 1,
+          sourceBoundaryReviewTasks: [],
+          issues: [],
+        },
+      ],
+      issues: [],
+    });
+
+    const result = await renderAiDrawingSessionReviewTool({
+      sessionId,
+      canvasTypes: ['plan'],
+      outputDir: 'D:\\review',
+      includeManifest: true,
+    });
+    const parsed = JSON.parse(result);
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(`/sessions/${sessionId}/state`);
+    expect(rendererModule.renderAiDrawingSessionReview).toHaveBeenCalledWith(state, {
+      outputDir: 'D:\\review',
+      canvases: ['plan'],
+      writeJsonManifest: true,
+    });
+    expect(parsed).toMatchObject({
+      sessionId,
+      outputDir: 'D:\\review',
+      manifestPath: 'D:\\review\\manifest.json',
+      aggregateIssueCount: 0,
+      visualReviewRequired: true,
+      visualReviewStatus: 'requires_native_vision',
+      completionBlockedUntil: expect.stringContaining('PASS/FAIL/UNCERTAIN'),
+      machineValidationScope: expect.stringContaining('aggregateIssueCount 0 is not visual approval'),
+      completionPolicy: expect.stringContaining('source_boundary_review_required'),
+      visualQaChecklist: expect.arrayContaining([
+        expect.stringContaining('Separate cabinet boxes must not overlap each other'),
+        expect.stringContaining('Do not include appliances, fixtures, counters, toe kicks, walls, dimension strings, labels, or blank/context areas'),
+      ]),
+      reviewImages: [
+        {
+          canvasType: 'plan',
+          outputImagePath: 'D:\\review\\plan.png',
+          imageWidth: 100,
+          imageHeight: 80,
+          renderedPlacementCount: 1,
+          sourceBoundaryReviewTaskCount: 0,
+          issueCount: 0,
+        },
+      ],
+      sourceBoundaryReviewTasks: [],
+    });
+    expect(parsed).not.toHaveProperty('placementReviewCrops');
+    expect(parsed.canvases[0]).not.toHaveProperty('placementReviewCrops');
+    expect(parsed.canvases[0].sourceBoundaryReviewTasks).toEqual([]);
+  });
+
+  it('materializes uploaded session s3Key backgrounds before rendering', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-review-tool-'));
+    const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00]);
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+      headers: { get: vi.fn(() => 'image/png') },
+      arrayBuffer: vi.fn(async () => pngBytes.buffer.slice(pngBytes.byteOffset, pngBytes.byteOffset + pngBytes.byteLength)),
+    } as unknown as Response);
+
+    try {
+      const state = {
+        session: { id: sessionId },
+        activeCanvases: ['plan'],
+        activeCart: { items: [] },
+        canvasImages: [
+          {
+            canvasType: 'plan',
+            imageType: 'background',
+            s3Key: 'ai-drawings/session-1/plan/background/plan.png',
+          },
+        ],
+        canvasCabinetPlacements: [],
+      };
+      vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({ data: state });
+      vi.mocked(rendererModule.renderAiDrawingSessionReview).mockReturnValue({
+        sessionId,
+        generatedAt: '2026-05-07T00:00:00.000Z',
+        canvases: [
+          {
+            canvasType: 'plan',
+            outputImagePath: path.join(tempDir, 'plan-review.png'),
+            imageWidth: 100,
+            imageHeight: 80,
+            renderedPlacementCount: 0,
+            issues: [],
+          },
+        ],
+        issues: [],
+      });
+
+      await renderAiDrawingSessionReviewTool({
+        sessionId,
+        canvasTypes: ['plan'],
+        outputDir: tempDir,
+      });
+
+      expect(fetchSpy).toHaveBeenCalledWith('https://www.thesealab.com/ai-drawings/session-1/plan/background/plan.png');
+      const rendererOptions = vi.mocked(rendererModule.renderAiDrawingSessionReview).mock.calls[0][1];
+      const materializedPath = rendererOptions.imagePathByCanvas?.plan;
+      expect(materializedPath).toBe(path.join(tempDir, 'ai-drawing-session-review-background-plan.png'));
+      expect(fs.existsSync(materializedPath!)).toBe(true);
+    } finally {
+      fetchSpy.mockRestore();
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('returns issue-only no-render output without throwing', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({
+      data: { session: { id: sessionId }, activeCanvases: ['north'] },
+    });
+    vi.mocked(rendererModule.renderAiDrawingSessionReview).mockReturnValue({
+      sessionId,
+      generatedAt: '2026-05-07T00:00:00.000Z',
+      canvases: [
+        {
+          canvasType: 'north',
+          renderedPlacementCount: 0,
+          issues: [
+            {
+              code: 'unsupported_background_image_reference',
+              severity: 'warning',
+              canvasType: 'north',
+              message: 'Canvas north background image is not renderable locally.',
+            },
+          ],
+        },
+      ],
+      issues: [
+        {
+          code: 'unsupported_background_image_reference',
+          severity: 'warning',
+          canvasType: 'north',
+          message: 'Canvas north background image is not renderable locally.',
+        },
+      ],
+    });
+
+    const result = await renderAiDrawingSessionReviewTool({
+      sessionId,
+      outputDir: 'D:\\review',
+    });
+    const parsed = JSON.parse(result);
+
+    expect(parsed.reviewImages).toEqual([]);
+    expect(parsed.aggregateIssueCount).toBe(1);
+    expect(parsed.perCanvasIssues.north[0]).toMatchObject({
+      code: 'unsupported_background_image_reference',
+      severity: 'warning',
+    });
+  });
+
+  it('validates sessionId UUID and outputDir', () => {
+    expect(AiDrawingSessionReviewRenderInputSchema.safeParse({
+      sessionId: 'not-a-uuid',
+      outputDir: 'D:\\review',
+    }).success).toBe(false);
+
+    expect(AiDrawingSessionReviewRenderInputSchema.safeParse({
+      sessionId,
+      outputDir: '   ',
+    }).success).toBe(false);
+
+    expect(AiDrawingSessionReviewRenderInputSchema.safeParse({
+      sessionId,
+    }).success).toBe(false);
+  });
+});
+
+describe('aiDrawingTools', () => {
+  const expectedPhase4ToolNames = [
+      'get_ai_drawing_state',
+      'render_ai_drawing_session_review',
+      'create_ai_drawing_session',
+      'link_ai_cart_to_drawing_session',
+      'upsert_ai_canvas_metadata',
+      'upsert_ai_canvas_image',
+      'upload_ai_canvas_image',
+      'delete_ai_canvas_image',
+      'get_ai_canvas_cabinet_placements',
+      'get_ai_canvas_cabinet_placements_by_canvas',
+      'replace_ai_canvas_cabinet_placements',
+      'upsert_ai_canvas_cabinet_placements',
+      'patch_ai_canvas_cabinet_placements',
+      'delete_ai_canvas_cabinet_placements',
+      'replace_ai_cabinet_coordinates',
+      'patch_ai_cabinet_coordinates',
+      'delete_ai_cabinet_coordinates',
+      'create_ai_cart',
+      'get_ai_cart',
+      'get_ai_cart_by_session',
+      'sync_ai_cart_snapshot',
+      'patch_ai_cart_item',
+      'delete_ai_cart_item',
+      'duplicate_ai_cabinet',
+      'configure_ai_cabinet',
+      'delete_ai_cabinet',
+      'get_ai_cart_item_order_ready_payload',
+      'set_ai_cart_item_order_ready_payload',
+      'clear_ai_cart_item_order_ready_payload',
+      'import_redux_cart_items_to_ai_cart',
+  ];
+
+  it('registers every AI MCP tool exactly once', () => {
+    const toolNames = aiDrawingTools.map((tool) => tool.name);
+
+    expect(toolNames).toEqual(expectedPhase4ToolNames);
+    expect(new Set(toolNames).size).toBe(expectedPhase4ToolNames.length);
+  });
+
+  it('registers every Phase 10 placement MCP tool exactly once', () => {
+    const toolNames = aiDrawingTools.map((tool) => tool.name);
+    const placementToolNames = [
+      'get_ai_canvas_cabinet_placements',
+      'get_ai_canvas_cabinet_placements_by_canvas',
+      'replace_ai_canvas_cabinet_placements',
+      'upsert_ai_canvas_cabinet_placements',
+      'patch_ai_canvas_cabinet_placements',
+      'delete_ai_canvas_cabinet_placements',
+    ];
+
+    for (const name of placementToolNames) {
+      expect(toolNames.filter((toolName) => toolName === name)).toHaveLength(1);
+    }
+  });
+
+  it('registers every Phase 11 cabinet operation MCP tool exactly once', () => {
+    const toolNames = aiDrawingTools.map((tool) => tool.name);
+    const operationToolNames = [
+      'duplicate_ai_cabinet',
+      'configure_ai_cabinet',
+      'delete_ai_cabinet',
+    ];
+
+    for (const name of operationToolNames) {
+      expect(toolNames.filter((toolName) => toolName === name)).toHaveLength(1);
+    }
+  });
+
+  it('registers every Phase 13 order-ready payload MCP tool exactly once', () => {
+    const toolNames = aiDrawingTools.map((tool) => tool.name);
+    const orderReadyToolNames = [
+      'get_ai_cart_item_order_ready_payload',
+      'set_ai_cart_item_order_ready_payload',
+      'clear_ai_cart_item_order_ready_payload',
+    ];
+
+    for (const name of orderReadyToolNames) {
+      expect(toolNames.filter((toolName) => toolName === name)).toHaveLength(1);
+    }
+  });
+
+  it('registers the Phase 14 Redux import MCP tool exactly once', () => {
+    const toolNames = aiDrawingTools.map((tool) => tool.name);
+
+    expect(toolNames.filter((toolName) => toolName === 'import_redux_cart_items_to_ai_cart')).toHaveLength(1);
+  });
+
+  it('registers the Phase 16 review renderer MCP tool exactly once', () => {
+    const toolNames = aiDrawingTools.map((tool) => tool.name);
+
+    expect(toolNames.filter((toolName) => toolName === 'render_ai_drawing_session_review')).toHaveLength(1);
+  });
+
+  it('does not register duplicate AI drawing state tools', () => {
+    expect(aiDrawingTools.filter((tool) => tool.name === 'get_ai_drawing_state')).toHaveLength(1);
+  });
+
+  it('describes every AI MCP tool as backend-owned AIDrawingTool behavior', () => {
+    for (const tool of aiDrawingTools) {
+      expect(tool.description).toContain('AIDrawingTool');
+      expect(tool.description).toContain('backend-owned');
+    }
+  });
+
+  it('describes the review renderer workflow as render, vision inspect, correct, and rerender', () => {
+    const tool = aiDrawingTools.find((candidate) => candidate.name === 'render_ai_drawing_session_review');
+
+    expect(tool?.description).toContain('after writing or updating AI cart items and per-canvas placements');
+    expect(tool?.description).toContain('open every returned full-canvas PNG path with native vision');
+    expect(tool?.description).toContain('complete every returned sourceBoundaryReviewTasks[] item against the actual source drawing pixels');
+    expect(tool?.description).toContain('no per-placement crop artifacts are generated');
+    expect(tool?.description).toContain('apply the visual QA checklist');
+    expect(tool?.description).toContain('Correct bad placements through the existing AI-only placement tools');
+    expect(tool?.description).toContain('render again/rerender');
+    expect(tool?.description).toContain('JSON validity');
+    expect(tool?.description).toContain('not visual correctness');
+    expect(tool?.description).toContain('Completion is blocked until the agent records PASS/FAIL/UNCERTAIN');
+  });
+
+  it('describes native vision as the drawing interpretation source of truth', () => {
+    const syncTool = aiDrawingTools.find((candidate) => candidate.name === 'sync_ai_cart_snapshot');
+    const placementTool = aiDrawingTools.find((candidate) => candidate.name === 'upsert_ai_canvas_cabinet_placements');
+    const reviewTool = aiDrawingTools.find((candidate) => candidate.name === 'render_ai_drawing_session_review');
+
+    for (const tool of [syncTool, placementTool, reviewTool]) {
+      expect(tool?.description).toContain('Native vision on the actual source plan/elevation images is the source of truth');
+      expect(tool?.description).toContain('Run native image analysis first');
+      expect(tool?.description).toContain('use MCP tools only to persist the reviewed session, cart, placements, and review artifacts');
+      expect(tool?.description).toContain('optional trace/diagnostic metadata only');
+      expect(tool?.description).toContain('Do not let raw extracted candidates, tool labels, evidence JSON, schema validity, or MCP-derived guesses override');
+    }
+  });
+
+  it('describes concrete visual QA failure modes for rendered placement review', () => {
+    const tool = aiDrawingTools.find((candidate) => candidate.name === 'render_ai_drawing_session_review');
+
+    expect(tool?.description).toContain('compare each rectangle against the visible drawing');
+    expect(tool?.description).toContain('source drawing pixels are the authority');
+    expect(tool?.description).toContain('inside the actual cabinet face or plan footprint boundaries');
+    expect(tool?.description).toContain('overlap other cabinets, appliances, fixtures, counters, toe kicks, walls, dimension strings, or blank/context areas');
+    expect(tool?.description).toContain('shifted boxes that extend beyond wood/front boundaries');
+    expect(tool?.description).toContain('include refrigerator/range/dishwasher/sink appliance surfaces unless the AI cart item is explicitly an appliance panel/opening');
+    expect(tool?.description).toContain('same positionName/aiCartItemId across plan and elevation');
+    expect(tool?.description).toContain('no obvious visible cabinet is missing');
+    expect(tool?.description).toContain('no side/return/context-only face is treated as a primary cabinet');
+    expect(tool?.description).toContain('labels do not hide boundary errors');
+    expect(tool?.description).toContain('ask the user instead of declaring the review correct');
+  });
+
+  it('tells agents to use dimension and scale anchors for placement sanity checks', () => {
+    const placementTool = aiDrawingTools.find((candidate) => candidate.name === 'upsert_ai_canvas_cabinet_placements');
+    const reviewTool = aiDrawingTools.find((candidate) => candidate.name === 'render_ai_drawing_session_review');
+
+    for (const tool of [placementTool, reviewTool]) {
+      expect(tool?.description).toContain('Use visible dimensions as scale anchors');
+      expect(tool?.description).toContain('read explicit dimension strings');
+      expect(tool?.description).toContain('known catalog widths/heights');
+      expect(tool?.description).toContain('compute pixels-per-inch per canvas when possible');
+      expect(tool?.description).toContain('sanity-check other cabinet sizes and gaps');
+      expect(tool?.description).toContain('Do not resize boxes away from visible boundaries just to force a dimension');
+      expect(tool?.description).toContain('reinspect the source image and correct or ask the user');
+    }
+  });
+
+  it('requires visual review guidance on placement mutation tool descriptions', () => {
+    const placementMutationToolNames = [
+      'replace_ai_canvas_cabinet_placements',
+      'upsert_ai_canvas_cabinet_placements',
+      'patch_ai_canvas_cabinet_placements',
+      'delete_ai_canvas_cabinet_placements',
+    ];
+
+    for (const name of placementMutationToolNames) {
+      expectDescriptionRequiresVisualReview(name);
+    }
+  });
+
+  it('requires visual review guidance on canvas upload and update tool descriptions', () => {
+    const canvasWriteToolNames = [
+      'upsert_ai_canvas_metadata',
+      'upsert_ai_canvas_image',
+      'upload_ai_canvas_image',
+      'delete_ai_canvas_image',
+    ];
+
+    for (const name of canvasWriteToolNames) {
+      expectDescriptionRequiresVisualReview(name);
+    }
+  });
+
+  it('requires visual review guidance on AI cart and cabinet mutation tool descriptions', () => {
+    const cartWriteToolNames = [
+      'create_ai_cart',
+      'sync_ai_cart_snapshot',
+      'patch_ai_cart_item',
+      'delete_ai_cart_item',
+      'duplicate_ai_cabinet',
+      'configure_ai_cabinet',
+      'delete_ai_cabinet',
+      'set_ai_cart_item_order_ready_payload',
+      'clear_ai_cart_item_order_ready_payload',
+      'import_redux_cart_items_to_ai_cart',
+    ];
+
+    for (const name of cartWriteToolNames) {
+      expectDescriptionRequiresVisualReview(name);
+    }
+  });
+
+  it('keeps order-ready and cart guidance tied to catalog, configuration, saved settings, and user choices before READY', () => {
+    const orderConfigurationToolNames = [
+      'create_ai_cart',
+      'sync_ai_cart_snapshot',
+      'set_ai_cart_item_order_ready_payload',
+    ];
+
+    for (const name of orderConfigurationToolNames) {
+      const tool = aiDrawingTools.find((candidate) => candidate.name === name);
+
+      expect(tool?.description).toContain('get_article_context');
+      expect(tool?.description).toContain('get_article_options');
+      expect(tool?.description).toContain('get_my_saved_settings');
+      expect(tool?.description).toContain('get_saved_settings_presets');
+      expect(tool?.description).toContain('ask the user');
+      expect(tool?.description).toContain('READY');
+      expect(tool?.description).toContain('ArticleItemSchema-compatible');
+    }
+  });
+
+  it('keeps the review renderer schema Gemini-compatible', () => {
+    const normalizedSchema = normalizeMcpJsonSchema(
+      zodToJsonSchema(AiDrawingSessionReviewRenderInputSchema, { target: 'openApi3' })
+    );
+
+    expect(findArrayTupleItems(normalizedSchema)).toEqual([]);
+    expect(findBooleanExclusiveBounds(normalizedSchema)).toEqual([]);
+  });
+
+  it('does not introduce protected legacy strings in the review renderer schema or description', () => {
+    const tool = aiDrawingTools.find((candidate) => candidate.name === 'render_ai_drawing_session_review');
+    const rendered = JSON.stringify([
+      tool?.description,
+      normalizeMcpJsonSchema(zodToJsonSchema(AiDrawingSessionReviewRenderInputSchema, { target: 'openApi3' })),
+    ]);
+    const forbiddenTerms = [
+      '/api/mcp/v1/' + 'canvas',
+      '/topic/' + 'drawing-tool',
+      'Drawing' + 'ToolTest',
+      'saved' + '_carts',
+      'cabinets' + '_coordinates',
+    ];
+
+    for (const term of forbiddenTerms) {
+      expect(rendered).not.toContain(term);
+    }
+  });
+});
+
+describe('AI drawing operation tool handlers', () => {
+  const sessionId = '33333333-3333-4333-8333-333333333333';
+  const cartId = '11111111-1111-4111-8111-111111111111';
+  const itemId = '22222222-2222-4222-8222-222222222222';
+  const planViewAssociationEvidence = {
+    basis: 'plan_elevation_marker_review' as const,
+    elevationCanvasType: 'north' as const,
+    detailNumber: '7',
+    planMarkerSide: 'right' as const,
+    selectedPlanObjectIds: ['P_REF'],
+    selectedPlanObjectBboxPx: { x: -0.5, y: 0, width: 3, height: 4 },
+    selectedPlanObjectRole: 'appliance_footprint' as const,
+    sourcePlanObject: validReviewedPlanObject('P_REF', 'appliance_opening'),
+    sharedAnchors: ['appliance_label:REF'],
+    conflictingPlanAnchorsRejected: ['fixture_symbol:SINK'],
+    evidence: 'Detail 7/A-721 is on the right side of the plan marker; association.selectedPlanObjects contains P_REF. Agent vision/image analysis confirms the matched elevation shows the same refrigerator appliance condition with handles, not the sink side.',
+  };
+  const sameCanvasReviewedPlanEvidence = {
+    ...planViewAssociationEvidence,
+    basis: 'same_canvas_reviewed_plan_object' as const,
+    evidence: 'This plan placement comes from same-canvas reviewed plan object P_REF; association.selectedPlanObjects contains P_REF. Agent visual image analysis confirms the selected plan object is the REF refrigerator footprint for the matched elevation.',
+  };
+
+  beforeEach(() => vi.clearAllMocks());
+
+  it('create_ai_drawing_session posts to the AI session endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({ data: { id: sessionId } });
+
+    const result = await createAiDrawingSession({
+      sourceType: 'REDUX_SNAPSHOT',
+      sourceOrderId: 'ORDER-1',
+      sourceSavedCartId: 12,
+      activeAiCartId: cartId,
+    });
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith('/sessions', {
+      sourceType: 'REDUX_SNAPSHOT',
+      sourceOrderId: 'ORDER-1',
+      sourceSavedCartId: 12,
+      activeAiCartId: cartId,
+    });
+    expect(result).toContain(sessionId);
+  });
+
+  it('link_ai_cart_to_drawing_session puts to the active cart endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { id: sessionId, activeAiCartId: cartId } });
+
+    const result = await linkAiCartToDrawingSession({ sessionId, cartId });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(`/sessions/${sessionId}/active-cart/${cartId}`);
+    expect(result).toContain(cartId);
+  });
+
+  it('upsert_ai_canvas_metadata puts to the AI metadata endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { sessionId, canvasType: 'plan' } });
+    const canvasMeta = { projectionCalibration: validPlanProjectionCalibration() };
+
+    const result = await upsertAiCanvasMetadata({
+      sessionId,
+      canvasType: 'plan',
+      canvasMeta,
+      activeCanvases: ['plan', 'north'],
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(`/sessions/${sessionId}/metadata/plan`, {
+      canvasType: 'plan',
+      canvasMeta,
+      activeCanvases: ['plan', 'north'],
+    });
+    expect(result).toContain('plan');
+  });
+
+  it('upsert_ai_canvas_image puts to the AI image endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { sessionId, s3Key: 'ai/plan.png' } });
+
+    const result = await upsertAiCanvasImage({
+      sessionId,
+      canvasType: 'plan',
+      imageType: 'background',
+      s3Key: 'ai/plan.png',
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(`/sessions/${sessionId}/images/plan/background`, {
+      canvasType: 'plan',
+      imageType: 'background',
+      s3Key: 'ai/plan.png',
+    });
+    expect(result).toContain('ai/plan.png');
+  });
+
+  it('upload_ai_canvas_image uploads a local file to the AI multipart endpoint', async () => {
+    const tempPath = path.join(os.tmpdir(), `ai-canvas-${Date.now()}.png`);
+    fs.writeFileSync(tempPath, Buffer.from([137, 80, 78, 71]));
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({
+      data: { sessionId, canvasType: 'east', imageType: 'background', s3Key: `ai-drawings/${sessionId}/east/background/file.png` },
+    });
+
+    try {
+      const result = await uploadAiCanvasImage({
+        sessionId,
+        canvasType: 'east',
+        imageType: 'background',
+        imagePath: tempPath,
+      });
+
+      expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith(
+        `/sessions/${sessionId}/images/east/background/upload`,
+        expect.anything(),
+        expect.objectContaining({ headers: expect.any(Object) })
+      );
+      expect(result).toContain('ai-drawings');
+    } finally {
+      fs.unlinkSync(tempPath);
+    }
+  });
+
+  it('upload_ai_canvas_image rejects unsupported local file extensions before API call', async () => {
+    const result = await uploadAiCanvasImage({
+      sessionId,
+      canvasType: 'east',
+      imageType: 'background',
+      imagePath: 'D:\\testing321\\overlay.txt',
+    });
+
+    expect(result).toContain('Unsupported file extension');
+    expect(apiClientModule.aiDrawingClient.post).not.toHaveBeenCalled();
+  });
+
+  it('delete_ai_canvas_image deletes through the AI image endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.delete).mockResolvedValue({
+      data: { deleted: true, canvasType: 'plan', imageType: 'background' },
+    });
+
+    const result = await deleteAiCanvasImage({
+      sessionId,
+      canvasType: 'plan',
+      imageType: 'background',
+    });
+
+    expect(apiClientModule.aiDrawingClient.delete).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/images/plan/background`
+    );
+    expect(result).toContain('background');
+  });
+
+  it('get_ai_canvas_cabinet_placements calls the all-placement endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({
+      data: [{ canvasType: 'plan', positionName: 'BASE_01' }],
+    });
+
+    const result = await getAiCanvasCabinetPlacements({ sessionId });
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(`/sessions/${sessionId}/placements`);
+    expect(result).toContain('BASE_01');
+  });
+
+  it('get_ai_canvas_cabinet_placements_by_canvas calls the canvas placement endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({
+      data: [{ canvasType: 'east', positionName: 'BASE_01' }],
+    });
+
+    const result = await getAiCanvasCabinetPlacementsByCanvas({ sessionId, canvasType: 'east' });
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(`/sessions/${sessionId}/placements/east`);
+    expect(result).toContain('east');
+  });
+
+  it('replace_ai_canvas_cabinet_placements puts one-canvas placement replacement payload', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: [{ canvasType: 'plan', positionName: 'BASE_01', placementRevision: 1 }],
+    });
+
+    const result = await replaceAiCanvasCabinetPlacements({
+      sessionId,
+      canvasType: 'plan',
+      placements: [
+        {
+          aiCartItemId: itemId,
+          positionName: 'BASE_01',
+          centerX: 120,
+          centerY: 240,
+          width: 60,
+          height: 80,
+          rotation: 0,
+          placementSpace: 'IMAGE_PIXELS',
+          basisImageWidthPx: 1000,
+          basisImageHeightPx: 800,
+          source: 'MCP',
+          viewAssociationEvidence: sameCanvasReviewedPlanEvidence,
+        },
+      ],
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(`/sessions/${sessionId}/placements/plan`, {
+      placements: [
+        {
+          aiCartItemId: itemId,
+          positionName: 'BASE_01',
+          centerX: 120,
+          centerY: 240,
+          width: 60,
+          height: 80,
+          rotation: 0,
+          placementSpace: 'IMAGE_PIXELS',
+          basisImageWidthPx: 1000,
+          basisImageHeightPx: 800,
+          source: 'MCP',
+        },
+      ],
+    });
+    expect(result).toContain('BASE_01');
+  });
+
+  it('upsert_ai_canvas_cabinet_placements posts one-canvas placement upsert payload', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({
+      data: [{ canvasType: 'east', positionName: 'BASE_01', placementRevision: 2 }],
+    });
+
+    const result = await upsertAiCanvasCabinetPlacements({
+      sessionId,
+      canvasType: 'east',
+      placements: [
+        {
+          positionName: 'BASE_01',
+          centerX: 120,
+          centerY: 240,
+          width: 60,
+          height: 80,
+          placementSpace: 'IMAGE_PIXELS',
+          source: 'MCP',
+        },
+      ],
+    });
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith(`/sessions/${sessionId}/placements/east`, {
+      placements: [
+        {
+          positionName: 'BASE_01',
+          centerX: 120,
+          centerY: 240,
+          width: 60,
+          height: 80,
+          placementSpace: 'IMAGE_PIXELS',
+          source: 'MCP',
+        },
+      ],
+    });
+    expect(result).toContain('BASE_01');
+  });
+
+  it('patch_ai_canvas_cabinet_placements patches one-canvas placement payloads', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.patch).mockResolvedValue({
+      data: [{ canvasType: 'north', positionName: 'WALL_01', centerX: 90 }],
+    });
+
+    const result = await patchAiCanvasCabinetPlacements({
+      sessionId,
+      canvasType: 'north',
+      placements: [
+        {
+          positionName: 'WALL_01',
+          centerX: 90,
+          source: 'AI',
+        },
+      ],
+    });
+
+    expect(apiClientModule.aiDrawingClient.patch).toHaveBeenCalledWith(`/sessions/${sessionId}/placements/north`, {
+      placements: [
+        {
+          positionName: 'WALL_01',
+          centerX: 90,
+          source: 'AI',
+        },
+      ],
+    });
+    expect(result).toContain('WALL_01');
+  });
+
+  it('delete_ai_canvas_cabinet_placements posts selected position names to one-canvas delete endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({
+      data: { canvasType: 'east', deletedPositionNames: ['BASE_01'] },
+    });
+
+    const result = await deleteAiCanvasCabinetPlacements({
+      sessionId,
+      canvasType: 'east',
+      positionNames: ['BASE_01'],
+    });
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith(`/sessions/${sessionId}/placements/east/delete`, {
+      positionNames: ['BASE_01'],
+    });
+    expect(result).toContain('BASE_01');
+  });
+
+  it('duplicate_ai_cabinet posts to the session cabinet duplicate endpoint with selected placement copy fields', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({
+      data: { duplicateItem: { id: itemId, positionName: 'BASE_01_copy' } },
+    });
+
+    const result = await duplicateAiCabinet({
+      sessionId,
+      itemId,
+      positionName: 'BASE_01_copy',
+      sourceCanvasType: 'plan',
+      sourcePlacementPositionName: 'BASE_01',
+      placementOffsetX: 24,
+      placementOffsetY: 12,
+      source: 'MCP',
+    });
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/duplicate`,
+      {
+        positionName: 'BASE_01_copy',
+        selectedCanvasType: 'plan',
+        sourcePlacementPositionName: 'BASE_01',
+        placementOffsetX: 24,
+        placementOffsetY: 12,
+        source: 'MCP',
+      }
+    );
+    expect(result).toContain('BASE_01_copy');
+  });
+
+  it('configure_ai_cabinet patches supported backend item fields and serializes payload objects', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.patch).mockResolvedValue({
+      data: { configuredItem: { id: itemId, positionName: 'BASE_02' } },
+    });
+
+    const result = await configureAiCabinet({
+      sessionId,
+      itemId,
+      positionName: 'BASE_02',
+      displayName: 'Configured Base',
+      serialNumber: 'SN-2',
+      frontendItemId: 'frontend-2',
+      originalFrontendItemId: 'original-2',
+      originalPositionName: 'BASE_01',
+      groupId: 'run-1',
+      quantity: 1,
+      originalQuantity: 1,
+      width: 36,
+      height: 40,
+      depth: 25,
+      originalItemPayload: { configured: true },
+      source: 'MCP',
+    });
+
+    expect(apiClientModule.aiDrawingClient.patch).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/configure`,
+      {
+        positionName: 'BASE_02',
+        displayName: 'Configured Base',
+        serialNumber: 'SN-2',
+        frontendItemId: 'frontend-2',
+        originalFrontendItemId: 'original-2',
+        originalPositionName: 'BASE_01',
+        groupId: 'run-1',
+        quantity: 1,
+        originalQuantity: 1,
+        width: 36,
+        height: 40,
+        depth: 25,
+        originalItemPayload: '{"configured":true}',
+        source: 'MCP',
+      }
+    );
+    expect(result).toContain('BASE_02');
+  });
+
+  it('delete_ai_cabinet deletes one session active-cart cabinet item', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.delete).mockResolvedValue({
+      data: { deletedItemId: itemId, deletedPositionName: 'BASE_01' },
+    });
+
+    const result = await deleteAiCabinet({ sessionId, itemId });
+
+    expect(apiClientModule.aiDrawingClient.delete).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}`
+    );
+    expect(result).toContain('BASE_01');
+  });
+
+  it('get_ai_cart_item_order_ready_payload calls the session item payload endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'READY' },
+    });
+
+    const result = await getAiCartItemOrderReadyPayload({ sessionId, itemId });
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/order-ready-payload`
+    );
+    expect(result).toContain('READY');
+  });
+
+  it('set_ai_cart_item_order_ready_payload rejects arbitrary READY payloads before API call', async () => {
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: { arbitrary: true },
+      orderReadySource: 'MCP',
+    });
+
+    expect(result).toContain('READY rejected');
+    expect(result).toContain('ArticleItemSchema');
+    expect(apiClientModule.aiDrawingClient.put).not.toHaveBeenCalled();
+  });
+
+  it('set_ai_cart_item_order_ready_payload rejects serial and dimensions only READY payloads', async () => {
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: thinArticleItemPayload(),
+      orderReadySource: 'MCP',
+    });
+
+    expect(result).toContain('READY rejected');
+    expect(result).toContain('serialNumber, positionName, width, height, and depth alone are not enough');
+    expect(apiClientModule.aiDrawingClient.put).not.toHaveBeenCalled();
+  });
+
+  it('set_ai_cart_item_order_ready_payload accepts valid ArticleItemSchema-compatible READY payloads', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'READY', orderReadyRevision: 1 },
+    });
+    const payload = validArticleItemPayload();
+    const drawingClassificationEvidence = validDrawingClassificationEvidence();
+
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: payload,
+      orderReadySource: 'MCP',
+      orderReadyMessages: [{ severity: 'info', message: 'Validated with order schema' }],
+      drawingClassificationEvidence,
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/order-ready-payload`,
+      {
+        orderReadyPayload: payload,
+        orderReadyStatus: 'READY',
+        orderReadyMessages: [{ severity: 'info', message: 'Validated with order schema' }],
+        orderReadySource: 'MCP',
+      }
+    );
+    expect(result).toContain('READY');
+  });
+
+  it('set_ai_cart_item_order_ready_payload allows non-base READY without drawing classification evidence by default', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'READY', orderReadyRevision: 1 },
+    });
+
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validUpperArticleItemPayload(),
+      orderReadySource: 'MCP',
+    });
+
+    expect(result).toContain('READY');
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalled();
+  });
+
+  it('set_ai_cart_item_order_ready_payload rejects base READY without body-height exclusion evidence', async () => {
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validArticleItemPayload(),
+      orderReadySource: 'MCP',
+    });
+
+    expect(result).toContain('READY rejected');
+    expect(result).toContain('baseCabinetBodyHeightEvidence');
+    expect(result).toContain('countertop and toekick_plinth excluded');
+    expect(apiClientModule.aiDrawingClient.put).not.toHaveBeenCalled();
+  });
+
+  it('set_ai_cart_item_order_ready_payload leaves visual evidence enforcement to rendered review by default', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'READY', orderReadyRevision: 1 },
+    });
+
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validArticleItemPayload(),
+      orderReadySource: 'MCP',
+      drawingClassificationEvidence: {
+        ...validDrawingClassificationEvidence(),
+        primaryViewPlaneRole: 'return_side_face',
+        frontFaceEvidence: 'Agent vision review says this is a perpendicular side view / return side face.',
+        frontFaceFeatures: ['side_panel_or_return_visible'],
+        semanticTypeEvidence: 'Side-view geometry only; not a primary front-facing cabinet in the north elevation.',
+      },
+    });
+
+    expect(result).toContain('READY');
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalled();
+  });
+
+  it('set_ai_cart_item_order_ready_payload writes needs-configuration and blocked messages safely', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION' },
+    });
+
+    const needsConfig = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION',
+      orderReadyMessages: [
+        {
+          severity: 'error',
+          field: 'caseMaterial',
+          message:
+            'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; ask the user for caseMaterial.',
+        },
+      ],
+      orderReadySource: 'MCP',
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/order-ready-payload`,
+      {
+        orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION',
+        orderReadyMessages: [
+          {
+            severity: 'error',
+            field: 'caseMaterial',
+            message:
+              'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; ask the user for caseMaterial.',
+          },
+        ],
+        orderReadySource: 'MCP',
+      }
+    );
+    expect(needsConfig).toContain('NEEDS_AGENT_CONFIGURATION');
+
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'BLOCKED' },
+    });
+    const blocked = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'BLOCKED',
+      orderReadyMessages: [
+        {
+          severity: 'blocker',
+          field: 'serialNumber',
+          message:
+            'Tried get_article_context and get_article_options but no catalog match was available; saved settings not applicable until a valid serialNumber is selected.',
+        },
+      ],
+    });
+
+    expect(blocked).toContain('BLOCKED');
+  });
+
+  it('set_ai_cart_item_order_ready_payload persists bare needs-configuration without prose evidence gating', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION' },
+    });
+
+    const result = await setAiCartItemOrderReadyPayload({
+      sessionId,
+      itemId,
+      orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION',
+      orderReadyMessages: [
+        { severity: 'error', field: 'caseMaterial', message: 'Ask the user for case material.' },
+      ],
+      orderReadySource: 'MCP',
+    });
+
+    expect(result).toContain('NEEDS_AGENT_CONFIGURATION');
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/order-ready-payload`,
+      expect.objectContaining({
+        orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION',
+        orderReadyMessages: [
+          { severity: 'error', field: 'caseMaterial', message: 'Ask the user for case material.' },
+        ],
+      })
+    );
+  });
+
+  it('clear_ai_cart_item_order_ready_payload calls the session item clear endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.delete).mockResolvedValue({
+      data: { id: itemId, orderReadyStatus: 'NOT_PREPARED' },
+    });
+
+    const result = await clearAiCartItemOrderReadyPayload({ sessionId, itemId });
+
+    expect(apiClientModule.aiDrawingClient.delete).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/${itemId}/order-ready-payload`
+    );
+    expect(result).toContain('NOT_PREPARED');
+  });
+
+  it('import_redux_cart_items_to_ai_cart posts rich Redux items to the session import endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({
+      data: { sessionId, createdCount: 1, updatedCount: 0 },
+    });
+    const input = validReduxCartImportInput(sessionId);
+
+    const result = await importReduxCartItemsToAiCart(input);
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith(
+      `/sessions/${sessionId}/cart-items/import-redux`,
+      {
+        items: [
+          expect.objectContaining({
+            frontendItemId: 'frontend-1',
+            positionName: 'BASE_01',
+            originalItemPayload: input.items[0].originalItemPayload,
+            orderReadyStatus: 'READY',
+            orderReadyPayload: input.items[0].orderReadyPayload,
+          }),
+        ],
+      }
+    );
+    expect(result).toContain('createdCount');
+  });
+
+  it('replace_ai_cabinet_coordinates puts coordinate replacement payload', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: [{ positionName: 'BASE_01' }] });
+
+    const result = await replaceAiCabinetCoordinates({
+      sessionId,
+      coordinates: [
+        {
+          positionName: 'BASE_01',
+          aiCartItemId: itemId,
+          x: 12,
+          y: 24,
+          z: 4,
+          rotation: 90,
+          source: 'MCP',
+          coordinateEvidence: validCoordinateEvidence(),
+        },
+      ],
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(`/sessions/${sessionId}/coordinates`, {
+      coordinates: [
+        {
+          positionName: 'BASE_01',
+          aiCartItemId: itemId,
+          x: 12,
+          y: 24,
+          z: 4,
+          rotation: 90,
+          source: 'MCP',
+        },
+      ],
+    });
+    expect(result).toContain('BASE_01');
+  });
+
+  it('patch_ai_cabinet_coordinates patches coordinate payloads by positionName', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.patch).mockResolvedValue({ data: [{ positionName: 'BASE_01', rotation: 180 }] });
+
+    const result = await patchAiCabinetCoordinates({
+      sessionId,
+      coordinates: [
+        {
+          positionName: 'BASE_01',
+          x: 33,
+          y: 44,
+          z: 6,
+          rotation: 180,
+          source: 'MCP',
+          coordinateEvidence: validCoordinateEvidence(),
+        },
+      ],
+    });
+
+    expect(apiClientModule.aiDrawingClient.patch).toHaveBeenCalledWith(`/sessions/${sessionId}/coordinates`, {
+      coordinates: [
+        {
+          positionName: 'BASE_01',
+          x: 33,
+          y: 44,
+          z: 6,
+          rotation: 180,
+          source: 'MCP',
+        },
+      ],
+    });
+    expect(result).toContain('BASE_01');
+  });
+
+  it('delete_ai_cabinet_coordinates posts to the coordinate delete endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({ data: { deletedPositionNames: ['BASE_01'] } });
+
+    const result = await deleteAiCabinetCoordinates({ sessionId, positionNames: ['BASE_01'] });
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith(`/sessions/${sessionId}/coordinates/delete`, {
+      positionNames: ['BASE_01'],
+    });
+    expect(result).toContain('BASE_01');
+  });
+
+  it('AI drawing tool input schemas reject invalid UUIDs, canvas types, and rotations', () => {
+    expect(AiDrawingSessionCreateInputSchema.safeParse({ activeAiCartId: 'bad' }).success).toBe(false);
+    expect(LinkAiCartToDrawingSessionInputSchema.safeParse({ sessionId: 'bad', cartId }).success).toBe(false);
+    expect(AiCanvasMetadataInputSchema.safeParse({ sessionId, canvasType: 'ceiling' }).success).toBe(false);
+    expect(AiCanvasImageInputSchema.safeParse({ sessionId, canvasType: 'plan', imageType: 'thumbnail', s3Key: 'a' }).success).toBe(false);
+    expect(AiCabinetCoordinateInputSchema.safeParse({ positionName: 'BASE_01', x: 1, y: 2, rotation: 45 }).success).toBe(false);
+    expect(AiCabinetCoordinatePatchInputSchema.safeParse({ positionName: 'BASE_01', rotation: 45 }).success).toBe(false);
+    expect(AiCabinetCoordinatesReplaceInputSchema.safeParse({ sessionId: 'bad', coordinates: [] }).success).toBe(false);
+    expect(AiCabinetCoordinatesPatchInputListSchema.safeParse({ sessionId, coordinates: [] }).success).toBe(false);
+    expect(AiCabinetCoordinatesDeleteInputSchema.safeParse({ sessionId, positionNames: [] }).success).toBe(false);
+    expect(AiCabinetCoordinatesReplaceInputSchema.safeParse({
+      sessionId,
+      coordinates: [{ positionName: 'BASE_01', x: 1, y: 2, source: 'MCP' }],
+    }).success).toBe(true);
+    expect(AiCabinetCoordinatesReplaceInputSchema.safeParse({
+      sessionId,
+      coordinates: [{ positionName: 'BASE_01', x: 1, y: 2, source: 'MCP', coordinateEvidence: validCoordinateEvidence() }],
+    }).success).toBe(true);
+  });
+
+  it('AI cabinet operation schemas validate UUIDs and supported fields', () => {
+    expect(DuplicateAiCabinetInputSchema.safeParse({ sessionId: 'bad', itemId }).success).toBe(false);
+    expect(DuplicateAiCabinetInputSchema.safeParse({ sessionId, itemId: 'bad' }).success).toBe(false);
+    expect(ConfigureAiCabinetInputSchema.safeParse({ sessionId: 'bad', itemId, width: 36 }).success).toBe(false);
+    expect(DeleteAiCabinetInputSchema.safeParse({ sessionId, itemId: 'bad' }).success).toBe(false);
+
+    expect(DuplicateAiCabinetInputSchema.safeParse({
+      sessionId,
+      itemId,
+      positionName: 'BASE_02',
+      sourceCanvasType: 'east',
+      sourcePlacementPositionName: 'BASE_01',
+      placementOffsetX: 12,
+      placementOffsetY: 8,
+      source: 'MCP',
+    }).success).toBe(true);
+
+    expect(DuplicateAiCabinetInputSchema.safeParse({
+      sessionId,
+      itemId,
+      sourceCanvasType: 'ceiling',
+    }).success).toBe(false);
+
+    expect(ConfigureAiCabinetInputSchema.safeParse({
+      sessionId,
+      itemId,
+      positionName: 'BASE_02',
+      displayName: 'Configured',
+      serialNumber: 'SN-2',
+      frontendItemId: 'frontend-2',
+      originalFrontendItemId: 'original-2',
+      originalPositionName: 'BASE_01',
+      groupId: 'run-1',
+      quantity: 1,
+      originalQuantity: 2,
+      width: 36,
+      height: 40,
+      depth: 25,
+      originalItemPayload: { configured: true },
+      source: 'MCP',
+    }).success).toBe(true);
+
+    expect(ConfigureAiCabinetInputSchema.safeParse({
+      sessionId,
+      itemId,
+      unsupportedField: true,
+    }).success).toBe(false);
+
+    expect(ConfigureAiCabinetInputSchema.safeParse({
+      sessionId,
+      itemId,
+      quantity: 2,
+    }).success).toBe(false);
+  });
+
+  it('AI canvas placement schemas validate UUIDs canvas types required fields and positive dimensions', () => {
+    expect(AiCanvasCabinetPlacementsByCanvasInputSchema.safeParse({ sessionId: 'bad', canvasType: 'plan' }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsByCanvasInputSchema.safeParse({ sessionId, canvasType: 'ceiling' }).success).toBe(false);
+
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+    }).success).toBe(true);
+
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerY: 20,
+      width: 30,
+      height: 40,
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 0,
+      height: 40,
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: -1,
+    }).success).toBe(false);
+  });
+
+  it('AI canvas placement schemas validate optional placement fields strictly', () => {
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+      aiCartItemId: itemId,
+      rotation: 12.5,
+      placementSpace: 'IMAGE_PIXELS',
+      basisImageWidthPx: 1000,
+      basisImageHeightPx: 800,
+      source: 'MCP',
+    }).success).toBe(true);
+
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+      placementSpace: 'ROOM_INCHES',
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+      basisImageWidthPx: 0,
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+      basisImageHeightPx: -5,
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementInputSchema.safeParse({
+      positionName: 'BASE_01',
+      centerX: 10,
+      centerY: 20,
+      width: 30,
+      height: 40,
+      source: 'OTHER',
+    }).success).toBe(false);
+  });
+
+  it('AI canvas placement operation schemas reject invalid lists and unknown fields', () => {
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{ positionName: 'BASE_01', centerX: 1, centerY: 2, width: 3, height: 4 }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: sameCanvasReviewedPlanEvidence,
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 10,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: sameCanvasReviewedPlanEvidence,
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          selectedPlanObjectBboxPx: undefined,
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          selectedPlanObjectIds: ['P_REF', 'P_REF_BASE'],
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          selectedPlanObjectIds: ['P_REF'],
+          sourcePlanObject: validReviewedPlanObject('P_REF', 'appliance_opening'),
+          anchorPlanObjectIds: undefined,
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          sourcePlanObject: undefined,
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          selectedPlanObjectRole: 'physical_plan_footprint',
+          sourcePlanObject: validReviewedPlanObject('P_REF', 'appliance_opening'),
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'UPPER_SIDE',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          selectedPlanObjectRole: 'dashed_overhead_only',
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          basis: 'user_confirmed',
+          evidence: 'User provided the plan/elevation drawings and asked the agent to verify the placement.',
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [{
+        positionName: 'BASE_01',
+        centerX: 1,
+        centerY: 2,
+        width: 3,
+        height: 4,
+        viewAssociationEvidence: {
+          ...planViewAssociationEvidence,
+          basis: 'user_confirmed',
+          selectedPlanObjectRole: 'dashed_overhead_only',
+          userExplicitConfirmation: true,
+          userConfirmationText: 'User confirmed this exact dashed overhead object should be treated as a physical plan placement for BASE_01.',
+          evidence: 'User confirmed this exact dashed overhead object should be treated as a physical plan placement; association.selectedPlanObjects contains P_REF and agent visual image analysis verified the bbox.',
+        },
+      }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      placements: [],
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsReplaceInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsUpsertInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      placements: [{ positionName: 'BASE_01', centerX: 1, centerY: 2, width: 3, height: 4 }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementsUpsertInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      placements: [],
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsPatchInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      placements: [{ positionName: 'BASE_01', centerX: 12 }],
+    }).success).toBe(true);
+    expect(AiCanvasCabinetPlacementPatchSchema.safeParse({
+      positionName: 'BASE_01',
+      unsupportedField: true,
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsPatchInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      placements: [],
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsDeleteInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      positionNames: [],
+    }).success).toBe(false);
+    expect(AiCanvasCabinetPlacementsDeleteInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      positionNames: [''],
+    }).success).toBe(false);
+  });
+
+  it('projection calibration schema accepts valid plan calibration', () => {
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(validPlanProjectionCalibration()).success).toBe(true);
+    expect(AiCanvasMetaSchema.safeParse({
+      projectionCalibration: validPlanProjectionCalibration(),
+      legacyDisplayMetadata: { stillFlexible: true },
+    }).success).toBe(true);
+  });
+
+  it('projection calibration schema accepts valid east elevation calibration', () => {
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(validElevationProjectionCalibration('east', 90)).success).toBe(true);
+    expect(AiCanvasMetaSchema.safeParse({
+      projectionCalibration: validElevationProjectionCalibration('east', 90),
+      elevationVisibility: { legacy: true },
+    }).success).toBe(true);
+  });
+
+  it('projection calibration schema rejects invalid schemaVersion', () => {
+    const calibration = validPlanProjectionCalibration();
+    calibration.schemaVersion = 'wrong-version';
+
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(calibration).success).toBe(false);
+    expect(AiCanvasMetaSchema.safeParse({ projectionCalibration: calibration }).success).toBe(false);
+  });
+
+  it('projection calibration schema rejects invalid direction values', () => {
+    const calibration = validPlanProjectionCalibration();
+    calibration.roomAxis.xPositiveDirection = 'diagonal';
+
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(calibration).success).toBe(false);
+  });
+
+  it('projection calibration schema rejects invalid rotations', () => {
+    const calibration = validElevationProjectionCalibration('east', 90);
+    calibration.visibilityRule.rotations = [45];
+
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(calibration).success).toBe(false);
+  });
+
+  it('projection calibration schema rejects non-array include and exclude position names', () => {
+    const includeCalibration = validElevationProjectionCalibration('east', 90);
+    includeCalibration.visibilityRule.includePositionNames = 'BASE_01';
+    const excludeCalibration = validElevationProjectionCalibration('east', 90);
+    excludeCalibration.visibilityRule.excludePositionNames = 'BASE_01';
+
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(includeCalibration).success).toBe(false);
+    expect(AiCanvasProjectionCalibrationSchema.safeParse(excludeCalibration).success).toBe(false);
+  });
+
+  it('canvas metadata accepts free-form association notes outside projectionCalibration', () => {
+    expect(AiCanvasMetadataInputSchema.safeParse({
+      sessionId,
+      canvasType: 'west',
+      activeCanvases: ['plan', 'north', 'west'],
+      canvasMeta: {
+        schemaVersion: 'ai-canvas-metadata/v1',
+        sourceFile: 'west.png',
+        imageSizePx: { width: 1665, height: 944 },
+        viewAssociation: {
+          elevationMarker: '2',
+          planMarkerSide: 'left',
+          orientationEvidence: 'Manual visual association from plan marker and appliance anchors.',
+        },
+        z0ReferencePx: 828,
+        floorLineEvidence: 'Base cabinet fronts end above the plinth/toe-kick band.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('metadata tool description tells agents not to put free-form notes in projectionCalibration', () => {
+    const metadataTool = aiDrawingTools.find((tool) => tool.name === 'upsert_ai_canvas_metadata');
+
+    expect(metadataTool?.description).toContain('projectionCalibration is not free-form notes');
+    expect(metadataTool?.description).toContain('For direct IMAGE_PIXELS per-canvas placements, omit projectionCalibration');
+    expect(metadataTool?.description).toContain('sourceFile, imageSizePx, plan/elevation marker association, orientation evidence, z0 notes');
+    expect(metadataTool?.description).toContain('outside projectionCalibration');
+  });
+
+  it('coordinate tool descriptions mention canonical room/global coordinates', () => {
+    const coordinateToolNames = [
+      'replace_ai_cabinet_coordinates',
+      'patch_ai_cabinet_coordinates',
+      'delete_ai_cabinet_coordinates',
+    ];
+
+    for (const name of coordinateToolNames) {
+      const tool = aiDrawingTools.find((candidate) => candidate.name === name);
+      expect(tool?.description).toContain('canonical room/global inches');
+      expect(tool?.description).toContain('Plan projects canonical x/y');
+    }
+  });
+
+  it('metadata tool description mentions canvasMeta projection calibration', () => {
+    const metadataTool = aiDrawingTools.find((tool) => tool.name === 'upsert_ai_canvas_metadata');
+
+    expect(metadataTool?.description).toContain('canvasMeta.projectionCalibration');
+    expect(metadataTool?.description).toContain('ai-canvas-calibration/v1');
+  });
+
+  it('placement tool descriptions include per-canvas canvas-local guidance', () => {
+    const placementToolNames = [
+      'get_ai_canvas_cabinet_placements',
+      'get_ai_canvas_cabinet_placements_by_canvas',
+      'replace_ai_canvas_cabinet_placements',
+      'upsert_ai_canvas_cabinet_placements',
+      'patch_ai_canvas_cabinet_placements',
+      'delete_ai_canvas_cabinet_placements',
+    ];
+
+    for (const name of placementToolNames) {
+      const tool = aiDrawingTools.find((candidate) => candidate.name === name);
+      expect(tool?.description).toContain('per-canvas');
+      expect(tool?.description).toContain('canvas-local visual rectangles');
+      expect(tool?.description).toContain('active linked AI cart');
+      expect(tool?.description).toContain('link to an active AI cart item by aiCartItemId or exact positionName');
+      expect(tool?.description).toContain('read back get_ai_drawing_state or get_ai_cart_by_session');
+      expect(tool?.description).toContain('returned backend aiCartItemId values before writing placements');
+      expect(tool?.description).toContain('If cart sync failed or activeCart/items are missing, stop');
+      expect(tool?.description).toContain('original image pixels');
+      expect(tool?.description).toContain('width/height in these placement tools are visual rectangle pixel dimensions');
+      expect(tool?.description).toContain('Plan rectangles are footprints');
+      expect(tool?.description).toContain('elevation rectangles are primary front faces');
+      expect(tool?.description).toContain('Reuse the same aiCartItemId/positionName');
+      expect(tool?.description).toContain('A plan placement does not make the cabinet appear on an elevation');
+      expect(tool?.description).toContain('every visible cabinet face on north/south/east/west must also get its own placement');
+      expect(tool?.description).toContain('Do not derive plan placements from elevation boxes');
+      expect(tool?.description).toContain('Do not rely on filenames, compass words, object order, or catalog labels alone');
+      expect(tool?.description).toContain('render and inspect the stored session');
+      expect(tool?.description).toContain('use native vision and user confirmation when ambiguous');
+      expect(tool?.description).toContain('do not mutate Redux cart');
+      expect(tool?.description).toContain('stored carts');
+      expect(tool?.description).toContain('production coordinates');
+    }
+  });
+
+  it('cabinet operation tool descriptions include one physical cabinet and shared identity guidance', () => {
+    const operationToolNames = [
+      'duplicate_ai_cabinet',
+      'configure_ai_cabinet',
+      'delete_ai_cabinet',
+    ];
+
+    for (const name of operationToolNames) {
+      const tool = aiDrawingTools.find((candidate) => candidate.name === name);
+      expect(tool?.description).toContain('one physical cabinet');
+      expect(tool?.description).toContain('shared aiCartItemId');
+      expect(tool?.description).toContain('same cabinet must use the same shared aiCartItemId and positionName');
+      expect(tool?.description).toContain('Do not create separate physical AI cart items');
+      expect(tool?.description).toContain('per-canvas placement tools for placement geometry');
+      expect(tool?.description).toContain('do not mutate the Redux cart');
+      expect(tool?.description).toContain('stored carts');
+      expect(tool?.description).toContain('production coordinate tables');
+      expect(tool?.description).toContain('CAD/XML');
+    }
+
+    expect(aiDrawingTools.find((tool) => tool.name === 'duplicate_ai_cabinet')?.description)
+      .toContain('creates a new physical cabinet');
+    expect(aiDrawingTools.find((tool) => tool.name === 'configure_ai_cabinet')?.description)
+      .toContain('linked AI-only placement dimensions');
+    expect(aiDrawingTools.find((tool) => tool.name === 'delete_ai_cabinet')?.description)
+      .toContain('linked AI-only placements');
+  });
+
+  it('AI drawing coordinate schemas preserve x y z and rotation', () => {
+    const replacement = AiCabinetCoordinatesReplaceInputSchema.parse({
+      sessionId,
+      coordinates: [{ positionName: 'BASE_01', x: 1, y: 2, z: 3, rotation: 270 }],
+    });
+    const patch = AiCabinetCoordinatesPatchInputListSchema.parse({
+      sessionId,
+      coordinates: [{ positionName: 'BASE_01', x: 4, y: 5, z: 6, rotation: 180 }],
+    });
+
+    expect(replacement.coordinates[0]).toEqual(expect.objectContaining({ x: 1, y: 2, z: 3, rotation: 270 }));
+    expect(patch.coordinates[0]).toEqual(expect.objectContaining({ x: 4, y: 5, z: 6, rotation: 180 }));
+  });
+});
+
+describe('AI cart tool handlers', () => {
+  const cartId = '11111111-1111-4111-8111-111111111111';
+  const itemId = '22222222-2222-4222-8222-222222222222';
+  const sessionId = '33333333-3333-4333-8333-333333333333';
+
+  beforeEach(() => vi.clearAllMocks());
+
+  it('create_ai_cart posts to the AI cart endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.post).mockResolvedValue({ data: { id: cartId } });
+
+    const result = await createAiCart({
+      aiDrawingSessionId: sessionId,
+      sourceType: 'REDUX_SNAPSHOT',
+      sourceOrderId: 'ORDER-1',
+      sourceSavedCartId: 123,
+      sourceSnapshotPayload: '{"cart":true}',
+    });
+
+    expect(apiClientModule.aiDrawingClient.post).toHaveBeenCalledWith('/carts', {
+      aiDrawingSessionId: sessionId,
+      sourceType: 'REDUX_SNAPSHOT',
+      sourceOrderId: 'ORDER-1',
+      sourceSavedCartId: 123,
+      sourceSnapshotPayload: '{"cart":true}',
+    });
+    expect(result).toContain(cartId);
+  });
+
+  it('get_ai_cart calls the AI cart read endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({ data: { id: cartId } });
+
+    const result = await getAiCart({ cartId });
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(`/carts/${cartId}`);
+    expect(result).toContain(cartId);
+  });
+
+  it('get_ai_cart_by_session calls the AI cart session endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.get).mockResolvedValue({ data: { aiDrawingSessionId: sessionId } });
+
+    const result = await getAiCartBySession({ sessionId });
+
+    expect(apiClientModule.aiDrawingClient.get).toHaveBeenCalledWith(`/carts/session/${sessionId}`);
+    expect(result).toContain(sessionId);
+  });
+
+  it('sync_ai_cart_snapshot accepts user explicitly requested saved preset evidence phrasing', () => {
+    const parsed = AiCartSnapshotInputSchema.safeParse({
+      cartId,
+      items: [
+        {
+          positionName: 'B1',
+          serialNumber: 'BC_4DR_1007',
+          quantity: 1,
+          width: 27.5,
+          height: 34.5,
+          depth: 24,
+        },
+      ],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        checkedSerialNumbers: ['BC_4DR_1007'],
+        evidence:
+          'Called get_article_context and get_article_options for each selected serial number. Checked get_my_saved_settings and get_saved_settings_presets; user explicitly requested the saved preset Transitional - Paint-Prefin, savedSettingsId 26, using exact option strings from the preset.',
+      },
+    });
+
+    expect(parsed.success).toBe(true);
+  });
+
+  it('sync_ai_cart_snapshot puts snapshot payload to the AI cart endpoint', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { id: cartId, cartRevision: 1 } });
+
+    const result = await syncAiCartSnapshot({
+      cartId,
+      sourceSnapshotPayload: '{"source":"redux"}',
+      items: [
+        {
+          frontendItemId: 'frontend-1',
+          serialNumber: 'B30',
+          positionName: 'BASE_01',
+          quantity: 2,
+          width: 30,
+          itemPayload: { original: true },
+        },
+      ],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user selected saved setting Modern Euro.',
+        checkedSerialNumbers: ['B30'],
+      },
+    });
+
+    expect(apiClientModule.aiDrawingClient.put).toHaveBeenCalledWith(`/carts/${cartId}/snapshot`, {
+      sourceSnapshotPayload: '{"source":"redux"}',
+      items: [
+        expect.objectContaining({
+          frontendItemId: 'frontend-1',
+          serialNumber: 'B30',
+          positionName: 'BASE_01',
+          quantity: 2,
+          width: 30,
+          originalItemPayload: JSON.stringify({
+            frontendItemId: 'frontend-1',
+            serialNumber: 'B30',
+            positionName: 'BASE_01',
+            quantity: 2,
+            width: 30,
+            original: true,
+          }),
+        }),
+      ],
+    });
+    expect(result).toContain('cartRevision');
+  });
+
+  it('sync_ai_cart_snapshot synthesizes original payload when itemPayload is omitted', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { id: cartId, cartRevision: 1 } });
+
+    await syncAiCartSnapshot({
+      cartId,
+      items: [
+        {
+          serialNumber: 'B30',
+          positionName: 'BASE_01',
+          displayName: '30 inch base',
+          quantity: 1,
+          width: 30,
+          height: 34.5,
+          depth: 24,
+        },
+      ],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user selected saved setting Modern Euro.',
+        checkedSerialNumbers: ['B30'],
+      },
+    });
+
+    const request = vi.mocked(apiClientModule.aiDrawingClient.put).mock.calls[0][1] as any;
+    expect(request.items[0]).toEqual(expect.objectContaining({
+      serialNumber: 'B30',
+      positionName: 'BASE_01',
+      quantity: 1,
+      width: 30,
+      height: 34.5,
+      depth: 24,
+    }));
+    expect(JSON.parse(request.items[0].originalItemPayload)).toEqual({
+      serialNumber: 'B30',
+      positionName: 'BASE_01',
+      quantity: 1,
+      width: 30,
+      height: 34.5,
+      depth: 24,
+      displayName: '30 inch base',
+    });
+  });
+
+  it('sync_ai_cart_snapshot preserves drawing classification evidence in backend item payloads', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { id: cartId, cartRevision: 1 } });
+
+    await syncAiCartSnapshot({
+      cartId,
+      sourceSnapshotPayload: '{"source":"drawing takeoff"}',
+      items: [
+        {
+          serialNumber: 'B30',
+          positionName: 'BASE_01',
+          quantity: 1,
+          width: 30,
+          itemPayload: { original: true },
+          drawingClassificationEvidence: validDrawingClassificationEvidence(),
+        },
+      ],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user selected saved setting Modern Euro.',
+        checkedSerialNumbers: ['B30'],
+      },
+    });
+
+    const request = vi.mocked(apiClientModule.aiDrawingClient.put).mock.calls[0][1] as any;
+    const originalItemPayload = JSON.parse(request.items[0].originalItemPayload);
+    expect(originalItemPayload.original).toBe(true);
+    expect(originalItemPayload.__aiDrawingClassificationEvidence).toEqual(
+      expect.objectContaining({ primaryViewPlaneRole: 'primary_elevation_face' })
+    );
+  });
+
+  it('sync_ai_cart_snapshot combines synthesized original payload with drawing classification evidence', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.put).mockResolvedValue({ data: { id: cartId, cartRevision: 1 } });
+
+    await syncAiCartSnapshot({
+      cartId,
+      items: [
+        {
+          serialNumber: 'B30',
+          positionName: 'BASE_01',
+          quantity: 1,
+          width: 30,
+          drawingClassificationEvidence: validDrawingClassificationEvidence(),
+        },
+      ],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user selected saved setting Modern Euro.',
+        checkedSerialNumbers: ['B30'],
+      },
+    });
+
+    const request = vi.mocked(apiClientModule.aiDrawingClient.put).mock.calls[0][1] as any;
+    const originalItemPayload = JSON.parse(request.items[0].originalItemPayload);
+    expect(originalItemPayload.serialNumber).toBe('B30');
+    expect(originalItemPayload.positionName).toBe('BASE_01');
+    expect(originalItemPayload.__aiDrawingClassificationEvidence).toEqual(
+      expect.objectContaining({ primaryViewPlaneRole: 'primary_elevation_face' })
+    );
+  });
+
+  it('create_ai_cart schema accepts drawing source metadata without semantic evidence gating', async () => {
+    const acceptedWithoutWorkflow = AiCartCreateInputSchema.safeParse({
+      aiDrawingSessionId: sessionId,
+      sourceType: 'REDUX_SNAPSHOT',
+      sourceSnapshotPayload: JSON.stringify({
+        source: 'overlay drawing takeoff',
+        checkedSerialNumbers: ['UC_1D_L_1227'],
+        items: [{ positionName: 'U1', serialNumber: 'UC_1D_L_1227' }],
+      }),
+    });
+    const acceptedWithWorkflow = AiCartCreateInputSchema.safeParse({
+      aiDrawingSessionId: sessionId,
+      sourceType: 'REDUX_SNAPSHOT',
+      sourceSnapshotPayload: JSON.stringify({
+        source: 'overlay drawing takeoff',
+        checkedSerialNumbers: ['UC_1D_L_1227'],
+      }),
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for UC_1D_L_1227; checked get_my_saved_settings and get_saved_settings_presets; user selected saved setting Modern Euro.',
+        checkedSerialNumbers: ['UC_1D_L_1227'],
+      },
+    });
+
+    expect(acceptedWithoutWorkflow.success).toBe(true);
+    expect(acceptedWithWorkflow.success).toBe(true);
+  });
+
+  it('patch_ai_cart_item patches one canonical AI cart item', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.patch).mockResolvedValue({ data: { id: cartId, cartRevision: 2 } });
+
+    const result = await patchAiCartItem({
+      cartId,
+      itemId,
+      patch: {
+        positionName: 'BASE_02',
+        displayName: 'Updated Base',
+        itemPayload: { patched: true },
+      },
+    });
+
+    expect(apiClientModule.aiDrawingClient.patch).toHaveBeenCalledWith(`/carts/${cartId}/items/${itemId}`, {
+      positionName: 'BASE_02',
+      displayName: 'Updated Base',
+      originalItemPayload: '{"patched":true}',
+    });
+    expect(result).toContain('cartRevision');
+  });
+
+  it('delete_ai_cart_item deletes one canonical AI cart item', async () => {
+    vi.mocked(apiClientModule.aiDrawingClient.delete).mockResolvedValue({ data: { id: cartId, items: [] } });
+
+    const result = await deleteAiCartItem({ cartId, itemId });
+
+    expect(apiClientModule.aiDrawingClient.delete).toHaveBeenCalledWith(`/carts/${cartId}/items/${itemId}`);
+    expect(result).toContain(cartId);
+  });
+
+  it('tool input schemas reject invalid UUIDs', () => {
+    const toolByName = Object.fromEntries(aiDrawingTools.map((tool) => [tool.name, tool]));
+
+    expect(toolByName.get_ai_cart.inputSchema.safeParse({ cartId: 'bad' }).success).toBe(false);
+    expect(toolByName.get_ai_cart_by_session.inputSchema.safeParse({ sessionId: 'bad' }).success).toBe(false);
+    expect(toolByName.upload_ai_canvas_image.inputSchema.safeParse({ sessionId: 'bad', canvasType: 'plan', imageType: 'background', imagePath: 'D:\\tmp\\file.png' }).success).toBe(false);
+    expect(toolByName.delete_ai_canvas_image.inputSchema.safeParse({ sessionId: 'bad', canvasType: 'plan', imageType: 'background' }).success).toBe(false);
+    expect(toolByName.patch_ai_cart_item.inputSchema.safeParse({ cartId, itemId: 'bad', patch: {} }).success).toBe(false);
+    expect(toolByName.delete_ai_cart_item.inputSchema.safeParse({ cartId: 'bad', itemId }).success).toBe(false);
+    expect(toolByName.get_ai_cart_item_order_ready_payload.inputSchema.safeParse({ sessionId: 'bad', itemId }).success).toBe(false);
+    expect(toolByName.set_ai_cart_item_order_ready_payload.inputSchema.safeParse({
+      sessionId,
+      itemId: 'bad',
+      orderReadyStatus: 'BLOCKED',
+      orderReadyMessages: [{ message: 'Invalid item id' }],
+    }).success).toBe(false);
+    expect(toolByName.clear_ai_cart_item_order_ready_payload.inputSchema.safeParse({ sessionId: 'bad', itemId }).success).toBe(false);
+  });
+
+  it('AI canvas image delete schema accepts only supported canvas and image types', () => {
+    expect(AiCanvasImageDeleteInputSchema.safeParse({
+      sessionId,
+      canvasType: 'south',
+      imageType: 'background',
+    }).success).toBe(true);
+
+    expect(AiCanvasImageDeleteInputSchema.safeParse({
+      sessionId,
+      canvasType: 'ceiling',
+      imageType: 'background',
+    }).success).toBe(false);
+
+    expect(AiCanvasImageDeleteInputSchema.safeParse({
+      sessionId,
+      canvasType: 'plan',
+      imageType: 'thumbnail',
+    }).success).toBe(false);
+  });
+
+  it('AI canvas image upload schema accepts supported canvas and image inputs', () => {
+    expect(AiCanvasImageUploadInputSchema.safeParse({
+      sessionId,
+      canvasType: 'east',
+      imageType: 'background',
+      imagePath: 'D:\\testing321\\unit_i_east_elevation_ai_overlay_preview.png',
+    }).success).toBe(true);
+
+    expect(AiCanvasImageUploadInputSchema.safeParse({
+      sessionId,
+      canvasType: 'ceiling',
+      imageType: 'background',
+      imagePath: 'D:\\testing321\\unit_i_east_elevation_ai_overlay_preview.png',
+    }).success).toBe(false);
+  });
+
+  it('sync snapshot tool schema accepts quantity greater than one item payload', () => {
+    const syncTool = aiDrawingTools.find((tool) => tool.name === 'sync_ai_cart_snapshot');
+    const parsed = syncTool?.inputSchema.safeParse({
+      cartId,
+      items: [{ positionName: 'BASE_01', quantity: 4, itemPayload: { raw: true } }],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user selected saved setting Modern Euro.',
+        checkedSerialNumbers: ['B30'],
+      },
+    });
+
+    expect(parsed?.success).toBe(true);
+    expect(syncTool?.description).toContain('one deduplicated physical cabinet manifest');
+    expect(syncTool?.description).toContain('plan is only a top-view placement');
+    expect(syncTool?.description).toContain('not one manifest per canvas');
+    expect(syncTool?.description).toContain('orderConfigurationWorkflow is optional audit metadata');
+    expect(syncTool?.description).toContain('visual semantics are not certified by this schema');
+  });
+
+  it('sync snapshot schema accepts persistence-only item manifests without evidence workflow', () => {
+    const syncTool = aiDrawingTools.find((tool) => tool.name === 'sync_ai_cart_snapshot');
+
+    expect(syncTool?.inputSchema.safeParse({
+      cartId,
+      items: [{ positionName: 'BASE_01', quantity: 1 }],
+    }).success).toBe(true);
+
+    expect(syncTool?.inputSchema.safeParse({
+      cartId,
+      items: [{ positionName: 'BASE_01', quantity: 1 }],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence: 'Agent decided configuration can wait.',
+      },
+    }).success).toBe(true);
+
+    expect(syncTool?.inputSchema.safeParse({
+      cartId,
+      items: [{ positionName: 'BASE_01', quantity: 1 }],
+      orderConfigurationWorkflow: {
+        mode: 'USER_APPROVED_UNCONFIGURED_DRAFT',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user approved creating an unconfigured planner draft.',
+      },
+    }).success).toBe(false);
+  });
+
+  it('AI cart creation and sync descriptions require order-ready follow-up for agent-created items', () => {
+    const createTool = aiDrawingTools.find((tool) => tool.name === 'create_ai_cart');
+    const syncTool = aiDrawingTools.find((tool) => tool.name === 'sync_ai_cart_snapshot');
+    const patchTool = aiDrawingTools.find((tool) => tool.name === 'patch_ai_cart_item');
+
+    for (const tool of [createTool, syncTool]) {
+      expect(tool?.description).toContain('When the agent creates or syncs AI cart items');
+      expect(tool?.description).toContain('get_article_context');
+      expect(tool?.description).toContain('get_article_options');
+      expect(tool?.description).toContain('get_my_saved_settings');
+      expect(tool?.description).toContain('get_saved_settings_presets');
+      expect(tool?.description).toContain('ask the user for every missing order-critical choice');
+      expect(tool?.description).toContain('set_ai_cart_item_order_ready_payload');
+      expect(tool?.description).toContain('ArticleItemSchema-compatible payload');
+      expect(tool?.description).toContain('Creating positionName, serialNumber, width, height, and depth is not enough');
+    }
+
+    expect(patchTool?.description).toContain('refresh that item with set_ai_cart_item_order_ready_payload');
+    expect(patchTool?.description).toContain('NEEDS_AGENT_CONFIGURATION/BLOCKED');
+  });
+
+  it('AI cart tool descriptions avoid legacy endpoint and tool identifiers in source schema output', () => {
+    const renderedToolMetadata = JSON.stringify(aiDrawingTools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: zodToJsonSchema(tool.inputSchema),
+    })));
+    const forbiddenTerms = [
+      '/api/mcp/v1/' + 'canvas',
+      'get' + '_drawing_tool_state',
+      'update' + '_cabinet_coordinates',
+      'patch' + '_cabinet_coordinates',
+      'upload' + '_canvas_background_image',
+      '/topic/' + 'drawing-tool',
+      'Drawing' + 'ToolTest',
+      'saved' + '_carts',
+    ];
+
+    for (const term of forbiddenTerms) {
+      expect(renderedToolMetadata).not.toContain(term);
+    }
+  });
+
+  it('order-ready tool descriptions include no-guessing order guidance', () => {
+    const toolNames = [
+      'get_ai_cart_item_order_ready_payload',
+      'set_ai_cart_item_order_ready_payload',
+      'clear_ai_cart_item_order_ready_payload',
+    ];
+
+    for (const name of toolNames) {
+      const tool = aiDrawingTools.find((candidate) => candidate.name === name);
+      expect(tool?.description).toContain('serialNumber, positionName, width, height, and depth alone are not order-ready');
+      expect(tool?.description).toContain('get_article_context');
+      expect(tool?.description).toContain('get_article_options');
+      expect(tool?.description).toContain('get_my_saved_settings');
+      expect(tool?.description).toContain('get_saved_settings_presets');
+      expect(tool?.description).toContain('saved setting tools');
+      expect(tool?.description).toContain('ask the user for every required missing order-critical choice');
+      expect(tool?.description).toContain('use exact option strings');
+      expect(tool?.description).toContain('ArticleItemSchema/order-contract validation');
+      expect(tool?.description).toContain('Drawing evidence JSON is optional trace metadata and is not visual certification');
+      expect(tool?.description).toContain('automatically upsert into the browser Redux checkout cart');
+      expect(tool?.description).toContain('Do not tell users to press Seed AI Cart or Apply to cart as the normal workflow');
+    }
+  });
+
+  it('Phase 14 import and order-ready descriptions explain automatic mirroring without normal seed/apply workflow', () => {
+    const importTool = aiDrawingTools.find((candidate) => candidate.name === 'import_redux_cart_items_to_ai_cart');
+    const setReadyTool = aiDrawingTools.find((candidate) => candidate.name === 'set_ai_cart_item_order_ready_payload');
+
+    expect(importTool?.description).toContain('Import rich browser Redux checkout cart items');
+    expect(importTool?.description).toContain('full original Redux cart item payload');
+    expect(importTool?.description).toContain('idempotency');
+    expect(importTool?.description).toContain('positionName alone');
+    expect(importTool?.description).toContain('only for real existing browser checkout cart items');
+    expect(importTool?.description).toContain('do not use it to seed AI cart items from drawing takeoff');
+    expect(importTool?.description).toContain('MCP imports must be READY and order-ready');
+    expect(importTool?.description).toContain('automatically upsert into the browser Redux checkout cart');
+    expect(importTool?.description).toContain('Do not tell users to press Seed AI Cart or Apply to cart as the normal workflow');
+    expect(setReadyTool?.description).toContain('READY AI cart items');
+    expect(setReadyTool?.description).toContain('Non-ready statuses');
+  });
+});
+
+describe('AI cart schemas', () => {
+  const cartId = '11111111-1111-4111-8111-111111111111';
+  const itemId = '22222222-2222-4222-8222-222222222222';
+
+  it('parses valid AI cart item snapshot input', () => {
+    const result = AiCartItemInputSchema.parse({
+      frontendItemId: 'frontend-1',
+      serialNumber: 'B30',
+      positionName: 'BASE_01',
+      groupId: 'base-run',
+      width: 30,
+      height: 34.5,
+      depth: 24,
+      displayName: 'Base 30',
+      itemPayload: { raw: true },
+    });
+
+    expect(result.quantity).toBe(1);
+    expect(result.positionName).toBe('BASE_01');
+    expect(result.itemPayload).toEqual({ raw: true });
+  });
+
+  it('accepts quantity greater than one for snapshot input before backend expansion', () => {
+    const result = AiCartItemInputSchema.parse({
+      positionName: 'BASE_01',
+      quantity: 3,
+    });
+
+    expect(result.quantity).toBe(3);
+  });
+
+  it('rejects missing or empty positionName for item input', () => {
+    expect(AiCartItemInputSchema.safeParse({ serialNumber: 'B30' }).success).toBe(false);
+    expect(AiCartItemInputSchema.safeParse({ positionName: '' }).success).toBe(false);
+  });
+
+  it('allows pantry classification evidence by default so visual review can catch mistakes', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'PTRY',
+      serialNumber: 'PC_1D_L_1293',
+      displayName: 'Tall Pantry',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        semanticTypeEvidence: 'North elevation same-canvas visible geometry shows REF refrigerator/freezer appliance handles, not a cabinet surround.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows sink-base classification evidence by default so visual review can catch mistakes', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'SINK',
+      serialNumber: 'SB24',
+      displayName: 'Sink Base',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['plan', 'north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'plan_elevation_association',
+        elevationCanvasType: 'north',
+        detailNumber: '7',
+        planMarkerSide: 'right',
+        selectedPlanObjectIds: ['P_BASE_RIGHT'],
+        selectedPlanObjectBboxPx: { x: 720, y: 390, width: 100, height: 110 },
+        sourcePlanObject: validReviewedPlanObject('P_BASE_RIGHT', 'base_cabinet'),
+        sourceElevationObject: validReviewedElevationObject('N_BASE_RIGHT', 'base_cabinet', ['front_panel_boundaries']),
+        semanticTypeEvidence: 'Plan has a sink symbol elsewhere in the drawing, but this north elevation item has no same-canvas sink basin/faucet evidence.',
+        rejectedConflictingEvidence: ['fixture_symbol:SINK from plan detail marker side 6'],
+      },
+    }).success).toBe(true);
+  });
+
+  it('accepts elevation-derived classification only with primary front-face evidence', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'BASE_01',
+      serialNumber: 'B30',
+      displayName: '30 Base Cabinet',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Agent visual review confirms front-facing base cabinet doors/drawers in the north elevation.',
+        frontFaceFeatures: ['door_drawer_fronts', 'front_handles_or_pulls'],
+        sourceElevationObject: validReviewedElevationObject('N_BASE_FRONT', 'base_cabinet', ['door_drawer_fronts', 'front_handles_or_pulls']),
+        semanticTypeEvidence: 'Same-canvas north elevation visible geometry shows a front-facing base cabinet with doors/drawers.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows self-attested reviewed source objects without review tokens by default', () => {
+    const sourceElevationObject = { ...validReviewedElevationObject('N_BASE_FRONT', 'base_cabinet', ['door_drawer_fronts']) };
+    delete sourceElevationObject.reviewToken;
+
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'BASE_01',
+      serialNumber: 'B30',
+      displayName: '30 Base Cabinet',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Agent visual review confirms front-facing base cabinet doors/drawers in the north elevation.',
+        frontFaceFeatures: ['door_drawer_fronts'],
+        sourceElevationObject,
+        semanticTypeEvidence: 'Same-canvas north elevation visible geometry shows a front-facing base cabinet with doors.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows elevation-derived return side evidence by default so visual review can catch mistakes', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'UPPER_SIDE',
+      serialNumber: 'U12',
+      displayName: 'Upper side view',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'return_side_face',
+        frontFaceEvidence: 'Agent visual review says this is a perpendicular side view / return side face at the edge of the north elevation.',
+        frontFaceFeatures: ['side_panel_or_return_visible'],
+        sourceElevationObject: {
+          ...validReviewedElevationObject('N_UPPER_SIDE', 'wall_cabinet', ['side_panel_or_return_visible']),
+          viewPlaneRole: 'return_side_face',
+          evidence: 'Reviewed object is a return side face at the edge of the elevation.',
+        },
+        semanticTypeEvidence: 'Visible side-view geometry only; this does not show the primary front face in the north elevation.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows elevation-derived classification without a reviewed source object by default', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'N_SNK',
+      serialNumber: 'BC_S_1D_R_1770',
+      displayName: 'Sink base right',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Agent claims this is a sink base with a sink basin on the primary elevation face.',
+        frontFaceFeatures: ['sink_basin_or_faucet_on_primary_face', 'front_panel_boundaries'],
+        semanticTypeEvidence: 'Sink base cabinet; sink basin is allegedly visible on this elevation.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows invented sink feature evidence by default so visual review can catch mistakes', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'N_SNK',
+      serialNumber: 'BC_S_1D_R_1770',
+      displayName: 'Sink base right',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Agent claims this is a sink base with a sink basin on the primary elevation face.',
+        frontFaceFeatures: ['sink_basin_or_faucet_on_primary_face', 'front_panel_boundaries'],
+        sourceElevationObject: validReviewedElevationObject('N_RIGHT_BASE', 'base_cabinet', ['front_panel_boundaries']),
+        semanticTypeEvidence: 'Sink base cabinet; sink basin is allegedly visible on this elevation.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('accepts sink classification only when the reviewed source object is a sink base with sink evidence', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'N_SNK',
+      serialNumber: 'BC_S_1D_R_1770',
+      displayName: 'Sink base right',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Reviewed north elevation object shows a sink basin or faucet on the same primary front face.',
+        frontFaceFeatures: ['sink_basin_or_faucet_on_primary_face', 'front_panel_boundaries'],
+        sourceElevationObject: validReviewedElevationObject('N_SINK_FRONT', 'sink_base', ['sink_basin_or_faucet_on_primary_face', 'front_panel_boundaries']),
+        semanticTypeEvidence: 'Sink base cabinet; same reviewed source object carries sink basin/faucet evidence.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows reviewed non-sink source objects with sink feature evidence by default', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'RB30',
+      serialNumber: 'BC_1D_L_1002',
+      displayName: 'Right Base',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Reviewed north elevation object is a right base panel below the counter line.',
+        frontFaceFeatures: ['sink_basin_or_faucet_on_primary_face', 'front_panel_boundaries'],
+        sourceElevationObject: validReviewedElevationObject('N_RB30', 'base_cabinet', ['sink_basin_or_faucet_on_primary_face', 'front_panel_boundaries']),
+        semanticTypeEvidence: 'Base cabinet with claimed sink feature on a non-sink reviewed object.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows elevation sink classification without same-canvas primary-face sink evidence by default', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'I_S30',
+      serialNumber: 'BC_S_2D_1761',
+      displayName: 'Sink Base',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Agent visual review shows a base-sized rectangle at the right edge but no sink basin or faucet on the primary face.',
+        frontFaceFeatures: ['front_panel_boundaries'],
+        sourceElevationObject: validReviewedElevationObject('N_RIGHT_BASE', 'base_cabinet', ['front_panel_boundaries']),
+        semanticTypeEvidence: 'North elevation context has no same-canvas sink basin/faucet on the primary front face.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows elevation upper classification from side/end-panel features by default', () => {
+    expect(AiCartItemInputSchema.safeParse({
+      positionName: 'I_U20',
+      serialNumber: 'UC_1D_R_1228',
+      displayName: 'Upper side panel',
+      drawingClassificationEvidence: {
+        sourceCanvases: ['north'],
+        primaryCanvasType: 'north',
+        classificationBasis: 'same_canvas_visible_geometry',
+        primaryViewPlaneRole: 'primary_elevation_face',
+        frontFaceEvidence: 'Agent visual review shows a narrow side/end panel at the right edge of the elevation.',
+        frontFaceFeatures: ['side_panel_or_return_visible'],
+        sourceElevationObject: {
+          ...validReviewedElevationObject('N_UPPER_SIDE', 'wall_cabinet', ['side_panel_or_return_visible']),
+          evidence: 'Reviewed object is a side/end panel at the right edge of the elevation.',
+        },
+        semanticTypeEvidence: 'Visible side/end panel context only, not an upper cabinet primary face.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('allows drawing-derived item snapshots without drawing classification evidence by default', () => {
+    expect(AiCartSnapshotInputSchema.safeParse({
+      cartId,
+      sourceSnapshotPayload: '{"source":"drawing takeoff","drawings":["unit_i_plan.png","unit_i_north_elevation.png"]}',
+      items: [{ positionName: 'BASE_01', serialNumber: 'B30' }],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user confirmed exact order options.',
+        checkedSerialNumbers: ['B30'],
+      },
+    }).success).toBe(true);
+  });
+
+  it('rejects invalid cart and item UUID params', () => {
+    expect(AiCartIdParamSchema.safeParse({ cartId: 'not-a-uuid' }).success).toBe(false);
+    expect(AiCartItemIdParamSchema.safeParse({ cartId, itemId: 'not-a-uuid' }).success).toBe(false);
+  });
+
+  it('accepts supported patch fields and rejects unknown fields', () => {
+    const validPatch = AiCartItemPatchSchema.safeParse({
+      positionName: 'BASE_02',
+      width: 33,
+      displayName: 'Updated Base',
+      itemPayload: { updated: true },
+    });
+    const invalidPatch = AiCartItemPatchSchema.safeParse({
+      positionName: 'BASE_02',
+      unsupportedField: true,
+    });
+
+    expect(validPatch.success).toBe(true);
+    expect(invalidPatch.success).toBe(false);
+  });
+
+  it('parses snapshot schema with UUID cart id and item array', () => {
+    const result = AiCartSnapshotInputSchema.parse({
+      cartId,
+      sourceSnapshotPayload: '{"source":"mcp"}',
+      items: [
+        {
+          positionName: 'BASE_01',
+          quantity: 2,
+          itemPayload: { source: 'cart' },
+        },
+      ],
+      orderConfigurationWorkflow: {
+        mode: 'USER_CONFIRMED_ORDER_READY',
+        evidence:
+          'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; user confirmed exact order options.',
+        checkedSerialNumbers: ['B30'],
+      },
+    });
+
+    expect(result.cartId).toBe(cartId);
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0].quantity).toBe(2);
+  });
+
+  it('schema descriptions avoid legacy MCP canvas and frontend drawing tool identifiers', () => {
+    const renderedSchemas = JSON.stringify([
+      zodToJsonSchema(AiCartIdParamSchema),
+      zodToJsonSchema(AiCartItemIdParamSchema),
+      zodToJsonSchema(AiCartItemInputSchema),
+      zodToJsonSchema(AiCartItemPatchSchema),
+      zodToJsonSchema(AiCartSnapshotInputSchema),
+      zodToJsonSchema(DuplicateAiCabinetInputSchema),
+      zodToJsonSchema(ConfigureAiCabinetInputSchema),
+      zodToJsonSchema(DeleteAiCabinetInputSchema),
+      zodToJsonSchema(AiOrderReadyPayloadReadInputSchema),
+      zodToJsonSchema(AiOrderReadyPayloadSetInputSchema),
+      zodToJsonSchema(AiOrderReadyPayloadClearInputSchema),
+      zodToJsonSchema(AiReduxCartImportInputSchema),
+    ]);
+
+    const forbiddenTerms = [
+      '/api/mcp/v1/' + 'canvas',
+      'get' + '_drawing_tool_state',
+      'update' + '_cabinet_coordinates',
+      'patch' + '_cabinet_coordinates',
+      'upload' + '_canvas_background_image',
+      '/topic/' + 'drawing-tool',
+      'Drawing' + 'ToolTest',
+      'saved' + '_carts',
+    ];
+
+    for (const term of forbiddenTerms) {
+      expect(renderedSchemas).not.toContain(term);
+    }
+  });
+
+  it('order-ready schema rejects thin READY payloads and requires base body-height evidence for base READY payloads', () => {
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: { arbitrary: true },
+    }).success).toBe(false);
+
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: thinArticleItemPayload(),
+    }).success).toBe(false);
+
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validArticleItemPayload(),
+    }).success).toBe(false);
+
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validUpperArticleItemPayload(),
+    }).success).toBe(true);
+
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validArticleItemPayload(),
+      drawingClassificationEvidence: validDrawingClassificationEvidence(),
+    }).success).toBe(true);
+  });
+
+  it('order-ready schema allows refrigerator/pantry evidence conflicts by default for visual review', () => {
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: {
+        ...validArticleItemPayload(),
+        serialNumber: 'PC_1D_L_1293',
+        positionName: 'N_PTRY',
+      },
+      drawingClassificationEvidence: {
+        ...validUpperDrawingClassificationEvidence(),
+        semanticTypeEvidence: 'Agent vision review shows REF refrigerator/freezer handles and appliance footprint.',
+        sourceElevationObject: validReviewedElevationObject('N_REF_FRONT', 'appliance_opening', ['appliance_front_or_handles']),
+      },
+    }).success).toBe(true);
+  });
+
+  it('order-ready schema allows elevation return-side evidence by default for visual review', () => {
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'READY',
+      orderReadyPayload: validUpperArticleItemPayload(),
+      drawingClassificationEvidence: {
+        ...validUpperDrawingClassificationEvidence(),
+        primaryViewPlaneRole: 'return_side_face',
+        frontFaceEvidence: 'Agent visual review says this is a side view / return side face.',
+        frontFaceFeatures: ['side_panel_or_return_visible'],
+        semanticTypeEvidence: 'Perpendicular return-side geometry visible at the edge of the north elevation.',
+      },
+    }).success).toBe(true);
+  });
+
+  it('order-ready schema accepts non-ready validation messages without prose evidence gates', () => {
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION',
+      orderReadyMessages: [
+        {
+          severity: 'error',
+          field: 'caseMaterial',
+          message:
+            'Called get_article_context and get_article_options for B30; checked get_my_saved_settings and get_saved_settings_presets; ask the user for caseMaterial.',
+        },
+      ],
+    }).success).toBe(true);
+
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'BLOCKED',
+      orderReadyMessages: [
+        {
+          severity: 'blocker',
+          field: 'serialNumber',
+          message: 'No reliable catalog match was available; ask the user to choose a valid serialNumber.',
+        },
+      ],
+    }).success).toBe(true);
+  });
+
+  it('order-ready schema accepts simple needs-configuration statuses as persistence state', () => {
+    expect(AiOrderReadyPayloadSetInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      itemId,
+      orderReadyStatus: 'NEEDS_AGENT_CONFIGURATION',
+      orderReadyMessages: [
+        { severity: 'error', field: 'caseMaterial', message: 'Ask the user for case material.' },
+      ],
+    }).success).toBe(true);
+  });
+
+  it('Redux import schema validates session UUID and rejects empty import arrays', () => {
+    expect(AiReduxCartImportInputSchema.safeParse({
+      sessionId: 'not-a-uuid',
+      items: [validReduxCartImportInput('33333333-3333-4333-8333-333333333333').items[0]],
+    }).success).toBe(false);
+
+    expect(AiReduxCartImportInputSchema.safeParse({
+      sessionId: '33333333-3333-4333-8333-333333333333',
+      items: [],
+    }).success).toBe(false);
+  });
+
+  it('Redux import schema rejects items without full original payload data', () => {
+    const input = validReduxCartImportInput('33333333-3333-4333-8333-333333333333');
+    input.items[0].originalItemPayload = { arbitrary: true };
+
+    expect(AiReduxCartImportInputSchema.safeParse(input).success).toBe(false);
+  });
+
+  it('Redux import schema rejects thin and non-ready MCP imports', () => {
+    const input = validReduxCartImportInput('33333333-3333-4333-8333-333333333333');
+    input.items[0].originalItemPayload = thinArticleItemPayload();
+    delete input.items[0].orderReadyPayload;
+    delete input.items[0].orderReadyStatus;
+
+    expect(AiReduxCartImportInputSchema.safeParse(input).success).toBe(false);
+
+    input.items[0].orderReadyStatus = 'READY';
+    expect(AiReduxCartImportInputSchema.safeParse(input).success).toBe(false);
+
+    input.items[0].orderReadyStatus = 'NOT_PREPARED';
+    input.items[0].orderReadyMessages = [
+      { severity: 'error', message: 'Ask the user for case material before mirroring.' },
+    ];
+    expect(AiReduxCartImportInputSchema.safeParse(input).success).toBe(false);
+  });
+});
+
+function validReduxCartImportInput(sessionId: string): any {
+  const payload = validArticleItemPayload();
+  return {
+    sessionId,
+    items: [
+      {
+        frontendItemId: 'frontend-1',
+        originalFrontendItemId: 'frontend-1',
+        positionName: payload.positionName,
+        originalPositionName: payload.positionName,
+        serialNumber: payload.serialNumber,
+        displayName: 'Base 30',
+        quantity: 1,
+        originalQuantity: 1,
+        width: payload.width,
+        height: payload.height,
+        depth: payload.depth,
+        originalItemPayload: payload,
+        orderReadyStatus: 'READY',
+        orderReadyPayload: payload,
+        orderReadySource: 'MCP',
+      },
+    ],
+  };
+}
+
+function thinArticleItemPayload(): Record<string, unknown> {
+  return {
+    serialNumber: 'B30',
+    positionName: 'BASE_01',
+    quantity: 1,
+    width: 30,
+    height: 34.5,
+    depth: 24,
+  };
+}
+
+function validArticleItemPayload(): Record<string, unknown> {
+  return {
+    serialNumber: 'B30',
+    positionName: 'BASE_01',
+    quantity: 1,
+    width: 30,
+    height: 34.5,
+    depth: 24,
+    caseMaterial: 'White Melamine',
+    frontMaterial: 'White Oak',
+    caseEdge: 'White 1mm',
+    frontEdge: 'White Oak 1mm',
+    backPanelMaterial: 'White Melamine',
+    backPanel: 'Inset',
+    jointMethod: 'Biscuit',
+  };
+}
+
+function validUpperArticleItemPayload(): Record<string, unknown> {
+  return {
+    serialNumber: 'UC_1D_R_1228',
+    positionName: 'UPPER_01',
+    quantity: 1,
+    width: 30,
+    height: 42,
+    depth: 12,
+    caseMaterial: 'White Melamine',
+    frontMaterial: 'White Oak',
+    caseEdge: 'White 1mm',
+    frontEdge: 'White Oak 1mm',
+    backPanelMaterial: 'White Melamine',
+    backPanel: 'Inset',
+    jointMethod: 'Biscuit',
+  };
+}
+
+function validDrawingClassificationEvidence(): Record<string, unknown> {
+  return {
+    sourceCanvases: ['north'],
+    primaryCanvasType: 'north',
+    classificationBasis: 'same_canvas_visible_geometry',
+    primaryViewPlaneRole: 'primary_elevation_face',
+    frontFaceEvidence: 'Agent vision review confirms this is a primary front-facing base cabinet in the north elevation.',
+    frontFaceFeatures: ['door_drawer_fronts', 'front_handles_or_pulls'],
+    sourceElevationObject: validReviewedElevationObject('N_BASE_FRONT', 'base_cabinet', ['door_drawer_fronts', 'front_handles_or_pulls']),
+    semanticTypeEvidence: 'Same-canvas north elevation visible geometry shows front-facing doors and drawers for this cabinet.',
+    baseCabinetBodyHeightEvidence: validBaseCabinetBodyHeightEvidence(),
+    rejectedConflictingEvidence: [],
+  };
+}
+
+function validUpperDrawingClassificationEvidence(): Record<string, unknown> {
+  return {
+    sourceCanvases: ['north'],
+    primaryCanvasType: 'north',
+    classificationBasis: 'same_canvas_visible_geometry',
+    primaryViewPlaneRole: 'primary_elevation_face',
+    frontFaceEvidence: 'Agent vision review confirms this is a primary front-facing upper cabinet in the north elevation.',
+    frontFaceFeatures: ['single_door_front', 'front_handles_or_pulls'],
+    sourceElevationObject: validReviewedElevationObject('N_UPPER_FRONT', 'wall_cabinet', ['single_door_front', 'front_handles_or_pulls']),
+    semanticTypeEvidence: 'Same-canvas north elevation visible geometry shows a front-facing upper wall cabinet.',
+    rejectedConflictingEvidence: [],
+  };
+}
+
+function validBaseCabinetBodyHeightEvidence(): Record<string, unknown> {
+  return {
+    cabinetBodyHeightInches: 34.5,
+    measurementBasis: 'called_out_scale_and_known_dimension',
+    scaleEvidence: 'Agent used the called-out elevation scale and known 30 inch cabinet width to measure the cabinet body height.',
+    topBoundaryEvidence: 'Top boundary is the base cabinet case/front below the countertop line; countertop thickness is excluded.',
+    bottomBoundaryEvidence: 'Bottom boundary is the cabinet body above the separate toekick/plinth band and at or above Z0.',
+    excludedElements: ['toekick_plinth', 'countertop', 'floor'],
+    plinthDecision: 'separate_plinth_item_created',
+    countertopDecision: 'excluded_visible_countertop',
+    z0Evidence: 'The measured cabinet body stops above the finished-floor Z0 line and does not include floor context.',
+    cabinetBodyBboxPx: { x: 100, y: 120, width: 200, height: 270 },
+    plinthBboxPx: { x: 100, y: 390, width: 200, height: 35 },
+    countertopBboxPx: { x: 100, y: 90, width: 200, height: 30 },
+    evidence: 'Base cabinet READY height is the body height only and excludes the visible countertop and separated plinth.',
+  };
+}
+
+function validReviewedElevationObject(
+  objectId: string,
+  objectType: string,
+  frontFaceFeatures: string[]
+): Record<string, unknown> {
+  return reviewedObjectWithToken({
+    objectId,
+    canvasType: 'north',
+    objectType,
+    reviewStatus: 'reviewed_cabinet',
+    viewPlaneRole: 'primary_elevation_face',
+    frontFaceFeatures,
+    bbox: { x: 100, y: 100, width: 50, height: 60 },
+    evidence: 'Reviewed north elevation object from the drawing-analysis artifact with primary face evidence.',
+  });
+}
+
+function validReviewedPlanObject(
+  objectId: string,
+  objectType: string
+): Record<string, unknown> {
+  return reviewedObjectWithToken({
+    objectId,
+    canvasType: 'plan',
+    objectType,
+    reviewStatus: 'reviewed_cabinet',
+    viewPlaneRole: 'plan_footprint',
+    frontFaceFeatures: [],
+    bbox: { x: 720, y: 390, width: 100, height: 110 },
+    evidence: 'Reviewed plan object from association.selectedPlanObjects and visual plan analysis.',
+  });
+}
+
+function reviewedObjectWithToken(subject: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...subject,
+    reviewToken: `test-review-token-${String(subject.objectId ?? 'object')}`,
+  };
+}
+
+function validCoordinateEvidence(): Record<string, unknown> {
+  return {
+    basis: 'validated_plan_placement',
+    sourceCanvasType: 'plan',
+    planPlacementPositionName: 'BASE_01',
+    planPlacementEvidence: {
+      basis: 'plan_elevation_marker_review',
+      elevationCanvasType: 'north',
+      detailNumber: '7',
+      planMarkerSide: 'right',
+      selectedPlanObjectIds: ['P_REF'],
+      selectedPlanObjectBboxPx: { x: -0.5, y: 0, width: 3, height: 4 },
+      selectedPlanObjectRole: 'appliance_footprint',
+      sourcePlanObject: validReviewedPlanObject('P_REF', 'appliance_opening'),
+      evidence: 'association.selectedPlanObjects contains P_REF. Agent visual image analysis confirms this exact selected plan object was used to derive canonical x/y.',
+    },
+    evidence: 'Canonical coordinate derived from the validated plan placement, not from an elevation-local rectangle.',
+  };
+}
+
+function validPlanProjectionCalibration(): any {
+  return {
+    schemaVersion: 'ai-canvas-calibration/v1',
+    canvasType: 'plan',
+    imageSizePx: { width: 1000, height: 800 },
+    unit: 'inches',
+    pixelsPerInch: 4,
+    roomOriginPx: { x: 100, y: 700 },
+    roomAxis: {
+      xPositiveDirection: 'right',
+      yPositiveDirection: 'up',
+    },
+    roomSizeInches: { width: 180, depth: 120 },
+  };
+}
+
+function validElevationProjectionCalibration(canvasType: 'north' | 'south' | 'east' | 'west', rotation: 0 | 90 | 180 | 270): any {
+  return {
+    schemaVersion: 'ai-canvas-calibration/v1',
+    canvasType,
+    imageSizePx: { width: 675, height: 706 },
+    unit: 'inches',
+    horizontalPixelsPerInch: 4,
+    verticalPixelsPerInch: 4,
+    floorZ0Px: 554,
+    wallType: canvasType,
+    wallPlaneCoordinateInches: 180,
+    horizontalOriginPx: { x: 60, y: 554 },
+    horizontalOriginCoordinateInches: 0,
+    horizontalAxisPositiveDirection: 'right',
+    verticalAxisPositiveDirection: 'up',
+    visibilityRule: {
+      mode: 'rotation',
+      rotations: [rotation],
+      includePositionNames: [],
+      excludePositionNames: [],
+    },
+  };
+}
+
+function expectDescriptionRequiresVisualReview(toolName: string): void {
+  const tool = aiDrawingTools.find((candidate) => candidate.name === toolName);
+
+  expect(tool?.description).toContain('render_ai_drawing_session_review');
+  expect(tool?.description).toContain('inspect every returned full-canvas PNG with native vision');
+  expect(tool?.description).toContain('correct wrong placements with existing AI-only placement tools');
+  expect(tool?.description).toContain('rerender');
+  expect(tool?.description).toContain('PASS/FAIL/UNCERTAIN');
+  expect(tool?.description).toContain('JSON validity is not visual correctness');
+}
+
+function findArrayTupleItems(value: unknown, path = '$'): string[] {
+  if (!value || typeof value !== 'object') {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findArrayTupleItems(item, `${path}[${index}]`));
+  }
+
+  const record = value as Record<string, unknown>;
+  const hits = Array.isArray(record.items) ? [`${path}.items`] : [];
+  return [
+    ...hits,
+    ...Object.entries(record).flatMap(([key, nestedValue]) => findArrayTupleItems(nestedValue, `${path}.${key}`)),
+  ];
+}
+
+function findBooleanExclusiveBounds(value: unknown, path = '$'): string[] {
+  if (!value || typeof value !== 'object') {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findBooleanExclusiveBounds(item, `${path}[${index}]`));
+  }
+
+  const record = value as Record<string, unknown>;
+  const hits = ['exclusiveMinimum', 'exclusiveMaximum']
+    .filter((key) => typeof record[key] === 'boolean')
+    .map((key) => `${path}.${key}`);
+  return [
+    ...hits,
+    ...Object.entries(record).flatMap(([key, nestedValue]) => findBooleanExclusiveBounds(nestedValue, `${path}.${key}`)),
+  ];
+}