Creative Specifications

Instructions

Implementation Reference

• src/index.ts:496-517 (handler)

  Tool handler for 'creative_specs' — receives platform and optional format, calls getCreativeSpecs() and returns the specs as JSON.

  // ── Tool 10: creative_specs ─────────────────────────────────────────
  
  server.registerTool(
    'creative_specs',
    {
      title: 'Creative Specifications',
      description: 'Platform-specific creative requirements for ad formats. Returns the exact image dimensions, aspect ratios, video duration and codec, headline/primary-text character limits, supported CTA buttons, and file size ceilings for each ad format. Input: platform ("google_ads"|"meta_ads") and optional format filter (e.g. "responsive_display", "video", "carousel", "single_image"). Use this before building creatives to avoid rejection at upload time.',
      inputSchema: CreativeSpecsInputSchema,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async ({ platform, format }) => {
      try {
        const specs = getCreativeSpecs(platform, format);
        return { content: [{ type: 'text' as const, text: JSON.stringify({
          platform,
          format_filter: format ?? 'all',
          specs_count: specs.length,
          specs,
        }, null, 2) }] };
      } catch (e) { return handleToolError(e); }
    },
  );

• src/models/adops.ts:463-466 (schema)

  Input schema (CreativeSpecsInputSchema) for the creative_specs tool — validates platform and optional format filter.

  export const CreativeSpecsInputSchema = z.object({
    platform: PlatformSchema.describe('Platform to get specs for'),
    format: z.enum(['image', 'video', 'carousel', 'stories']).optional(),
  });

• src/models/adops.ts:319-343 (schema)

  Type definition (CreativeSpecSchema) describing the shape of creative specification data — image_specs, video_specs, text_specs.

  export const CreativeSpecSchema = z.object({
    platform: PlatformSchema,
    format: z.string(),
    placement: z.string(),
    image_specs: z.object({
      width: z.number().int(),
      height: z.number().int(),
      aspect_ratio: z.string(),
      max_file_size_mb: z.number(),
      formats: z.array(z.string()),
    }).nullable(),
    video_specs: z.object({
      min_duration_sec: z.number(),
      max_duration_sec: z.number(),
      aspect_ratios: z.array(z.string()),
      max_file_size_mb: z.number(),
      formats: z.array(z.string()),
    }).nullable(),
    text_specs: z.object({
      headline_max_chars: z.number().int(),
      description_max_chars: z.number().int(),
      cta_options: z.array(z.string()),
    }),
  });
  export type CreativeSpec = z.infer<typeof CreativeSpecSchema>;

• src/services/creative-specs.ts:37-49 (helper)

  Helper functions getCreativeSpecs() and getAllCreativeSpecs() that filter the hardcoded CREATIVE_SPECS array by platform and optional format.

  /** Get platform-specific creative specifications filtered by platform and optional format. Returns image sizes, video specs, text limits, and CTA options. */
  export function getCreativeSpecs(platform: Platform, format?: string): CreativeSpec[] {
    let specs = CREATIVE_SPECS.filter((s) => s.platform === platform);
    if (format) {
      specs = specs.filter((s) => s.format.toLowerCase().includes(format.toLowerCase()));
    }
    return specs;
  }
  
  /** Get all creative specifications across all platforms and formats. */
  export function getAllCreativeSpecs(): CreativeSpec[] {
    return CREATIVE_SPECS;
  }

• src/index.ts:751-751 (registration)

  Tool registration entry in the server card's tool list for the 'creative_specs' tool.

  { name: 'creative_specs', description: 'Platform creative requirements' },