@mixio-pro/kalaasetu-mcp 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixio-pro/kalaasetu-mcp",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A powerful Model Context Protocol server providing AI tools for content generation and analysis",
   "type": "module",
   "module": "src/index.ts",

package/src/tools/fal/generate.ts

@@ -58,27 +58,36 @@ function sanitizeParameters(
   );
 }
 
-/**
- * Unified generation tool using presets defined in configuration.
- */
 export const falGenerate = {
   name: "fal_generate",
   description:
-    "Generate content using a named preset and optional parameters. Use fal_list_presets to discover available intents and preset names.",
+    "The primary tool for generating AI content (images, videos, etc.) using fal.ai. " +
+    "This tool follows a 'Preset' pattern: you choose a high-level intent (preset_name) and provide optional parameters. " +
+    "Use 'fal_list_presets' to discover available intents and names. " +
+    "PREREQUISITE: If using local files as parameters, you MUST upload them first using 'fal_upload_file' and use the resulting CDN URL. " +
+    "If a task is expected to take longer than 10-20 seconds, set 'queue: true' to receive status and result URLs instead of a direct result. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
     preset_name: z
       .string()
-      .describe("The name of the preset to use (e.g., 'cinematic_image')"),
+      .describe(
+        "The unique name of the generation preset (e.g., 'ltx_image_to_video', 'cinematic_image'). Obtain this from 'fal_list_presets'."
+      ),
     parameters: z
       .record(z.string(), z.any())
       .optional()
-      .describe("Optional model-specific parameters to override defaults"),
+      .describe(
+        "A dictionary of model-specific parameters (e.g., { 'prompt': '...', 'image_url': '...' }). " +
+          "These override the default values defined in the preset. " +
+          "NOTE: For image-to-video or video-to-video tasks, use 'fal_upload_file' first and pass the resulting CDN URL here."
+      ),
     queue: z
       .boolean()
       .optional()
       .default(false)
       .describe(
-        "Whether to use the queuing system for long-running tasks. Default: false"
+        "Set to true for asynchronous execution. Use this for high-resolution video or complex tasks. " +
+          "When true, returns 'status_url' and 'cancel_url' instead of the final result."
       ),
   }),
   timeoutMs: 300000,
@@ -126,9 +135,17 @@ export const falGenerate = {
  */
 export const falGetResult = {
   name: "fal_get_result",
-  description: "Get the result of a queued fal.ai request.",
+  description:
+    "Retrieve the final output of a queued/asynchronous fal.ai request. " +
+    "PREREQUISITE: This tool can ONLY be used with request 'response_url's obtained from 'fal_generate' or 'fal_get_status'. " +
+    "Only call this after 'fal_get_status' indicates that the request status is 'COMPLETED'. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
-    url: z.string().describe("The response_url from a queued request"),
+    url: z
+      .string()
+      .describe(
+        "The 'response_url' provided by a queued 'fal_generate' or 'fal_get_status' call."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: { url: string }) => {
@@ -142,9 +159,15 @@ export const falGetResult = {
  */
 export const falGetStatus = {
   name: "fal_get_status",
-  description: "Check the status of a queued fal.ai request.",
+  description:
+    "Check the current progress or status of an asynchronous fal.ai request. " +
+    "PREREQUISITE: This tool can ONLY be used with request 'status_url's obtained from a queued 'fal_generate' call. " +
+    "Use this for polling until the status becomes 'COMPLETED', then use 'fal_get_result' for the final output. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
-    url: z.string().describe("The status_url from a queued request"),
+    url: z
+      .string()
+      .describe("The 'status_url' provided by a queued 'fal_generate' call."),
   }),
   timeoutMs: 300000,
   execute: async (args: { url: string }) => {
@@ -158,9 +181,14 @@ export const falGetStatus = {
  */
 export const falCancelRequest = {
   name: "fal_cancel_request",
-  description: "Cancel a queued fal.ai request.",
+  description:
+    "Terminate and cancel an ongoing asynchronous fal.ai request. " +
+    "PREREQUISITE: This tool can ONLY be used with request 'cancel_url's obtained from a queued 'fal_generate' call. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
-    url: z.string().describe("The cancel_url from a queued request"),
+    url: z
+      .string()
+      .describe("The 'cancel_url' provided by a queued 'fal_generate' call."),
   }),
   timeoutMs: 300000,
   execute: async (args: { url: string }) => {

package/src/tools/fal/models.ts

@@ -13,7 +13,9 @@ import { safeToolExecute } from "../../utils/tool-wrapper";
 export const falListPresets = {
   name: "fal_list_presets",
   description:
-    "List all available generation presets, including their intents, input types, and output types. Use this to find the right preset for a task.",
+    "The entry point for discovering fal.ai capabilities on this server. " +
+    "Lists all available generation presets, including their high-level 'intent' (e.g., 'Generate cinematic video'), " +
+    "and the types of input/output they support. Call this first when you need to perform an AI generation task.",
   parameters: z.object({}),
   timeoutMs: 30000,
   execute: async () => {
@@ -37,9 +39,16 @@ export const falListPresets = {
 export const falGetPresetDetails = {
   name: "fal_get_preset_details",
   description:
-    "Get full details for a specific generation preset, including its model ID and default parameters.",
+    "Retrieve full details for a specific generation preset. " +
+    "Use this to see the 'modelId' being used and, most importantly, the 'defaultParams'. " +
+    "The default parameters shown here can be overridden in the 'parameters' argument of 'fal_generate'. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
-    preset_name: z.string().describe("The name of the preset to inspect"),
+    preset_name: z
+      .string()
+      .describe(
+        "The name of the preset to inspect (e.g., 'ltx_image_to_video')."
+      ),
   }),
   timeoutMs: 30000,
   execute: async (args: { preset_name: string }) => {

package/src/tools/fal/storage.ts

@@ -38,9 +38,16 @@ function getMimeType(filePath: string): string {
  */
 export const falUploadFile = {
   name: "fal_upload_file",
-  description: "Upload a file to fal.ai CDN storage.",
+  description:
+    "Upload a local file (image, video, audio) to fal.ai CDN storage. " +
+    "CRITICAL: You MUST use this tool to upload local files before passing their URLs to generation tools in FAL. ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS" +
+    "It returns a public 'file_url' which should be used as input for 'fal_generate'.",
   parameters: z.object({
-    path: z.string().describe("The absolute path to the file to upload"),
+    path: z
+      .string()
+      .describe(
+        "The absolute local path to the file to upload (e.g., '/Users/name/images/input.jpg')."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: { path: string }) => {

package/src/tools/gemini.ts

@@ -202,23 +202,36 @@ async function processVideoInput(
 export const geminiTextToImage = {
   name: "generateImage",
   description:
-    "Generate images from text prompts using Gemini image models with optional reference images. Returns the URL of the generated image.",
+    "Generate high-quality images from text prompts using Google's Imagen 3 model via Gemini. " +
+    "This tool is highly capable of following complex instructions. " +
+    "Best practices: " +
+    "1. Be descriptive: instead of 'a dog', use 'a golden retriever playing in a sunlit meadow, cinematic lighting'. " +
+    "2. Specify style: e.g., '3D render', 'oil painting', 'minimalist vector art'. " +
+    "3. Use reference images: you can provide existing images to guide the style or content. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
-    prompt: z.string().describe("Text description of the image to generate"),
+    prompt: z
+      .string()
+      .describe("Detailed text description of the image to generate."),
     aspect_ratio: z
       .string()
       .optional()
-      .describe("Aspect ratio: 1:1, 3:4, 4:3, 9:16, or 16:9 (default 9:16)"),
+      .describe(
+        "Supported ratios: 1:1, 3:4, 4:3, 9:16, or 16:9. Default is 9:16."
+      ),
     output_path: z
       .string()
       .optional()
       .describe(
-        "File path to save the generated image (optional, auto-generated if not provided)"
+        "Optional: specific local path or filename to save the image (e.g., 'outputs/hero.png'). " +
+          "If omitted, a timestamped filename is generated automatically."
       ),
     reference_images: z
       .array(z.string())
       .optional()
-      .describe("Optional reference image file paths to guide generation"),
+      .describe(
+        "Optional: local paths or URLs of images to use as visual references for style or composition."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: {
@@ -297,18 +310,33 @@ export const geminiTextToImage = {
 export const geminiEditImage = {
   name: "editImage",
   description:
-    "Edit existing images with text instructions using Gemini 3 Pro Image Preview",
+    "Modify or edit an existing image based on text instructions using Google's Imagen 3 model via Gemini. " +
+    "This can be used for inpainting (changing specific parts), style transfer, or adding/removing elements. " +
+    "Describe the desired changes relative to the source image (e.g., 'Change the white shirt to a blue one' or 'Add a cat sitting on the sofa'). " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
-    image_path: z.string().describe("Path to the source image file"),
-    prompt: z.string().describe("Text instructions for editing the image"),
+    image_path: z
+      .string()
+      .describe(
+        "Absolute local path or URL to the source image file to be edited."
+      ),
+    prompt: z
+      .string()
+      .describe(
+        "Instructional text describing the edits or modifications required."
+      ),
     output_path: z
       .string()
       .optional()
-      .describe("File path to save the edited image"),
+      .describe(
+        "Optional: specific local path to save the edited result. Defaults to generated timestamp."
+      ),
     reference_images: z
       .array(z.string())
       .optional()
-      .describe("Additional image paths for reference"),
+      .describe(
+        "Optional: additional images to guide the edit (e.g., to reference a specific character or object style)."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: {
@@ -378,12 +406,19 @@ export const geminiEditImage = {
 export const geminiAnalyzeImages = {
   name: "analyzeImages",
   description:
-    "Analyze and describe images using Gemini 2.5 Pro with advanced multimodal understanding",
+    "Perform advanced multimodal analysis on one or more images using Google's Gemini 2.5 Pro model. " +
+    "Use this for complex reasoning, visual question answering, OCR, or describing scenes in detail. " +
+    "You can compare multiple images by providing them in the array. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
     image_paths: z
       .array(z.string())
-      .describe("Array of image file paths to analyze"),
-    prompt: z.string().describe("Text prompt or question about the images"),
+      .describe(
+        "An array of absolute local file paths or publicly accessible URLs to analyze."
+      ),
+    prompt: z
+      .string()
+      .describe("The question, query, or instruction to apply to the images."),
   }),
   timeoutMs: 300000,
   execute: async (args: { image_paths: string[]; prompt: string }) => {
@@ -447,19 +482,22 @@ export const geminiAnalyzeImages = {
 export const geminiSingleSpeakerTts = {
   name: "generateSpeech",
   description:
-    "Generate single speaker voice audio from text using Gemini 2.5 Pro Preview TTS model",
+    "Convert text to natural-sounding speech using Google's Gemini 2.5 Pro Preview TTS model. " +
+    "This tool generates a single speaker's voice in a WAV format. " +
+    "Best for long-form narration or simple voiceovers. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
-    text: z.string().describe("Text to convert to speech"),
+    text: z.string().describe("The text content to be converted into speech."),
     voice_name: z
       .string()
       .describe(
-        "Voice name from supported options. Use Kore, Erinome or Despina for the female voices and Enceladus for male."
+        "Supported voices: 'Despina' (Female, versatile), 'Kore' (Female, calm), 'Erinome' (Female, expressive), or 'Enceladus' (Male, neutral)."
       ),
     output_path: z
       .string()
       .optional()
       .describe(
-        "Output WAV file path (optional, defaults to timestamp-based filename)"
+        "Optional: Output WAV file path. Defaults to a timestamped filename in the output directory."
       ),
   }),
   timeoutMs: 300000,
@@ -518,37 +556,41 @@ export const geminiSingleSpeakerTts = {
 export const geminiAnalyzeVideos = {
   name: "analyzeVideos",
   description:
-    "Analyze and understand video content using Gemini 2.5 Flash model. Intelligently handles YouTube URLs and local videos (files <20MB processed inline, ≥20MB uploaded via File API). Supports timestamp queries, clipping, and custom frame rates with default 5 FPS for local videos to optimize processing.",
+    "Comprehensive video understanding using Google's Gemini 2.5 Pro model. " +
+    "Capable of analyzing both longitudinal content (YouTube) and specific local files. " +
+    "Supports time-aware queries (e.g., 'What color is the car at 02:45?'), clipping, and advanced visual reasoning over video streams. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
     video_inputs: z
       .array(z.string())
       .describe(
-        "Array of video inputs - mix of local file paths and YouTube URLs (max 10 videos). Local files <20MB processed inline, larger files uploaded via File API automatically."
+        "An array containing absolute paths to local videos or YouTube URLs. Max 10 per request. " +
+          "Note: Local files are automatically optimized for processing."
       ),
     prompt: z
       .string()
       .describe(
-        "Text prompt or question about the videos. Use MM:SS format for timestamp references (e.g., 'What happens at 01:30?')."
+        "The question or instruction regarding the video. Use MM:SS or HH:MM:SS for precise time references."
       ),
     fps: z
       .number()
       .optional()
       .describe(
-        "Frame rate for video processing (default: 5 FPS for local videos to reduce file size, 1 FPS for YouTube URLs)"
+        "Optional: Target frames per second for processing. Lower FPS (1-5) is recommended for long videos to save tokens."
       ),
     start_offset: z
       .string()
       .optional()
-      .describe("Clip start time in seconds with 's' suffix (e.g., '40s')"),
+      .describe("Start time of the segment to analyze (e.g., '10s', '01:30')."),
     end_offset: z
       .string()
       .optional()
-      .describe("Clip end time in seconds with 's' suffix (e.g., '80s')"),
+      .describe("End time of the segment to analyze (e.g., '20s', '02:00')."),
     media_resolution: z
       .string()
       .optional()
       .describe(
-        "Media resolution: 'default' or 'low' (low resolution uses ~100 tokens/sec vs 300 tokens/sec)"
+        "Processing resolution: 'default' or 'low'. 'low' significantly reduces token usage for simple visual tasks."
       ),
   }),
   timeoutMs: 300000,

package/src/tools/image-to-video.ts

@@ -41,73 +41,88 @@ async function fileToBase64(
 export const imageToVideo = {
   name: "generateVideoi2v",
   description:
-    "Generate videos from an image as starting first frame using Vertex Veo models (predictLongRunning + fetchPredictOperation).",
+    "Generate professional-quality cinematic videos from a starting image and text prompt using Vertex AI's Veo models. " +
+    "This is a high-latency tool (often takes 5-15 minutes) but produces state-of-the-art results. " +
+    "It supports guided generation with start/end frames and specific durations. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE VERTEX AI MODELS.",
   parameters: z.object({
-    prompt: z.string().describe("Text description for the video"),
+    prompt: z
+      .string()
+      .describe(
+        "Descriptive text for the video action and style (e.g., 'A robot walking through a neon city at night')."
+      ),
     image_path: z
       .string()
       .optional()
-      .describe("Path to source image for image-to-video generation"),
+      .describe("Absolute local path or URL to the STARTING image frame."),
     last_frame_path: z
       .string()
       .optional()
-      .describe("Path to last frame image to guide ending frame (optional)"),
+      .describe(
+        "Optional: Absolute local path or URL to the ENDING image frame to guide the video's conclusion."
+      ),
     aspect_ratio: z
       .string()
       .optional()
       .default("16:9")
-      .describe("Video aspect ratio: '16:9' or '9:16'"),
+      .describe(
+        "Target aspect ratio: '16:9' (landscape) or '9:16' (vertical)."
+      ),
     duration_seconds: z
       .string()
       .optional()
       .default("6")
       .describe(
-        "Video duration in seconds. MUST be one of: '4', '6', or '8' (default: '6'). Other values will be rejected by Vertex AI."
+        "Target duration. Vertex AI ONLY supports exactly '4', '6', or '8' seconds. Other values will be rounded to the nearest supported step."
       ),
     resolution: z
       .string()
       .optional()
-      .describe("Video resolution: '720p' or '1080p' (default: '720p')"),
+      .describe("Target resolution: '720p' or '1080p'. Default is '720p'."),
     negative_prompt: z
       .string()
       .optional()
-      .describe("Text describing what not to include in the video"),
+      .describe(
+        "Visual elements or styles to EXCLUDE from the generated video."
+      ),
     person_generation: z
       .string()
       .optional()
       .describe(
-        "Controls generation of people: 'allow_adult' (default for image-to-video) or 'allow_all'"
+        "Policy for generating people: 'allow_adult' (standard) or 'allow_all'. Note: Gemini 1.5+ safety filters apply."
       ),
     reference_images: z
       .array(z.string())
       .optional()
-      .describe("Additional image paths for reference (max 3)"),
+      .describe(
+        "Optional: Additional images (up to 3) to guide style or character consistency."
+      ),
     output_path: z
       .string()
       .optional()
       .describe(
-        "Output MP4 file path (if multiple predictions, index suffix is added)"
+        "Optional: Local path to save the resulting .mp4 file. Defaults to timestamped filename."
       ),
     project_id: z
       .string()
       .optional()
       .default("mixio-pro")
-      .describe("GCP Project ID (default: mixio-pro)"),
+      .describe("GCP Project ID for Vertex billing."),
     location_id: z
       .string()
       .optional()
       .default("us-central1")
-      .describe("Vertex region (default: us-central1)"),
+      .describe("GCP region for Vertex AI processing (e.g., 'us-central1')."),
     model_id: z
       .string()
       .optional()
       .default("veo-3.1-fast-generate-001")
-      .describe("Model ID (default: veo-3.1-fast-generate-001)"),
+      .describe("Specific Vertex Veo model ID to use."),
     generate_audio: z
       .boolean()
       .optional()
       .describe(
-        "Boolean flag to enable generation of audio along with the video"
+        "If true, Vertex will attempt to synthesize synchronized audio for the video."
       )
       .default(false),
   }),

package/src/tools/perplexity.ts

@@ -4,21 +4,26 @@ import { safeToolExecute } from "../utils/tool-wrapper";
 export const perplexityImages = {
   name: "perplexityImages",
   description:
-    "Searches for images using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of image URLs with citations mapped to the text.",
+    "Search for and discover real-world images using the Perplexity Sonar API. " +
+    "This tool provides a summarized text description of findings along with a verified list of image URLs. " +
+    "Citations in the text are mapped [N] to the numbered images in the list. " +
+    "Ideal for finding visual inspiration, reference photos, or stock-like images from the web.",
   parameters: z.object({
-    query: z.string().describe("The search query for images."),
+    query: z
+      .string()
+      .describe(
+        "Descriptive search terms (e.g., 'SpaceX Starship launch photos')."
+      ),
     image_domain_filter: z
       .array(z.string())
       .optional()
       .describe(
-        "A list of domains to include or exclude. To exclude, prefix with '-'. E.g., ['wikimedia.org', '-gettyimages.com']."
+        "Filter results by domain. Use 'domain.com' to include, or '-domain.com' to exclude. (e.g., ['wikimedia.org', '-pinterest.com'])."
       ),
     image_format_filter: z
       .array(z.string())
       .optional()
-      .describe(
-        "A list of allowed image formats. E.g., ['jpg', 'png', 'gif']."
-      ),
+      .describe("Target specific formats: 'jpg', 'png', 'gif', etc."),
   }),
   timeoutMs: 300000,
   execute: async (args: {
@@ -33,28 +38,26 @@ export const perplexityImages = {
       }
 
       const url = "https://api.perplexity.ai/chat/completions";
-      const headers = {
+      const headers: Record<string, string> = {
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json",
         accept: "application/json",
       };
 
-      const payload: any = {
+      const payload = {
         model: "sonar",
         messages: [
           { role: "user", content: `Show me images of ${args.query}` },
         ],
         return_images: true,
+        ...(args.image_domain_filter
+          ? { image_domain_filter: args.image_domain_filter }
+          : {}),
+        ...(args.image_format_filter
+          ? { image_format_filter: args.image_format_filter }
+          : {}),
       };
 
-      if (args.image_domain_filter) {
-        payload.image_domain_filter = args.image_domain_filter;
-      }
-
-      if (args.image_format_filter) {
-        payload.image_format_filter = args.image_format_filter;
-      }
-
       const res = await fetch(url, {
         method: "POST",
         headers: headers,
@@ -66,51 +69,49 @@ export const perplexityImages = {
         throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
       }
 
-      const data: any = await res.json();
+      const data = (await res.json()) as any;
       let content = data.choices?.[0]?.message?.content;
-      const images = data.images;
-      const citations = data.citations;
+      const images = (data.images || []) as any[];
+      const citations = (data.citations || []) as string[];
 
-      if (!images || images.length === 0) {
+      if (images.length === 0) {
         return `No direct image URLs found in the API response. The text content was: ${content}`;
       }
 
       // Create a map of origin_url -> new 1-based index
-      const originUrlToImageIndex: { [key: string]: number } = {};
-      images.forEach((img: any, index: number) => {
+      const originUrlToImageIndex: Record<string, number> = {};
+      images.forEach((img, index) => {
         if (img.origin_url) {
           originUrlToImageIndex[img.origin_url] = index + 1;
         }
       });
 
       // Create a map of old citation index -> new image index
-      const oldToNewCitationMap: { [key: number]: number } = {};
-      if (citations && Array.isArray(citations)) {
-        citations.forEach((citationUrl: string, index: number) => {
-          if (originUrlToImageIndex[citationUrl]) {
-            oldToNewCitationMap[index + 1] = originUrlToImageIndex[citationUrl];
-          }
-        });
-      }
+      const oldToNewCitationMap: Record<number, number> = {};
+      citations.forEach((citationUrl, index) => {
+        if (originUrlToImageIndex[citationUrl]) {
+          oldToNewCitationMap[index + 1] = originUrlToImageIndex[citationUrl];
+        }
+      });
 
       // Replace citations in the content
       if (content && typeof content === "string") {
         content = content
-          .replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
+          .replace(/\[(\d+)\]/g, (_match, oldIndexStr) => {
             const oldIndex = parseInt(oldIndexStr, 10);
             const newIndex = oldToNewCitationMap[oldIndex];
             if (newIndex) {
               return `[${newIndex}]`;
             }
-            return ""; // Remove citation if it doesn't correspond to an image
+            return "";
           })
           .replace(/(\s\s+)/g, " ")
-          .trim(); // Clean up extra spaces
+          .trim();
       }
 
       // Build the final formatted output
       let output = content + "\n\n--- Images ---\n";
-      images.forEach((img: any, index: number) => {
+      images.forEach((img, index) => {
         output += `${index + 1}. ${img.image_url}\n   (Source: ${
           img.origin_url
         })\n`;
@@ -124,14 +125,16 @@ export const perplexityImages = {
 export const perplexityVideos = {
   name: "perplexityVideos",
   description:
-    "Searches for videos using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of video URLs with citations mapped to the text.",
+    "Search for web videos (e.g., from YouTube, Vimeo) using Perplexity Sonar Pro. " +
+    "Provides a textual summary of the content found and direct links to the videos. " +
+    "Perfect for finding research material or specific clips based on natural language queries.",
   parameters: z.object({
-    query: z.string().describe("The search query for videos."),
+    query: z.string().describe("The natural language search query for videos."),
     search_domain_filter: z
       .array(z.string())
       .optional()
       .describe(
-        "A list of domains to limit the search to (e.g., ['youtube.com']). Use a '-' prefix to exclude a domain."
+        "Optional: Restrict search to specific domains (e.g., ['youtube.com']) or exclude them with '-' prefix."
       ),
   }),
   timeoutMs: 300000,
@@ -143,24 +146,23 @@ export const perplexityVideos = {
       }
 
       const url = "https://api.perplexity.ai/chat/completions";
-      const headers = {
+      const headers: Record<string, string> = {
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json",
         accept: "application/json",
       };
 
-      const payload: any = {
+      const payload = {
         model: "sonar-pro",
         messages: [
           { role: "user", content: `Show me videos of ${args.query}` },
         ],
         media_response: { overrides: { return_videos: true } },
+        ...(args.search_domain_filter
+          ? { search_domain_filter: args.search_domain_filter }
+          : {}),
       };
 
-      if (args.search_domain_filter) {
-        payload.search_domain_filter = args.search_domain_filter;
-      }
-
       const res = await fetch(url, {
         method: "POST",
         headers: headers,
@@ -172,12 +174,12 @@ export const perplexityVideos = {
         throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
       }
 
-      const data: any = await res.json();
+      const data = (await res.json()) as any;
       let content = data.choices?.[0]?.message?.content;
-      const videos = data.videos;
-      const citations = data.citations;
+      const videos = (data.videos || []) as any[];
+      const citations = (data.citations || []) as string[];
 
-      if (!videos || videos.length === 0) {
+      if (videos.length === 0) {
         return `No direct video URLs found in the API response. Full API Response: ${JSON.stringify(
           data,
           null,
@@ -186,41 +188,39 @@ export const perplexityVideos = {
       }
 
       // Create a map of video url -> new 1-based index
-      const urlToVideoIndex: { [key: string]: number } = {};
-      videos.forEach((video: any, index: number) => {
+      const urlToVideoIndex: Record<string, number> = {};
+      videos.forEach((video, index) => {
         if (video.url) {
           urlToVideoIndex[video.url] = index + 1;
         }
       });
 
       // Create a map of old citation index -> new video index
-      const oldToNewCitationMap: { [key: number]: number } = {};
-      if (citations && Array.isArray(citations)) {
-        citations.forEach((citationUrl: string, index: number) => {
-          if (urlToVideoIndex[citationUrl]) {
-            oldToNewCitationMap[index + 1] = urlToVideoIndex[citationUrl];
-          }
-        });
-      }
+      const oldToNewCitationMap: Record<number, number> = {};
+      citations.forEach((citationUrl, index) => {
+        if (urlToVideoIndex[citationUrl]) {
+          oldToNewCitationMap[index + 1] = urlToVideoIndex[citationUrl];
+        }
+      });
 
       // Replace citations in the content
       if (content && typeof content === "string") {
         content = content
-          .replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
+          .replace(/\[(\d+)\]/g, (_match, oldIndexStr) => {
             const oldIndex = parseInt(oldIndexStr, 10);
             const newIndex = oldToNewCitationMap[oldIndex];
             if (newIndex) {
               return `[${newIndex}]`;
             }
-            return ""; // Remove citation if it doesn't correspond to a video
+            return "";
           })
           .replace(/(\s\s+)/g, " ")
-          .trim(); // Clean up extra spaces
+          .trim();
       }
 
       // Build the final formatted output
       let output = content + "\n\n--- Videos ---\n";
-      videos.forEach((video: any, index: number) => {
+      videos.forEach((video, index) => {
         output += `${index + 1}. ${video.url}\n`;
       });
 

package/src/tools/youtube.ts

@@ -9,16 +9,21 @@ const ai = new GoogleGenAI({
 export const analyzeYoutubeVideo = {
   name: "analyzeYoutubeVideo",
   description:
-    "Analyze YouTube videos for content using the correct GenAI JS API approach with FileData fileUri. Perfect for extracting stock media content, analyzing video content, or getting descriptions of YouTube videos",
+    "Perform deep semantic analysis of a YouTube video using Google's Gemini 2.5 Flash model. " +
+    "Use this to summarize long videos, identify specific scenes, extract information, or ask visual questions about the video's content. " +
+    "This tool treats the YouTube URL as a first-class video stream for the model. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
     youtube_url: z
       .string()
       .describe(
-        "YouTube video URL to analyze (format: https://www.youtube.com/watch?v=VIDEO_ID)"
+        "The full URL of the YouTube video (e.g., 'https://www.youtube.com/watch?v=dQw4w9WgXcQ')."
       ),
     prompt: z
       .string()
-      .describe("Analysis prompt or question about the YouTube video content"),
+      .describe(
+        "Instruction or question about the video content (e.g., 'Summarize the main points' or 'What color was the car?')."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: { youtube_url: string; prompt: string }) => {