@stabgan/openrouter-mcp-multimodal 4.7.0 → 5.0.0

package/dist/tool-definitions.js

@@ -1,8 +1,84 @@
-import { TOOL_DESCRIPTIONS } from './tool-descriptions.js';
-/** Shared JSON-schema fragment for save_path on generate/write tools. */
-const SAVE_PATH_PROPERTY = {
+import { TOOL_DESCRIPTIONS, TOOL_NAMES } from './tool-descriptions.js';
+import { DEFAULT_TTS_MODEL, DEFAULT_TTS_RESPONSE_FORMAT, DEFAULT_TTS_VOICE, } from './tts-defaults.js';
+/** Aspect ratios accepted by generate_image and generate_image_dedicated handlers. */
+export const IMAGE_ASPECT_RATIOS = [
+    '1:1',
+    '2:3',
+    '3:2',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+    '1:4',
+    '4:1',
+    '1:8',
+    '8:1',
+];
+export const IMAGE_SIZES = ['0.5K', '1K', '2K', '4K'];
+export const IMAGE_DEDICATED_RESOLUTIONS = ['512', '0.5K', '1K', '2K', '4K'];
+export const IMAGE_DEDICATED_QUALITIES = ['auto', 'low', 'medium', 'high'];
+export const IMAGE_OUTPUT_FORMATS = ['png', 'jpeg', 'webp', 'svg'];
+/** generate_audio handler VALID_FORMATS */
+export const GENERATE_AUDIO_FORMATS = ['wav', 'mp3', 'flac', 'opus', 'pcm16'];
+/** text_to_speech handler VALID_FORMATS */
+export const TTS_RESPONSE_FORMATS = ['mp3', 'pcm'];
+/** speech_to_text handler VALID_RESPONSE_FORMATS */
+export const STT_RESPONSE_FORMATS = ['json', 'text', 'srt', 'verbose_json', 'vtt'];
+export const CHAT_MESSAGE_ROLES = ['system', 'user', 'assistant'];
+export const PROVIDER_SORT_VALUES = ['price', 'throughput', 'latency'];
+export const PROVIDER_DATA_COLLECTION = ['allow', 'deny'];
+/** Tools whose handlers accept save_path (binary artifact output). */
+export const TOOLS_WITH_SAVE_PATH = [
+    'generate_image',
+    'generate_image_dedicated',
+    'generate_audio',
+    'text_to_speech',
+    'generate_video',
+    'generate_video_from_image',
+    'get_video_status',
+];
+/** Shared save_path fragment for binary-output tools. */
+export const SAVE_PATH_PROPERTY = {
     type: 'string',
-    description: 'Write the artifact under OPENROUTER_OUTPUT_DIR (path-sandboxed). When set, the tool result is text-only with _meta.save_path — no inline media block. Without save_path, inline image/audio/video is returned only if under OPENROUTER_*_INLINE_MAX_BYTES (see .env.example).',
+    description: 'Write the artifact under OPENROUTER_OUTPUT_DIR (path-sandboxed). When set, the tool result is text-only with _meta.save_path — no inline media block. ' +
+        'When unset, inline image/audio (default 1 MiB) or video (default 10 MiB) is returned only if under the per-kind ceiling: ' +
+        'OPENROUTER_IMAGE_INLINE_MAX_BYTES, OPENROUTER_AUDIO_INLINE_MAX_BYTES, OPENROUTER_VIDEO_INLINE_MAX_BYTES ' +
+        '(global fallback OPENROUTER_INLINE_MAX_BYTES). See .env.example.',
+};
+const SAVE_PATH_WITH_PREFIX = (prefix) => ({
+    ...SAVE_PATH_PROPERTY,
+    description: `${prefix} ${SAVE_PATH_PROPERTY.description}`,
+});
+const CHAT_MESSAGE_SCHEMA = {
+    type: 'array',
+    minItems: 1,
+    items: {
+        type: 'object',
+        properties: {
+            role: { type: 'string', enum: [...CHAT_MESSAGE_ROLES] },
+            content: {
+                oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
+            },
+        },
+        required: ['role', 'content'],
+    },
+};
+const CACHE_PROPERTIES = {
+    cache: {
+        type: 'boolean',
+        description: 'Enable OpenRouter response caching via `X-OpenRouter-Cache: true`. Server default: `OPENROUTER_CACHE_RESPONSES=1`.',
+    },
+    cache_ttl: {
+        type: 'string',
+        description: 'Cache TTL as integer seconds (1–86400) or a duration string such as "30s", "5m", or "1h". Sent upstream as seconds.',
+    },
+    cache_clear: {
+        type: 'boolean',
+        description: 'Bust the cache entry for this exact request.',
+    },
 };
 export const TOOL_DEFINITIONS = [
     {
@@ -20,26 +96,10 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 model: {
                     type: 'string',
-                    description: 'Model ID (optional, uses default). Append `:nitro` for the fastest variant, ' +
-                        '`:floor` for the cheapest, `:free` for the free tier, `:online` for web search, ' +
-                        'or `:exacto` for the best tool-calling accuracy. ' +
-                        'Example: `openai/gpt-4o:nitro`. Or pass `online: true` for programmatic web search control.',
+                    description: 'Model ID (optional, uses server default). Append `:nitro` (fastest), `:floor` (cheapest), `:free`, `:online` (web search), or `:exacto` (tool accuracy). Example: `openai/gpt-4o:nitro`. Or pass `online: true` for programmatic web search.',
                 },
-                messages: {
-                    type: 'array',
-                    minItems: 1,
-                    items: {
-                        type: 'object',
-                        properties: {
-                            role: { type: 'string', enum: ['system', 'user', 'assistant'] },
-                            content: {
-                                oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
-                            },
-                        },
-                        required: ['role', 'content'],
-                    },
-                },
-                temperature: { type: 'number', minimum: 0, maximum: 2 },
+                messages: CHAT_MESSAGE_SCHEMA,
+                temperature: { type: 'number', minimum: 0, maximum: 2, description: 'Default: 1.' },
                 max_tokens: {
                     type: 'number',
                     minimum: 1,
@@ -47,8 +107,7 @@ export const TOOL_DEFINITIONS = [
                 },
                 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',
@@ -60,19 +119,16 @@ export const TOOL_DEFINITIONS = [
                             items: { type: 'string' },
                             description: 'Exclude these provider slugs.',
                         },
-                        sort: {
-                            type: 'string',
-                            enum: ['price', 'throughput', 'latency'],
-                        },
+                        sort: { type: 'string', enum: [...PROVIDER_SORT_VALUES] },
                         order: { type: 'array', items: { type: 'string' } },
                         require_parameters: { type: 'boolean' },
-                        data_collection: { type: 'string', enum: ['allow', 'deny'] },
+                        data_collection: { type: 'string', enum: [...PROVIDER_DATA_COLLECTION] },
                         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.",
+                    description: "Surface the model's chain-of-thought on `_meta.reasoning` for R1 / Opus / Gemini Thinking models.",
                 },
                 online: {
                     type: 'boolean',
@@ -83,19 +139,7 @@ export const TOOL_DEFINITIONS = [
                     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.',
-                },
+                ...CACHE_PROPERTIES,
             },
             required: ['messages'],
         },
@@ -113,30 +157,15 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                model: { type: 'string', description: 'Model ID (same as chat_completion).' },
-                messages: {
-                    type: 'array',
-                    minItems: 1,
-                    items: {
-                        type: 'object',
-                        properties: {
-                            role: { type: 'string', enum: ['system', 'user', 'assistant'] },
-                            content: {
-                                oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
-                            },
-                        },
-                        required: ['role', 'content'],
-                    },
-                },
+                model: { type: 'string', description: 'Model ID (same options as chat_completion).' },
+                messages: CHAT_MESSAGE_SCHEMA,
                 temperature: { type: 'number', minimum: 0, maximum: 2 },
                 max_tokens: { type: 'number', minimum: 1 },
                 provider: { type: 'object' },
                 include_reasoning: { type: 'boolean' },
                 online: { type: 'boolean' },
                 web_max_results: { type: 'number', minimum: 1 },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                ...CACHE_PROPERTIES,
             },
             required: ['messages'],
         },
@@ -177,23 +206,21 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 image_path: {
                     type: 'string',
-                    description: 'Required. Local path (inside OPENROUTER_INPUT_DIR sandbox), https URL, or data URL. ' +
-                        'Good: `"photo.jpg"`. Bad: `"url": "..."` (wrong key), `"/etc/passwd"` (UNSAFE_PATH).',
+                    description: 'Local path (OPENROUTER_INPUT_DIR sandbox), https URL, or data URL. Good: `"photo.jpg"`. Bad: `"url": "..."` (wrong key), `"/etc/passwd"` (UNSAFE_PATH).',
                 },
                 question: {
                     type: 'string',
-                    description: 'Optional question about the image. Defaults to "What\'s in this image?" if omitted. ' +
-                        'Good: `"List all text"`. Bad: using `prompt` key (wrong name for this tool).',
+                    description: 'Optional question. Default: "What\'s in this image?". Bad: using `prompt` (wrong key for this tool).',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Vision model ID (optional; server default is a free multimodal model).',
                 },
-                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.',
+                    description: 'Attach `cache_control: ephemeral` to the image block for Anthropic / Gemini prompt caching.',
                 },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                ...CACHE_PROPERTIES,
             },
             required: ['image_path'],
         },
@@ -213,18 +240,18 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 audio_path: {
                     type: 'string',
-                    description: 'Local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / cwd), ' +
-                        'http(s) URL, or data URL (base64-encoded audio)',
+                    description: 'Local file path (sandboxed), http(s) URL, or data URL (base64-encoded audio).',
                 },
                 question: {
                     type: 'string',
-                    description: 'Question or instruction about the audio (default: transcribe)',
+                    description: 'Question or instruction. Default: "Please transcribe and analyze this audio file."',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Multimodal model ID (default: google/gemini-2.5-flash).',
                 },
-                model: { type: 'string' },
                 cache_input: { type: 'boolean' },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                ...CACHE_PROPERTIES,
             },
             required: ['audio_path'],
         },
@@ -244,15 +271,18 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 video_path: {
                     type: 'string',
-                    description: 'Local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / cwd), ' +
-                        'http(s) URL, or base64 data URL. Supported: mp4 / mpeg / mov / webm.',
+                    description: 'Local file path (sandboxed), http(s) URL, or base64 data URL. Supported containers: mp4, mpeg, mov, webm.',
+                },
+                question: {
+                    type: 'string',
+                    description: 'Optional question. Default: "Describe what happens in this video, step by step."',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Video-capable model ID (default: google/gemini-2.5-flash).',
                 },
-                question: { type: 'string' },
-                model: { type: 'string' },
                 cache_input: { type: 'boolean' },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                ...CACHE_PROPERTIES,
             },
             required: ['video_path'],
         },
@@ -270,8 +300,11 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string' },
-                provider: { type: 'string' },
+                query: { type: 'string', description: 'Substring match against model id or name.' },
+                provider: {
+                    type: 'string',
+                    description: 'Filter by provider slug prefix (e.g. `google`).',
+                },
                 capabilities: {
                     type: 'object',
                     properties: {
@@ -280,8 +313,13 @@ export const TOOL_DEFINITIONS = [
                         video: { type: 'boolean' },
                     },
                 },
-                limit: { type: 'number', minimum: 1, maximum: 50 },
-                offset: { type: 'number', minimum: 0 },
+                limit: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 50,
+                    description: 'Page size (default 20, max 50).',
+                },
+                offset: { type: 'number', minimum: 0, description: 'Pagination offset (default 0).' },
             },
         },
         outputSchema: {
@@ -309,7 +347,12 @@ export const TOOL_DEFINITIONS = [
         },
         inputSchema: {
             type: 'object',
-            properties: { model: { type: 'string' } },
+            properties: {
+                model: {
+                    type: 'string',
+                    description: 'Full OpenRouter model slug (e.g. `openai/gpt-4o`).',
+                },
+            },
             required: ['model'],
         },
         outputSchema: {
@@ -335,7 +378,9 @@ export const TOOL_DEFINITIONS = [
         },
         inputSchema: {
             type: 'object',
-            properties: { model: { type: 'string' } },
+            properties: {
+                model: { type: 'string', description: 'Full OpenRouter model slug to check.' },
+            },
             required: ['model'],
         },
         outputSchema: {
@@ -360,32 +405,33 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                prompt: { type: 'string' },
-                model: { type: 'string' },
+                prompt: { type: 'string', description: 'Text prompt describing the image to generate.' },
+                model: {
+                    type: 'string',
+                    description: 'Image model ID (default: google/gemini-2.5-flash-image). Chat-completions route.',
+                },
                 aspect_ratio: {
                     type: 'string',
-                    enum: [
-                        '1:1',
-                        '2:3',
-                        '3:2',
-                        '3:4',
-                        '4:3',
-                        '4:5',
-                        '5:4',
-                        '9:16',
-                        '16:9',
-                        '21:9',
-                        '1:4',
-                        '4:1',
-                        '1:8',
-                        '8:1',
-                    ],
-                },
-                image_size: { type: 'string', enum: ['0.5K', '1K', '2K', '4K'] },
-                max_tokens: { type: 'number', minimum: 1 },
+                    enum: [...IMAGE_ASPECT_RATIOS],
+                    description: 'Optional aspect ratio (provider-dependent).',
+                },
+                image_size: {
+                    type: 'string',
+                    enum: [...IMAGE_SIZES],
+                    description: 'Optional resolution tier for supported models.',
+                },
+                max_tokens: { type: 'number', minimum: 1, description: 'Optional completion token cap.' },
                 save_path: SAVE_PATH_PROPERTY,
-                input_images: { type: 'array', items: { type: 'string' } },
-                modalities: { type: 'array', items: { type: 'string' } },
+                input_images: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Reference images (local path, URL, or data URL) for style/identity conditioning.',
+                },
+                modalities: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Response modalities (default: `["image","text"]`).',
+                },
             },
             required: ['prompt'],
         },
@@ -409,49 +455,45 @@ export const TOOL_DEFINITIONS = [
                 },
                 model: {
                     type: 'string',
-                    description: 'Image model ID. Default: google/gemini-2.5-flash-image. Browse available at https://openrouter.ai/collections/image-models',
+                    description: 'Image model ID. Default: google/gemini-2.5-flash-image. Browse: https://openrouter.ai/collections/image-models',
                 },
                 resolution: {
                     type: 'string',
-                    enum: ['512', '0.5K', '1K', '2K', '4K'],
+                    enum: [...IMAGE_DEDICATED_RESOLUTIONS],
                     description: 'Normalized resolution tier. Provider maps to closest supported size.',
                 },
                 aspect_ratio: {
                     type: 'string',
-                    description: 'Aspect ratio (e.g. "1:1", "16:9", "9:16", "4:3", "21:9").',
+                    enum: [...IMAGE_ASPECT_RATIOS],
+                    description: 'Aspect ratio (same enum as generate_image).',
                 },
                 quality: {
                     type: 'string',
-                    enum: ['auto', 'low', 'medium', 'high'],
-                    description: 'Image quality level.',
+                    enum: [...IMAGE_DEDICATED_QUALITIES],
+                    description: 'Image quality level (default: auto).',
                 },
                 output_format: {
                     type: 'string',
-                    enum: ['png', 'jpeg', 'webp', 'svg'],
+                    enum: [...IMAGE_OUTPUT_FORMATS],
                     description: 'Output image format.',
                 },
                 n: {
                     type: 'number',
                     minimum: 1,
                     maximum: 10,
-                    description: 'Number of images to generate (model-dependent, default 1).',
+                    description: 'Number of images to request (default 1; only images[0] is saved/inlined).',
                 },
                 input_references: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Reference images for image-to-image workflows. Each entry: local path, http(s) URL, or data URL.',
-                },
-                save_path: {
-                    ...SAVE_PATH_PROPERTY,
-                    description: 'Save generated image to this path. ' + SAVE_PATH_PROPERTY.description,
+                    description: 'Reference images for image-to-image. Each entry: local path, http(s) URL, or data URL.',
                 },
+                save_path: SAVE_PATH_WITH_PREFIX('Save generated image to this path.'),
                 provider: {
                     type: 'object',
                     description: 'Provider routing overrides (order, sort, allow_fallbacks, etc.).',
                 },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                ...CACHE_PROPERTIES,
             },
             required: ['prompt'],
         },
@@ -469,10 +511,20 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                prompt: { type: 'string' },
-                model: { type: 'string' },
-                voice: { type: 'string' },
-                format: { type: 'string' },
+                prompt: { type: 'string', description: 'Text prompt for speech or music generation.' },
+                model: {
+                    type: 'string',
+                    description: 'Chat-completions audio model (default: openai/gpt-audio).',
+                },
+                voice: {
+                    type: 'string',
+                    description: 'Voice ID (default: alloy). Model-specific.',
+                },
+                format: {
+                    type: 'string',
+                    enum: [...GENERATE_AUDIO_FORMATS],
+                    description: 'Output audio format (default: pcm16, auto-wrapped as WAV when needed).',
+                },
                 save_path: SAVE_PATH_PROPERTY,
             },
             required: ['prompt'],
@@ -497,34 +549,29 @@ export const TOOL_DEFINITIONS = [
                 },
                 model: {
                     type: 'string',
-                    description: 'TTS model. Default: openai/gpt-4o-mini-tts-2025-12-15. Also: google/gemini-flash-tts, mistral/voxtral-mini-tts.',
+                    description: `TTS model for OpenRouter POST /audio/speech. Default: ${DEFAULT_TTS_MODEL}. Discover current models with GET /api/v1/models?output_modalities=speech.`,
                 },
                 voice: {
                     type: 'string',
-                    description: 'Voice ID (model-specific). Default: alloy. OpenAI voices: alloy, echo, fable, onyx, nova, shimmer.',
+                    description: `Voice ID (model-specific). Default: ${DEFAULT_TTS_VOICE} for ${DEFAULT_TTS_MODEL}; pass a voice supported by another model.`,
                 },
                 response_format: {
                     type: 'string',
-                    enum: ['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'],
-                    description: 'Output audio format. Default: mp3.',
+                    enum: [...TTS_RESPONSE_FORMATS],
+                    description: `Output audio format (mp3 or pcm). Default: ${DEFAULT_TTS_RESPONSE_FORMAT}.`,
                 },
                 speed: {
                     type: 'number',
                     minimum: 0.25,
                     maximum: 4.0,
-                    description: 'Speed of speech (0.25 to 4.0). Default: 1.0.',
+                    description: 'Speed of speech (0.25–4.0). Default: 1.0.',
                 },
                 instructions: {
                     type: 'string',
                     description: 'Tone/style instructions (e.g. "speak in a warm, friendly tone"). OpenAI models only.',
                 },
-                save_path: {
-                    ...SAVE_PATH_PROPERTY,
-                    description: 'Save audio to this path. ' + SAVE_PATH_PROPERTY.description,
-                },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                save_path: SAVE_PATH_WITH_PREFIX('Save audio to this path.'),
+                ...CACHE_PROPERTIES,
             },
             required: ['input'],
         },
@@ -544,7 +591,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 audio_path: {
                     type: 'string',
-                    description: 'Audio file: local path (sandboxed), http(s) URL, or base64 data URL. Formats: mp3, wav, flac, ogg, webm, mp4.',
+                    description: 'Audio file: local path (sandboxed), http(s) URL, or base64 data URL. Formats: mp3, wav, flac, ogg, webm, mp4, m4a.',
                 },
                 model: {
                     type: 'string',
@@ -556,18 +603,16 @@ export const TOOL_DEFINITIONS = [
                 },
                 response_format: {
                     type: 'string',
-                    enum: ['json', 'text', 'srt', 'verbose_json', 'vtt'],
+                    enum: [...STT_RESPONSE_FORMATS],
                     description: 'Output format for transcription. Default: json.',
                 },
                 temperature: {
                     type: 'number',
                     minimum: 0,
                     maximum: 1,
-                    description: 'Sampling temperature for transcription (0-1).',
+                    description: 'Sampling temperature for transcription (0–1).',
                 },
-                cache: { type: 'boolean' },
-                cache_ttl: { type: 'string' },
-                cache_clear: { type: 'boolean' },
+                ...CACHE_PROPERTIES,
             },
             required: ['audio_path'],
         },
@@ -585,19 +630,50 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                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' },
+                prompt: { type: 'string', description: 'Text prompt describing the video to generate.' },
+                model: {
+                    type: 'string',
+                    description: 'Video model ID (default: google/veo-3.1). Passed through to provider.',
+                },
+                resolution: {
+                    type: 'string',
+                    description: 'Provider-specific resolution (e.g. "720p", "1080p"). No server-side enum.',
+                },
+                aspect_ratio: {
+                    type: 'string',
+                    description: 'Provider-specific aspect ratio (e.g. "16:9", "9:16"). No server-side enum.',
+                },
+                duration: {
+                    type: 'number',
+                    minimum: 1,
+                    description: 'Clip duration in seconds (provider-dependent).',
+                },
+                seed: { type: 'number', description: 'Optional reproducibility seed.' },
+                first_frame_image: {
+                    type: 'string',
+                    description: 'Optional first-frame image (path, URL, or data URL).',
+                },
+                last_frame_image: {
+                    type: 'string',
+                    description: 'Optional last-frame image (path, URL, or data URL).',
+                },
+                reference_images: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional reference images for style/subject guidance.',
+                },
+                provider: { type: 'object', description: 'Provider routing overrides.' },
                 save_path: SAVE_PATH_PROPERTY,
-                max_wait_ms: { type: 'number', minimum: 10000 },
-                poll_interval_ms: { type: 'number', minimum: 2000 },
+                max_wait_ms: {
+                    type: 'number',
+                    minimum: 100,
+                    description: 'Max time to poll before returning JOB_STILL_RUNNING (ms). Default: 600000 (10 min) via OPENROUTER_VIDEO_MAX_WAIT_MS.',
+                },
+                poll_interval_ms: {
+                    type: 'number',
+                    minimum: 50,
+                    description: 'Poll interval while waiting (ms). Default: 15000 via OPENROUTER_VIDEO_POLL_INTERVAL_MS.',
+                },
             },
             required: ['prompt'],
         },
@@ -619,15 +695,23 @@ export const TOOL_DEFINITIONS = [
                     type: 'string',
                     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' },
+                prompt: { type: 'string', description: 'Motion/scene prompt describing the video.' },
+                model: { type: 'string', description: 'Video model ID (default: google/veo-3.1).' },
+                resolution: { type: 'string', description: 'Provider-specific resolution.' },
+                aspect_ratio: { type: 'string', description: 'Provider-specific aspect ratio.' },
+                duration: { type: 'number', minimum: 1, description: 'Clip duration in seconds.' },
+                seed: { type: 'number', description: 'Optional reproducibility seed.' },
                 save_path: SAVE_PATH_PROPERTY,
-                max_wait_ms: { type: 'number', minimum: 10000 },
-                poll_interval_ms: { type: 'number', minimum: 2000 },
+                max_wait_ms: {
+                    type: 'number',
+                    minimum: 100,
+                    description: 'Max poll wait (ms) before JOB_STILL_RUNNING. Default: 600000.',
+                },
+                poll_interval_ms: {
+                    type: 'number',
+                    minimum: 50,
+                    description: 'Poll interval (ms). Default: 15000.',
+                },
             },
             required: ['image', 'prompt'],
         },
@@ -645,7 +729,10 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                video_id: { type: 'string' },
+                video_id: {
+                    type: 'string',
+                    description: 'Video job id from generate_video / generate_video_from_image.',
+                },
                 save_path: SAVE_PATH_PROPERTY,
             },
             required: ['video_id'],
@@ -664,11 +751,17 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string' },
+                query: { type: 'string', description: 'Search query to rank documents against.' },
                 documents: { type: 'array', items: { type: 'string' }, minItems: 1 },
-                model: { type: 'string' },
-                top_n: { type: 'number', minimum: 1 },
-                return_documents: { type: 'boolean' },
+                model: {
+                    type: 'string',
+                    description: 'Reranker model (default: cohere/rerank-v3.5).',
+                },
+                top_n: { type: 'number', minimum: 1, description: 'Return only the top N results.' },
+                return_documents: {
+                    type: 'boolean',
+                    description: 'When true, include original document text in each result.',
+                },
             },
             required: ['query', 'documents'],
         },
@@ -717,3 +810,13 @@ export const TOOL_DEFINITIONS = [
         },
     },
 ];
+/** Tool names from definitions — must match TOOL_NAMES in tool-descriptions.ts. */
+export const TOOL_DEFINITION_NAMES = TOOL_DEFINITIONS.map((t) => t.name);
+if (TOOL_DEFINITION_NAMES.length !== TOOL_NAMES.length) {
+    throw new Error(`Tool count mismatch: definitions=${TOOL_DEFINITION_NAMES.length} descriptions=${TOOL_NAMES.length}`);
+}
+for (const name of TOOL_NAMES) {
+    if (!TOOL_DEFINITION_NAMES.includes(name)) {
+        throw new Error(`Missing tool definition for ${name}`);
+    }
+}