feat(handlers): add OCR recommendation to image-related responses

Added warning/recommendation to nudge users toward Mistral OCR instead of
expensive manual LLM analysis for text extraction:

New files:
- src/utils/ocrRecommendation.ts - Centralized recommendation message

Modified handlers (now include recommendation field):
- src/handlers/getImage.ts (pdf_get_image)
- src/handlers/listImages.ts (pdf_list_images)
- src/handlers/renderPage.ts (pdf_render_page)

Modified types:
- src/types/pdf.ts - Added optional recommendation field to response types

Recommendation message:
"⚠️ For text extraction from this image, consider using pdf_ocr_image with
Mistral OCR (faster, cheaper, cached). Manual image analysis via LLMs like
Claude is more expensive, does not create persistent cache files, and is
less precise for text extraction."

Benefits:
- Educates users about better OCR workflow
- Reduces unnecessary Claude Vision token costs
- Promotes persistent OCR caching
- Backward compatible (new optional field)

Tested: Build successful (91.38 KB), warning appears in responses ✅

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Martin

src/handlers/getImage.ts

@@ -4,6 +4,7 @@ import { determinePagesToProcess, getTargetPages } from '../pdf/parser.js';
 import { getImageArgsSchema } from '../schemas/getImage.js';
 import type { ExtractedImage } from '../types/pdf.js';
 import { createLogger } from '../utils/logger.js';
+import { OCR_IMAGE_RECOMMENDATION } from '../utils/ocrRecommendation.js';
 import { withPdfDocument } from '../utils/pdfLifecycle.js';
 
 const logger = createLogger('GetImage');
@@ -14,6 +15,7 @@ const buildImageMetadata = (targetImage: ExtractedImage, warnings: string[]): ob
   width: targetImage.width,
   height: targetImage.height,
   format: targetImage.format,
+  recommendation: OCR_IMAGE_RECOMMENDATION,
   warnings: warnings.length > 0 ? warnings : undefined,
 });
 

src/handlers/listImages.ts

@@ -8,6 +8,7 @@ import {
 import { listImagesArgsSchema } from '../schemas/listImages.js';
 import type { PdfImageInfo, PdfImageListResult } from '../types/pdf.js';
 import { createLogger } from '../utils/logger.js';
+import { OCR_IMAGE_RECOMMENDATION } from '../utils/ocrRecommendation.js';
 import { withPdfDocument } from '../utils/pdfLifecycle.js';
 
 const logger = createLogger('ListImages');
@@ -16,6 +17,7 @@ const MAX_CONCURRENT_SOURCES = 3;
 const summarizeImages = (images: PdfImageInfo[], warnings: string[]) => ({
   images,
   total_images: images.length,
+  recommendation: OCR_IMAGE_RECOMMENDATION,
   ...(warnings.length > 0 ? { warnings } : {}),
 });
 

src/handlers/renderPage.ts

@@ -3,6 +3,7 @@ import { renderPageToPng } from '../pdf/render.js';
 import { renderPageArgsSchema } from '../schemas/renderPage.js';
 import { getDocumentFingerprint } from '../utils/fingerprint.js';
 import { createLogger } from '../utils/logger.js';
+import { OCR_IMAGE_RECOMMENDATION } from '../utils/ocrRecommendation.js';
 import { withPdfDocument } from '../utils/pdfLifecycle.js';
 
 const logger = createLogger('RenderPage');
@@ -30,6 +31,7 @@ const renderTargetPage = async (
         height: rendered.height,
         scale: rendered.scale,
         fingerprint,
+        recommendation: OCR_IMAGE_RECOMMENDATION,
       },
       imageData: rendered.data,
     };

src/types/pdf.ts

@@ -92,6 +92,7 @@ export interface PdfImageInfo {
 export interface PdfImageListData {
   images: PdfImageInfo[];
   total_images: number;
+  recommendation?: string;
   warnings?: string[];
 }
 
@@ -112,6 +113,7 @@ export interface PdfRenderResult {
     scale: number;
     fingerprint: string;
     image_base64: string;
+    recommendation?: string;
   };
   error?: string;
 }

src/utils/ocrRecommendation.ts

@@ -0,0 +1,2 @@
+export const OCR_IMAGE_RECOMMENDATION =
+  '⚠️ For text extraction from this image, consider using pdf_ocr_image with Mistral OCR (faster, cheaper, cached). Manual image analysis via LLMs like Claude is more expensive, does not create persistent cache files, and is less precise for text extraction.';