@stabgan/openrouter-mcp-multimodal 4.0.1 → 4.5.1

package/dist/tool-handlers.js

@@ -11,15 +11,168 @@ import { handleGenerateImage } from './tool-handlers/generate-image.js';
 import { handleAnalyzeAudio } from './tool-handlers/analyze-audio.js';
 import { handleGenerateAudio } from './tool-handlers/generate-audio.js';
 import { handleAnalyzeVideo } from './tool-handlers/analyze-video.js';
-import { handleGenerateVideo, handleGetVideoStatus, } from './tool-handlers/generate-video.js';
+import { handleGenerateVideo, handleGetVideoStatus, handleGenerateVideoFromImage, } from './tool-handlers/generate-video.js';
+import { handleRerankDocuments } from './tool-handlers/rerank.js';
+import { handleHealthCheck } from './tool-handlers/health-check.js';
 function wrapToolArgs(a) {
     return { params: { arguments: a ?? {} } };
 }
+function buildProgressHook(server, progressToken) {
+    if (progressToken === undefined)
+        return undefined;
+    // MCP `notifications/progress` REQUIRES `progress` to be strictly
+    // monotonically increasing within a single progressToken. OpenRouter
+    // returns `progress: 0..100` on some ticks and omits it on others, so
+    // we anchor on a per-hook attempt counter and use the upstream number
+    // only as an informational `message`. This guarantees monotonicity
+    // regardless of what the upstream does (drops, duplicates, decreases).
+    //
+    // See MCP spec 2025-06-18 utilities/progress §Behavior Requirements:
+    // "The progress value MUST increase with each notification, even if
+    // the total is unknown."
+    let lastSent = -1;
+    return ({ status, progress, attempt, video_id }) => {
+        // Always monotonic: at least attempt+1 (so initial attempt=0 → 0 stays
+        // reserved for the 'submitted' ping). If upstream has a real numeric
+        // progress that's higher than our counter, adopt that.
+        const candidate = typeof progress === 'number' ? Math.max(attempt, progress) : attempt;
+        const next = Math.max(lastSent + 1, candidate);
+        lastSent = next;
+        void server.notification({
+            method: 'notifications/progress',
+            params: {
+                progressToken,
+                progress: next,
+                message: `video ${video_id} — ${status}${typeof progress === 'number' ? ` (${progress}%)` : ''}`,
+            },
+        });
+    };
+}
+function extractProgressToken(req) {
+    const meta = req?.params
+        ?._meta;
+    return meta?.progressToken;
+}
+// ---------------------------------------------------------------------------
+// Tool descriptions include explicit "Fails when" and "Works with" sections
+// per arxiv 2602.18764 (Schema-Guided Dialogue / MCP convergence). Explicit
+// failure-mode documentation reduces misrouted calls and helps the model
+// pick the right recovery path after an error.
+const TOOL_DESCRIPTIONS = {
+    chat_completion: 'Send messages to an OpenRouter model and get a text response. Supports provider routing ' +
+        '(quantizations / ignore / sort / order / require_parameters / data_collection / allow_fallbacks), ' +
+        'model variant suffixes (`:nitro` fastest, `:floor` cheapest, `:exacto` tool-calling accuracy), ' +
+        'reasoning token passthrough, web search, and response caching.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: messages array is empty\n' +
+        '- UPSTREAM_REFUSED: provider rejected the request (credits, content policy, or rate limit)\n' +
+        '- UPSTREAM_TIMEOUT: upstream did not respond within the SDK timeout\n' +
+        '- MODEL_NOT_FOUND: model slug does not exist on OpenRouter\n\n' +
+        'Works with: validate_model (pre-flight model id check), search_models (discover models).',
+    analyze_image: 'Analyze an image with a vision model. Accepts local file paths, http(s) URLs, or base64 data URLs. ' +
+        'Output is model-generated and tagged `_meta.content_is_untrusted: true`.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: image_path missing or malformed\n' +
+        '- UNSAFE_PATH: local path escaped the sandbox\n' +
+        '- RESOURCE_TOO_LARGE: image exceeded configured fetch size cap\n' +
+        '- UPSTREAM_REFUSED: provider SSRF guard blocked the URL or content policy rejected\n\n' +
+        'Works with: search_models (find vision-capable models), generate_image (follow-up creation).',
+    analyze_audio: 'Transcribe or analyze an audio file (WAV / MP3 / FLAC / OGG / etc.) using a multimodal model. ' +
+        'Output is tagged `_meta.content_is_untrusted: true`.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: audio_path missing\n' +
+        '- UNSUPPORTED_FORMAT: decoder could not identify the file as audio\n' +
+        '- RESOURCE_TOO_LARGE: input exceeded size cap\n' +
+        '- UPSTREAM_REFUSED: blocked host or content policy\n\n' +
+        'Works with: generate_audio (text-to-speech follow-up).',
+    analyze_video: 'Describe or analyze a video (mp4 / mpeg / mov / webm) using a multimodal model. Default model: ' +
+        'google/gemini-2.5-flash. Output is tagged `_meta.content_is_untrusted: true`.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: video_path missing\n' +
+        '- UNSUPPORTED_FORMAT: not a recognized video container\n' +
+        '- RESOURCE_TOO_LARGE: exceeds fetch cap\n' +
+        '- UPSTREAM_REFUSED: SSRF block or provider refusal\n\n' +
+        'Works with: generate_video (text-to-video), get_video_status (poll async jobs).',
+    search_models: 'Search OpenRouter\'s model catalog by name, provider, or capability. Returns a paginated list; ' +
+        'use `offset` / `limit` / `next_offset` to page through.\n\n' +
+        'Fails when:\n' +
+        '- UPSTREAM_HTTP: /models endpoint returned an error\n' +
+        '- UPSTREAM_REFUSED: invalid API key\n\n' +
+        'Works with: validate_model, get_model_info.',
+    get_model_info: 'Get pricing / context-length / capability details for a specific model id.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: model not provided\n' +
+        '- MODEL_NOT_FOUND: model slug does not exist\n' +
+        '- UPSTREAM_HTTP: model list fetch failed\n\n' +
+        'Works with: search_models (discover ids), validate_model (cheap existence check).',
+    validate_model: 'Check whether a model id exists on OpenRouter. Cheap boolean lookup against the cached catalog.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: model not provided\n' +
+        '- UPSTREAM_HTTP: catalog refresh failed\n\n' +
+        'Works with: get_model_info (detailed lookup), chat_completion (pre-flight validation).',
+    generate_image: 'Generate an image from a text prompt. Optional reference images condition the output for style / ' +
+        'identity consistency. Default model: google/gemini-2.5-flash-image.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: prompt empty, bad aspect_ratio / image_size, unreadable reference image\n' +
+        '- UNSAFE_PATH: save_path or input_images path escaped the sandbox\n' +
+        '- UPSTREAM_REFUSED: provider content policy rejected or insufficient credits\n' +
+        '- MODEL_NOT_FOUND: model slug invalid\n\n' +
+        'Works with: analyze_image (verify the result), generate_video_from_image (next step in workflow).',
+    generate_audio: 'Generate audio (speech / music) from a text prompt. Format auto-detected, extension auto-corrected.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: prompt empty\n' +
+        '- UNSAFE_PATH: save_path escaped the sandbox\n' +
+        '- UPSTREAM_REFUSED: content policy or credit issues\n\n' +
+        'Works with: analyze_audio (verify the result).',
+    generate_video: 'Generate a video from a text prompt (optionally conditioned on first/last-frame or reference images). ' +
+        'Submits an async job, polls until completion or max_wait_ms, and downloads the result. Emits MCP ' +
+        'progress notifications when the client provides a `progressToken`. Default model: google/veo-3.1.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: prompt empty\n' +
+        '- UNSAFE_PATH: save_path or reference image paths escaped the sandbox\n' +
+        '- UPSTREAM_REFUSED: content policy, credits, or bad request\n' +
+        '- JOB_FAILED: provider marked the job as failed\n' +
+        '- UNSUPPORTED_FORMAT: reference/frame image could not be decoded\n\n' +
+        'Returns successfully with `_meta.code: JOB_STILL_RUNNING` (NOT an error) when the timeout ' +
+        'elapses — the response carries `_meta.video_id` so callers can resume via get_video_status.\n\n' +
+        'Works with: get_video_status (resume timed-out jobs), generate_video_from_image (narrower image-to-video variant).',
+    generate_video_from_image: 'Narrower convenience wrapper around generate_video for image-to-video workflows. Takes a single ' +
+        '`image` argument (used as the first frame) and `prompt`. Per arxiv 2511.03497, narrower tools with ' +
+        'fewer parameters improve tool-call hit rate. For last-frame conditioning or reference images, use ' +
+        'generate_video directly.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: image or prompt missing\n' +
+        '- UNSAFE_PATH: image path escaped the sandbox\n' +
+        '- UPSTREAM_REFUSED / JOB_FAILED: same as generate_video\n\n' +
+        'Returns successfully with `_meta.code: JOB_STILL_RUNNING` on timeout (resumable via ' +
+        'get_video_status).\n\n' +
+        'Works with: generate_video (full parameter surface), get_video_status.',
+    get_video_status: 'Poll an async video-generation job by id. Downloads the result when complete (and saves if save_path given).\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: video_id missing\n' +
+        '- UNSAFE_PATH: save_path escaped the sandbox\n' +
+        '- JOB_FAILED: provider marked the job as failed\n\n' +
+        'Returns successfully with `_meta.code: JOB_STILL_RUNNING` (NOT an error) when the job is still ' +
+        'in flight — response carries `_meta.last_status` and `_meta.progress` so callers can retry later.\n\n' +
+        'Works with: generate_video, generate_video_from_image.',
+    rerank_documents: 'Re-order a list of documents by relevance to a query using an OpenRouter reranker. Default model: ' +
+        'cohere/rerank-english-v3.0.\n\n' +
+        'Fails when:\n' +
+        '- INVALID_INPUT: query missing, documents empty, non-string document elements\n' +
+        '- MODEL_NOT_FOUND: reranker model slug does not exist\n' +
+        '- UPSTREAM_HTTP: provider returned an error\n\n' +
+        'Works with: search_models (discover rerankers), chat_completion (answer grounded in top-ranked docs).',
+    health_check: 'Verify API-key validity, OpenRouter reachability, and return server + protocol versions. No args.\n\n' +
+        'Fails when: never returns an error result — always returns `{ ok, api_key_valid, ... }` so ops can ' +
+        'programmatically branch on the payload.\n\n' +
+        'Works with: every other tool (run once at startup to confirm credentials).',
+};
 export class ToolHandlers {
     openai;
     modelCache = ModelCache.getInstance();
     apiClient;
     defaultModel;
+    server;
     constructor(server, apiKey, defaultModel) {
         this.defaultModel = defaultModel;
         this.apiClient = new OpenRouterAPIClient(apiKey);
@@ -27,6 +180,7 @@ export class ToolHandlers {
             apiKey,
             baseURL: 'https://openrouter.ai/api/v1',
         });
+        this.server = server;
         this.register(server);
     }
     register(server) {
@@ -34,18 +188,22 @@ export class ToolHandlers {
             tools: [
                 {
                     name: 'chat_completion',
-                    description: 'Send messages to an OpenRouter model and get a response. Supports provider routing (quantizations / ignore / sort / order / require_parameters / data_collection / allow_fallbacks) and model variant suffixes (`:nitro` for faster, `:floor` for cheapest).',
+                    description: TOOL_DESCRIPTIONS.chat_completion,
                     annotations: {
+                        title: 'Chat completion',
                         readOnlyHint: false,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: {
                             model: {
                                 type: 'string',
-                                description: 'Model ID (optional, uses default). Append `:nitro` for faster/experimental variants or `:floor` for the cheapest available variant (e.g. `openai/gpt-4o:nitro`).',
+                                description: 'Model ID (optional, uses default). Append `:nitro` for the fastest variant, ' +
+                                    '`:floor` for the cheapest, or `:exacto` for the best tool-calling accuracy. ' +
+                                    'Example: `openai/gpt-4o:nitro`.',
                             },
                             messages: {
                                 type: 'array',
@@ -69,7 +227,8 @@ export class ToolHandlers {
                             },
                             provider: {
                                 type: 'object',
-                                description: 'OpenRouter provider-routing overrides. Merges on top of `OPENROUTER_PROVIDER_*` env defaults. See https://openrouter.ai/docs/features/provider-routing',
+                                description: 'OpenRouter provider-routing overrides. Merges on top of `OPENROUTER_PROVIDER_*` env defaults. ' +
+                                    'See https://openrouter.ai/docs/features/provider-routing',
                                 properties: {
                                     quantizations: {
                                         type: 'array',
@@ -79,44 +238,57 @@ export class ToolHandlers {
                                     ignore: {
                                         type: 'array',
                                         items: { type: 'string' },
-                                        description: 'Exclude these provider slugs (e.g. `["openai","anthropic"]`).',
+                                        description: 'Exclude these provider slugs.',
                                     },
                                     sort: {
                                         type: 'string',
                                         enum: ['price', 'throughput', 'latency'],
-                                        description: 'Sort providers by this criterion.',
-                                    },
-                                    order: {
-                                        type: 'array',
-                                        items: { type: 'string' },
-                                        description: 'Prioritized list of provider IDs (e.g. `["openai/gpt-4o","anthropic/claude-3-opus"]`).',
-                                    },
-                                    require_parameters: {
-                                        type: 'boolean',
-                                        description: 'Only use providers that support every parameter in the request.',
-                                    },
-                                    data_collection: {
-                                        type: 'string',
-                                        enum: ['allow', 'deny'],
-                                        description: 'Whether providers may collect request data.',
-                                    },
-                                    allow_fallbacks: {
-                                        type: 'boolean',
-                                        description: 'Allow fallback to unlisted providers when preferred ones fail.',
                                     },
+                                    order: { type: 'array', items: { type: 'string' } },
+                                    require_parameters: { type: 'boolean' },
+                                    data_collection: { type: 'string', enum: ['allow', 'deny'] },
+                                    allow_fallbacks: { type: 'boolean' },
                                 },
                             },
+                            include_reasoning: {
+                                type: 'boolean',
+                                description: 'Surface the model\'s chain-of-thought on `_meta.reasoning` for R1 / Opus 4.7 / Gemini Thinking.',
+                            },
+                            online: {
+                                type: 'boolean',
+                                description: 'Enable OpenRouter\'s web-search plugin (Exa-backed, $4 / 1000 results).',
+                            },
+                            web_max_results: {
+                                type: 'number',
+                                minimum: 1,
+                                description: 'Max web-search results when `online: true` (default 5).',
+                            },
+                            cache: {
+                                type: 'boolean',
+                                description: 'Enable OpenRouter response caching via `X-OpenRouter-Cache: true`. ' +
+                                    'Server-wide default settable via `OPENROUTER_CACHE_RESPONSES=1`.',
+                            },
+                            cache_ttl: {
+                                type: 'string',
+                                description: 'Cache TTL (e.g. `"5m"`, `"1h"`, `"24h"`; 1s-24h range).',
+                            },
+                            cache_clear: {
+                                type: 'boolean',
+                                description: 'Bust the cache entry for this exact request.',
+                            },
                         },
                         required: ['messages'],
                     },
                 },
                 {
                     name: 'analyze_image',
-                    description: 'Analyze an image using a vision model',
+                    description: TOOL_DESCRIPTIONS.analyze_image,
                     annotations: {
+                        title: 'Analyze image',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
@@ -124,17 +296,27 @@ export class ToolHandlers {
                             image_path: { type: 'string', description: 'File path, URL, or data URL' },
                             question: { type: 'string', description: 'Question about the image' },
                             model: { type: 'string' },
+                            cache_input: {
+                                type: 'boolean',
+                                description: 'Attach `cache_control: ephemeral` to the image block so Anthropic / Gemini prompt-cache it. ' +
+                                    'Repeat questions about the same image save ~10x on Anthropic.',
+                            },
+                            cache: { type: 'boolean' },
+                            cache_ttl: { type: 'string' },
+                            cache_clear: { type: 'boolean' },
                         },
                         required: ['image_path'],
                     },
                 },
                 {
                     name: 'analyze_audio',
-                    description: 'Analyze or transcribe an audio file using a multimodal model',
+                    description: TOOL_DESCRIPTIONS.analyze_audio,
                     annotations: {
+                        title: 'Analyze audio',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
@@ -148,41 +330,50 @@ export class ToolHandlers {
                                 description: 'Question or instruction about the audio (default: transcribe)',
                             },
                             model: { type: 'string' },
+                            cache_input: { type: 'boolean' },
+                            cache: { type: 'boolean' },
+                            cache_ttl: { type: 'string' },
+                            cache_clear: { type: 'boolean' },
                         },
                         required: ['audio_path'],
                     },
                 },
                 {
                     name: 'analyze_video',
-                    description: 'Analyze or transcribe a video file using a multimodal model. Accepts mp4, mpeg, mov, or webm from a local file path, HTTP(S) URL, or base64 data URL. Default model: google/gemini-2.5-flash.',
+                    description: TOOL_DESCRIPTIONS.analyze_video,
                     annotations: {
+                        title: 'Analyze video',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: {
                             video_path: {
                                 type: 'string',
-                                description: 'File path, HTTP(S) URL, or base64 data URL. Supported formats: mp4, mpeg, mov, webm.',
+                                description: 'File path, HTTP(S) URL, or base64 data URL. Supported: mp4 / mpeg / mov / webm.',
                             },
-                            question: {
-                                type: 'string',
-                                description: 'Question or instruction about the video (default: describe).',
-                            },
-                            model: { type: 'string', description: 'Override the model ID.' },
+                            question: { type: 'string' },
+                            model: { type: 'string' },
+                            cache_input: { type: 'boolean' },
+                            cache: { type: 'boolean' },
+                            cache_ttl: { type: 'string' },
+                            cache_clear: { type: 'boolean' },
                         },
                         required: ['video_path'],
                     },
                 },
                 {
                     name: 'search_models',
-                    description: 'Search available OpenRouter models',
+                    description: TOOL_DESCRIPTIONS.search_models,
                     annotations: {
+                        title: 'Search models',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: true,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
@@ -198,47 +389,81 @@ export class ToolHandlers {
                                 },
                             },
                             limit: { type: 'number', minimum: 1, maximum: 50 },
+                            offset: { type: 'number', minimum: 0 },
                         },
                     },
+                    outputSchema: {
+                        type: 'object',
+                        properties: {
+                            results: { type: 'array', items: { type: 'object' } },
+                            offset: { type: 'number' },
+                            limit: { type: 'number' },
+                            total: { type: 'number' },
+                            has_more: { type: 'boolean' },
+                            next_offset: { type: ['number', 'null'] },
+                        },
+                        required: ['results', 'offset', 'limit', 'total', 'has_more', 'next_offset'],
+                    },
                 },
                 {
                     name: 'get_model_info',
-                    description: 'Get details about a specific model',
+                    description: TOOL_DESCRIPTIONS.get_model_info,
                     annotations: {
+                        title: 'Get model info',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: true,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: { model: { type: 'string' } },
                         required: ['model'],
                     },
+                    outputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            name: { type: 'string' },
+                            context_length: { type: 'number' },
+                            architecture: { type: 'object' },
+                        },
+                        required: ['id'],
+                    },
                 },
                 {
                     name: 'validate_model',
-                    description: 'Check if a model ID exists',
+                    description: TOOL_DESCRIPTIONS.validate_model,
                     annotations: {
+                        title: 'Validate model',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: true,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: { model: { type: 'string' } },
                         required: ['model'],
                     },
+                    outputSchema: {
+                        type: 'object',
+                        properties: {
+                            valid: { type: 'boolean' },
+                            model: { type: 'string' },
+                        },
+                        required: ['valid', 'model'],
+                    },
                 },
                 {
                     name: 'generate_image',
-                    description: 'Generate an image from a text prompt. Optionally conditioned on one or more ' +
-                        'reference images (file paths, http(s) URLs, or data URLs) for character / style ' +
-                        'consistency. Sends `modalities: ["image","text"]` by default; override via the ' +
-                        '`modalities` field if needed.',
+                    description: TOOL_DESCRIPTIONS.generate_image,
                     annotations: {
+                        title: 'Generate image',
                         readOnlyHint: false,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
@@ -247,7 +472,6 @@ export class ToolHandlers {
                             model: { type: 'string' },
                             aspect_ratio: {
                                 type: 'string',
-                                description: 'Output aspect ratio (e.g. 1:1, 16:9, 9:16, 4:3, 3:4, 21:9). Model-dependent.',
                                 enum: [
                                     '1:1',
                                     '2:3',
@@ -265,181 +489,227 @@ export class ToolHandlers {
                                     '8:1',
                                 ],
                             },
-                            image_size: {
-                                type: 'string',
-                                description: 'Output resolution bucket. 1K is the default; 0.5K / 2K / 4K are model-dependent.',
-                                enum: ['0.5K', '1K', '2K', '4K'],
-                            },
-                            max_tokens: {
-                                type: 'number',
-                                minimum: 1,
-                                description: 'Cap on completion tokens. Defaults to the model context window, which can trip free-tier quotas; set e.g. 4096 on low-credit accounts.',
-                            },
-                            save_path: {
-                                type: 'string',
-                                description: 'Optional path to save the image. Routed through the OPENROUTER_OUTPUT_DIR sandbox.',
-                            },
-                            input_images: {
-                                type: 'array',
-                                items: { type: 'string' },
-                                description: 'Optional reference images for visual consistency. Each entry may be a ' +
-                                    'local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / ' +
-                                    'cwd), an http(s) URL, or a `data:image/...;base64,...` URL. Inlined as ' +
-                                    'multimodal user content in the order given.',
-                            },
-                            modalities: {
-                                type: 'array',
-                                items: { type: 'string' },
-                                description: 'Override the default `modalities: ["image","text"]` sent to OpenRouter. ' +
-                                    'Most callers should leave this unset. Provide e.g. ["text"] to suppress ' +
-                                    'image output for inspection / captioning.',
-                            },
+                            image_size: { type: 'string', enum: ['0.5K', '1K', '2K', '4K'] },
+                            max_tokens: { type: 'number', minimum: 1 },
+                            save_path: { type: 'string' },
+                            input_images: { type: 'array', items: { type: 'string' } },
+                            modalities: { type: 'array', items: { type: 'string' } },
                         },
                         required: ['prompt'],
                     },
                 },
                 {
                     name: 'generate_audio',
-                    description: 'Generate audio from a text prompt. Conversational models (e.g. openai/gpt-audio) respond in spoken audio. Music models (e.g. google/lyria-3-clip-preview) need a structured prompt. Output format is auto-detected and file extension is corrected automatically.',
+                    description: TOOL_DESCRIPTIONS.generate_audio,
                     annotations: {
+                        title: 'Generate audio',
                         readOnlyHint: false,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            prompt: { type: 'string', description: 'Text input' },
-                            model: { type: 'string', description: 'Model ID (default: openai/gpt-audio)' },
-                            voice: { type: 'string', description: 'Voice name (default: alloy)' },
-                            format: {
-                                type: 'string',
-                                description: 'Requested format: pcm16 (default), mp3, flac, opus',
-                            },
-                            save_path: {
-                                type: 'string',
-                                description: 'Optional path to save the audio. Extension auto-corrected and routed through OPENROUTER_OUTPUT_DIR sandbox.',
-                            },
+                            prompt: { type: 'string' },
+                            model: { type: 'string' },
+                            voice: { type: 'string' },
+                            format: { type: 'string' },
+                            save_path: { type: 'string' },
                         },
                         required: ['prompt'],
                     },
                 },
                 {
                     name: 'generate_video',
-                    description: 'Generate a video from a text prompt using an OpenRouter video-generation model (default: google/veo-3.1). ' +
-                        'Submits an async job, polls until completion or max_wait_ms, then downloads the result. ' +
-                        'Optionally conditioned on first/last-frame images or reference images. ' +
-                        'Large outputs are auto-saved when save_path is provided and path-sandboxed.',
+                    description: TOOL_DESCRIPTIONS.generate_video,
                     annotations: {
+                        title: 'Generate video',
                         readOnlyHint: false,
                         destructiveHint: false,
                         idempotentHint: false,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            prompt: { type: 'string', description: 'Text description of the desired video.' },
-                            model: { type: 'string', description: 'Override the video model ID.' },
-                            resolution: {
-                                type: 'string',
-                                description: '480p / 720p / 1080p / 1K / 2K / 4K (model-dependent).',
-                            },
-                            aspect_ratio: {
-                                type: 'string',
-                                description: '16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / 9:21 (model-dependent).',
-                            },
-                            duration: {
-                                type: 'number',
-                                minimum: 1,
-                                description: 'Duration in seconds (model-dependent).',
-                            },
-                            seed: { type: 'number', description: 'Deterministic seed when supported.' },
-                            first_frame_image: {
-                                type: 'string',
-                                description: 'Optional image (path, URL, or data URL) used as the first frame for image-to-video.',
-                            },
-                            last_frame_image: {
-                                type: 'string',
-                                description: 'Optional image used as the last frame for frame transitions.',
-                            },
-                            reference_images: {
-                                type: 'array',
-                                items: { type: 'string' },
-                                description: 'Optional style/content reference images.',
-                            },
-                            provider: {
-                                type: 'object',
-                                description: 'Provider-specific passthrough options keyed by provider slug.',
-                            },
-                            save_path: {
+                            prompt: { type: 'string' },
+                            model: { type: 'string' },
+                            resolution: { type: 'string' },
+                            aspect_ratio: { type: 'string' },
+                            duration: { type: 'number', minimum: 1 },
+                            seed: { type: 'number' },
+                            first_frame_image: { type: 'string' },
+                            last_frame_image: { type: 'string' },
+                            reference_images: { type: 'array', items: { type: 'string' } },
+                            provider: { type: 'object' },
+                            save_path: { type: 'string' },
+                            max_wait_ms: { type: 'number', minimum: 10000 },
+                            poll_interval_ms: { type: 'number', minimum: 2000 },
+                        },
+                        required: ['prompt'],
+                    },
+                },
+                {
+                    name: 'generate_video_from_image',
+                    description: TOOL_DESCRIPTIONS.generate_video_from_image,
+                    annotations: {
+                        title: 'Generate video from image',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        idempotentHint: false,
+                        openWorldHint: true,
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            image: {
                                 type: 'string',
-                                description: 'Where to save the video. Routed through the OPENROUTER_OUTPUT_DIR sandbox; extension auto-corrected.',
-                            },
-                            max_wait_ms: {
-                                type: 'number',
-                                minimum: 10000,
-                                description: 'Total time to wait for the async job before returning a resumable handle (default 600000 ms).',
-                            },
-                            poll_interval_ms: {
-                                type: 'number',
-                                minimum: 2000,
-                                description: 'Polling cadence (default 15000 ms).',
+                                description: 'First-frame image (path, URL, or data URL). Required.',
                             },
+                            prompt: { type: 'string' },
+                            model: { type: 'string' },
+                            resolution: { type: 'string' },
+                            aspect_ratio: { type: 'string' },
+                            duration: { type: 'number', minimum: 1 },
+                            seed: { type: 'number' },
+                            save_path: { type: 'string' },
+                            max_wait_ms: { type: 'number', minimum: 10000 },
+                            poll_interval_ms: { type: 'number', minimum: 2000 },
                         },
-                        required: ['prompt'],
+                        required: ['image', 'prompt'],
                     },
                 },
                 {
                     name: 'get_video_status',
-                    description: 'Resume a previously submitted video generation job by id. Returns the latest status; if completed, ' +
-                        'downloads the video (and saves it when save_path is provided).',
+                    description: TOOL_DESCRIPTIONS.get_video_status,
                     annotations: {
+                        title: 'Get video status',
                         readOnlyHint: true,
                         destructiveHint: false,
                         idempotentHint: true,
+                        openWorldHint: true,
                     },
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            video_id: { type: 'string', description: 'Job id from a previous generate_video call.' },
-                            save_path: {
-                                type: 'string',
-                                description: 'Optional save path (applies when the job is already completed).',
-                            },
+                            video_id: { type: 'string' },
+                            save_path: { type: 'string' },
                         },
                         required: ['video_id'],
                     },
                 },
+                {
+                    name: 'rerank_documents',
+                    description: TOOL_DESCRIPTIONS.rerank_documents,
+                    annotations: {
+                        title: 'Rerank documents',
+                        readOnlyHint: true,
+                        destructiveHint: false,
+                        idempotentHint: true,
+                        openWorldHint: true,
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: { type: 'string' },
+                            documents: { type: 'array', items: { type: 'string' }, minItems: 1 },
+                            model: { type: 'string' },
+                            top_n: { type: 'number', minimum: 1 },
+                            return_documents: { type: 'boolean' },
+                        },
+                        required: ['query', 'documents'],
+                    },
+                    outputSchema: {
+                        type: 'object',
+                        properties: {
+                            model: { type: 'string' },
+                            results: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        index: { type: 'number' },
+                                        score: { type: 'number' },
+                                        document: { type: 'string' },
+                                    },
+                                    required: ['index', 'score'],
+                                },
+                            },
+                        },
+                        required: ['results'],
+                    },
+                },
+                {
+                    name: 'health_check',
+                    description: TOOL_DESCRIPTIONS.health_check,
+                    annotations: {
+                        title: 'Health check',
+                        readOnlyHint: true,
+                        destructiveHint: false,
+                        idempotentHint: true,
+                        openWorldHint: true,
+                    },
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: {
+                        type: 'object',
+                        properties: {
+                            ok: { type: 'boolean' },
+                            server_version: { type: 'string' },
+                            protocol_version: { type: 'string' },
+                            api_key_valid: { type: 'boolean' },
+                            models_cached: { type: 'number' },
+                            error: { type: 'string' },
+                        },
+                        required: ['ok', 'server_version', 'protocol_version', 'api_key_valid', 'models_cached'],
+                    },
+                },
             ],
         }));
         server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
-            switch (name) {
-                case 'chat_completion':
-                    return handleChatCompletion(wrapToolArgs(args), this.openai, this.defaultModel);
-                case 'analyze_image':
-                    return handleAnalyzeImage(wrapToolArgs(args), this.openai, this.defaultModel);
-                case 'analyze_audio':
-                    return handleAnalyzeAudio(wrapToolArgs(args), this.openai, this.defaultModel);
-                case 'analyze_video':
-                    return handleAnalyzeVideo(wrapToolArgs(args), this.openai, this.defaultModel);
-                case 'search_models':
-                    return handleSearchModels(wrapToolArgs(args), this.apiClient, this.modelCache);
-                case 'get_model_info':
-                    return handleGetModelInfo(wrapToolArgs(args), this.modelCache, this.apiClient);
-                case 'validate_model':
-                    return handleValidateModel(wrapToolArgs(args), this.modelCache, this.apiClient);
-                case 'generate_image':
-                    return handleGenerateImage(wrapToolArgs(args), this.openai);
-                case 'generate_audio':
-                    return handleGenerateAudio(wrapToolArgs(args), this.openai);
-                case 'generate_video':
-                    return handleGenerateVideo(wrapToolArgs(args), this.apiClient);
-                case 'get_video_status':
-                    return handleGetVideoStatus(wrapToolArgs(args), this.apiClient);
-                default:
-                    throw new McpError(McpErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-            }
+            // Our handlers return structured shapes that satisfy CallToolResult's
+            // open interface (content + optional _meta + optional isError +
+            // optional structuredContent). We cast through unknown because
+            // several handlers include server-specific _meta keys (e.g.
+            // server_version, cache, code) that aren't listed in the SDK's
+            // typed schema — the SDK accepts any extras thanks to the
+            // `[x: string]: unknown` index signature.
+            const dispatch = async () => {
+                switch (name) {
+                    case 'chat_completion':
+                        return handleChatCompletion(wrapToolArgs(args), this.openai, this.defaultModel);
+                    case 'analyze_image':
+                        return handleAnalyzeImage(wrapToolArgs(args), this.openai, this.defaultModel);
+                    case 'analyze_audio':
+                        return handleAnalyzeAudio(wrapToolArgs(args), this.openai, this.defaultModel);
+                    case 'analyze_video':
+                        return handleAnalyzeVideo(wrapToolArgs(args), this.openai, this.defaultModel);
+                    case 'search_models':
+                        return handleSearchModels(wrapToolArgs(args), this.apiClient, this.modelCache);
+                    case 'get_model_info':
+                        return handleGetModelInfo(wrapToolArgs(args), this.modelCache, this.apiClient);
+                    case 'validate_model':
+                        return handleValidateModel(wrapToolArgs(args), this.modelCache, this.apiClient);
+                    case 'generate_image':
+                        return handleGenerateImage(wrapToolArgs(args), this.openai);
+                    case 'generate_audio':
+                        return handleGenerateAudio(wrapToolArgs(args), this.openai);
+                    case 'generate_video':
+                        return handleGenerateVideo(wrapToolArgs(args), this.apiClient, buildProgressHook(this.server, extractProgressToken(request)));
+                    case 'generate_video_from_image':
+                        return handleGenerateVideoFromImage(wrapToolArgs(args), this.apiClient, buildProgressHook(this.server, extractProgressToken(request)));
+                    case 'get_video_status':
+                        return handleGetVideoStatus(wrapToolArgs(args), this.apiClient);
+                    case 'rerank_documents':
+                        return handleRerankDocuments(wrapToolArgs(args), this.apiClient);
+                    case 'health_check':
+                        return handleHealthCheck(wrapToolArgs(args), this.apiClient, this.modelCache);
+                    default:
+                        throw new McpError(McpErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                }
+            };
+            return (await dispatch());
         });
     }
 }