[ { "name": "meta_ads_get_account_summary", "title": "Get Meta Ads Account Summary", "description": "Standardized account-level performance summary for cross-platform comparison. Normalized format identical to google_ads_get_account_summary. Includes conversion_detail breakdown from both Meta actions and conversions arrays. Preferred over get_insights or get_performance_report for quick account-level overviews. Always fetches fresh data.", "cli_command": "hopkin meta account-summary get", "cli_flags": [ { "flag": "--account", "description": "Meta ad account ID", "type": "string", "required": true }, { "flag": "--date-preset", "description": "Predefined date range (e.g., last_7d, last_30d, this_month)", "type": "string", "required": false }, { "flag": "--time-range", "description": "Custom date range {since, until} in YYYY-MM-DD", "type": "object", "required": false } ], "category": "account-summary", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "date_preset": { "type": "string", "enum": [ "today", "yesterday", "this_week_mon_today", "this_week_sun_today", "last_week_mon_sun", "last_week_sun_sat", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "lifetime", "maximum" ], "description": "Predefined date range (e.g., last_7d, last_30d, this_month)" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Custom date range {since, until} in YYYY-MM-DD" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Meta ad account ID", "constraints": { "min_length": 1 } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range (e.g., last_7d, last_30d, this_month)", "enum_values": [ "today", "yesterday", "this_week_mon_today", "this_week_sun_today", "last_week_mon_sun", "last_week_sun_sat", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "lifetime", "maximum" ] }, { "name": "time_range", "type": "object", "required": false, "description": "Custom date range {since, until} in YYYY-MM-DD" }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Last 30 days summary", "mcp_params": { "account_id": "act_123", "reason": "Quick performance overview" }, "cli_command": "hopkin meta account-summary get --account act_123", "natural_language": "Last 30 days summary" }, { "label": "Last 7 days", "mcp_params": { "account_id": "act_123", "date_preset": "last_7d", "reason": "Weekly check-in" }, "cli_command": "hopkin meta account-summary get --account act_123 --date-preset last_7d", "natural_language": "Last 7 days" }, { "label": "Custom date range", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2026-01-01", "until": "2026-01-31" }, "reason": "January performance review" }, "cli_command": "hopkin meta account-summary get --account act_123 --time-range [object Object]", "natural_language": "Custom date range" } ], "response_format": "markdown", "related_tools": [ { "name": "google_ads_get_account_summary", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_account_summary", "relationship": "cross-platform" }, { "name": "reddit_ads_get_account_summary", "relationship": "cross-platform" } ] }, { "name": "meta_ads_get_activities", "title": "Get Meta Ads Activities", "description": "Retrieve activity/change history for a Meta ad account or specific entity. Cached with 1-hour TTL; use refresh=true for fresh data. Meta's API only returns the last 7 days per call, but cached data accumulates for historical lookups.", "cli_command": "hopkin meta activities get", "cli_flags": [ { "flag": "--account", "description": "The ad account ID (with or without act_ prefix)", "type": "string", "required": true }, { "flag": "--entity-id", "description": "Filter activities to a specific entity (campaign, ad set, or ad ID). If omitted, returns account-level activities.", "type": "string", "required": false }, { "flag": "--entity-type", "description": "Type of entity: ACCOUNT, CAMPAIGN, AD_SET, AD. Used with entity_id for filtering.", "type": "string", "required": false }, { "flag": "--start-date", "description": "Start date for activity range (ISO 8601, e.g. 2024-01-01)", "type": "string", "required": false }, { "flag": "--end-date", "description": "End date for activity range (ISO 8601, e.g. 2024-01-31)", "type": "string", "required": false }, { "flag": "--limit", "description": "Number of activities per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force fresh activity data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "type": "boolean", "required": false } ], "category": "activities", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "entity_id": { "type": "string", "minLength": 1, "description": "Filter activities to a specific entity (campaign, ad set, or ad ID). If omitted, returns account-level activities." }, "entity_type": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_SET", "AD" ], "description": "Type of entity: ACCOUNT, CAMPAIGN, AD_SET, AD. Used with entity_id for filtering." }, "start_date": { "type": "string", "description": "Start date for activity range (ISO 8601, e.g. 2024-01-01)" }, "end_date": { "type": "string", "description": "End date for activity range (ISO 8601, e.g. 2024-01-31)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of activities per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh activity data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "The ad account ID (with or without act_ prefix)", "constraints": { "min_length": 1 } }, { "name": "entity_id", "type": "string", "required": false, "description": "Filter activities to a specific entity (campaign, ad set, or ad ID). If omitted, returns account-level activities.", "constraints": { "min_length": 1 } }, { "name": "entity_type", "type": "string", "required": false, "description": "Type of entity: ACCOUNT, CAMPAIGN, AD_SET, AD. Used with entity_id for filtering.", "enum_values": [ "ACCOUNT", "CAMPAIGN", "AD_SET", "AD" ] }, { "name": "start_date", "type": "string", "required": false, "description": "Start date for activity range (ISO 8601, e.g. 2024-01-01)" }, { "name": "end_date", "type": "string", "required": false, "description": "End date for activity range (ISO 8601, e.g. 2024-01-31)" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of activities per page (default: 20, max: 100)", "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from previous response", "constraints": { "min_length": 1 } }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force fresh activity data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Account activities", "mcp_params": { "account_id": "123456789", "reason": "View recent account changes" }, "cli_command": "hopkin meta activities get --account 123456789", "natural_language": "Account activities" }, { "label": "Campaign history", "mcp_params": { "account_id": "123456789", "entity_id": "23842453456789", "entity_type": "CAMPAIGN", "reason": "View campaign change history" }, "cli_command": "hopkin meta activities get --account 123456789 --entity-id 23842453456789 --entity-type CAMPAIGN", "natural_language": "Campaign history" }, { "label": "Date range", "mcp_params": { "account_id": "123456789", "start_date": "2024-01-01", "end_date": "2024-01-31", "reason": "January activity" }, "cli_command": "hopkin meta activities get --account 123456789 --start-date 2024-01-01 --end-date 2024-01-31", "natural_language": "Date range" } ], "response_format": "markdown", "related_tools": [ { "name": "google_ads_get_activities", "relationship": "cross-platform" } ] }, { "name": "meta_ads_list_ad_accounts", "title": "List Meta Ad Accounts", "description": "List Meta ad accounts with search, status filtering, single/multi-account lookup by ID, and pagination. Cached by default; pass refresh=true for latest data. Entities may include _stored_preferences and optionally recent activities.", "cli_command": "hopkin meta ad-accounts list", "cli_flags": [ { "flag": "--refresh", "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "type": "boolean", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false }, { "flag": "--search", "description": "Search ad accounts by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--account", "description": "Filter by exact account ID (without act_ prefix)", "type": "string", "required": false }, { "flag": "--account-ids", "description": "Get multiple accounts by ID. Mutually exclusive with account_id. When provided, ignores other filters/pagination.", "type": "array", "required": false }, { "flag": "--status", "description": "Account status code (1=Active, 2=Disabled, etc.)", "type": "integer", "required": false }, { "flag": "--limit", "description": "Number of accounts per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--include-activities", "description": "Include recent activity log (last 7 days of changes) for each entity", "type": "boolean", "required": false } ], "category": "ad-accounts", "annotations": { "readOnly": true, "destructive": false, "idempotent": false, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "search": { "type": "string", "minLength": 1, "description": "Search ad accounts by name (case-insensitive partial match)" }, "account_id": { "type": "string", "minLength": 1, "description": "Filter by exact account ID (without act_ prefix)" }, "account_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple accounts by ID. Mutually exclusive with account_id. When provided, ignores other filters/pagination." }, "status": { "type": "integer", "description": "Account status code (1=Active, 2=Disabled, etc.)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of accounts per page (default: 20, max: 100)" }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "refresh", "type": "boolean", "required": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "default": false }, { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from previous response", "constraints": { "min_length": 1 } }, { "name": "search", "type": "string", "required": false, "description": "Search ad accounts by name (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "account_id", "type": "string", "required": false, "description": "Filter by exact account ID (without act_ prefix)", "constraints": { "min_length": 1 } }, { "name": "account_ids", "type": "array", "required": false, "description": "Get multiple accounts by ID. Mutually exclusive with account_id. When provided, ignores other filters/pagination." }, { "name": "status", "type": "integer", "required": false, "description": "Account status code (1=Active, 2=Disabled, etc.)" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of accounts per page (default: 20, max: 100)", "constraints": { "min": 1, "max": 100 } }, { "name": "include_activities", "type": "boolean", "required": false, "description": "Include recent activity log (last 7 days of changes) for each entity", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "List all", "mcp_params": { "reason": "List all ad accounts" }, "cli_command": "hopkin meta ad-accounts list", "natural_language": "List all" }, { "label": "Search by name", "mcp_params": { "search": "marketing", "reason": "Find marketing accounts" }, "cli_command": "hopkin meta ad-accounts list --search marketing", "natural_language": "Search by name" }, { "label": "Filter by status", "mcp_params": { "status": 1, "reason": "List active accounts" }, "cli_command": "hopkin meta ad-accounts list --status 1", "natural_language": "Filter by status" }, { "label": "Get by ID", "mcp_params": { "account_id": "123456789", "reason": "Get specific account" }, "cli_command": "hopkin meta ad-accounts list --account 123456789", "natural_language": "Get by ID" }, { "label": "Get multiple by IDs", "mcp_params": { "account_ids": [ "123456789", "987654321" ], "reason": "Get specific accounts" }, "cli_command": "hopkin meta ad-accounts list --account-ids 123456789,987654321", "natural_language": "Get multiple by IDs" }, { "label": "Force refresh", "mcp_params": { "refresh": true, "reason": "Get fresh data from Meta API" }, "cli_command": "hopkin meta ad-accounts list --refresh true", "natural_language": "Force refresh" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_campaigns", "relationship": "hierarchy" }, { "name": "linkedin_ads_list_ad_accounts", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ad_accounts", "relationship": "cross-platform" } ] }, { "name": "meta_ads_get_ad_creative_report", "title": "Get Meta Ads Creative Performance Report", "description": "Ad-level performance report with full funnel metrics. All conversion types shown individually. Supports two grouping modes: ad_name (default, aggregates ads sharing the same name with a representative ad_id for preview) and ad_id (one row per ad). The representative ad_id can be passed to meta_ads_preview_ads. Always fetches fresh data.", "cli_command": "hopkin meta ad-creative-report get", "cli_flags": [ { "flag": "--account", "description": "Meta ad account ID", "type": "string", "required": true }, { "flag": "--time-range", "description": "Required date range {since, until} in YYYY-MM-DD", "type": "object", "required": true }, { "flag": "--level", "description": "Grouping level: ad_name (default, aggregate ads sharing the same name, providing a representative ad_id that can be passed to meta_ads_preview_ads) or ad_id (one row per ad)", "type": "string", "required": false }, { "flag": "--time-increment", "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"", "type": "unknown", "required": false }, { "flag": "--breakdowns", "description": "Segment by dimension. Pass multiple values for cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma", "type": "array", "required": false }, { "flag": "--filtering", "description": "Filters as [{field, operator, value}]", "type": "array", "required": false } ], "category": "reporting", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Required date range {since, until} in YYYY-MM-DD" }, "level": { "type": "string", "enum": [ "ad_id", "ad_name" ], "default": "ad_name", "description": "Grouping level: ad_name (default, aggregate ads sharing the same name, providing a representative ad_id that can be passed to meta_ads_preview_ads) or ad_id (one row per ad)" }, "time_increment": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "string", "const": "monthly" }, { "type": "string", "const": "all_days" } ], "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, "breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "age", "gender", "country", "region", "device_platform", "publisher_platform", "platform_position", "impression_device", "dma" ] }, "description": "Segment by dimension. Pass multiple values for cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma" }, "filtering": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Field to filter on" }, "operator": { "type": "string", "enum": [ "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "IN", "NOT_IN", "CONTAIN", "NOT_CONTAIN" ], "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) to compare against — numbers are coerced to strings automatically" } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "description": "Filters as [{field, operator, value}]" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "time_range", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Meta ad account ID", "constraints": { "min_length": 1 } }, { "name": "time_range", "type": "object", "required": true, "description": "Required date range {since, until} in YYYY-MM-DD" }, { "name": "level", "type": "string", "required": false, "description": "Grouping level: ad_name (default, aggregate ads sharing the same name, providing a representative ad_id that can be passed to meta_ads_preview_ads) or ad_id (one row per ad)", "enum_values": [ "ad_id", "ad_name" ], "default": "ad_name" }, { "name": "time_increment", "type": "unknown", "required": false, "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, { "name": "breakdowns", "type": "array", "required": false, "description": "Segment by dimension. Pass multiple values for cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma" }, { "name": "filtering", "type": "array", "required": false, "description": "Filters as [{field, operator, value}]" }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "All ads by ID", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "reason": "Review individual ad performance" }, "cli_command": "hopkin meta ad-creative-report get --account act_123 --time-range [object Object]", "natural_language": "All ads by ID" }, { "label": "Aggregate by creative name", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "reason": "Compare creative variants running across multiple ad sets" }, "cli_command": "hopkin meta ad-creative-report get --account act_123 --time-range [object Object] --level ad_name", "natural_language": "Aggregate by creative name" }, { "label": "Filter by campaign", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "filtering": [ { "field": "campaign.id", "operator": "IN", "value": [ "111111111" ] } ], "reason": "Creative performance within a specific campaign" }, "cli_command": "hopkin meta ad-creative-report get --account act_123 --time-range [object Object] --level ad_name --filtering [object Object]", "natural_language": "Filter by campaign" }, { "label": "Creative names by demographics", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "breakdowns": [ "age", "gender" ], "reason": "Understand which creatives perform best per demographic" }, "cli_command": "hopkin meta ad-creative-report get --account act_123 --time-range [object Object] --level ad_name --breakdowns age,gender", "natural_language": "Creative names by demographics" } ], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_performance_report", "relationship": "sibling" } ] }, { "name": "meta_ads_list_ads", "title": "List Meta Ads", "description": "List ads for a Meta ad account with ad set filtering, status, name search, single/multi-ad lookup by ID, and pagination. Each ad includes a Landing URL when available (extracted from object_story_spec, link_url, or asset_feed_spec depending on ad format). A \"Landing Page URLs\" summary section at the end of the response lists all unique destination URLs found — use this to quickly answer landing page questions without reading every ad. Set include_assets=true to include resolved creative media URLs (adds latency for cache misses). Entities may include _stored_preferences and optionally recent activities.", "cli_command": "hopkin meta ads list", "cli_flags": [ { "flag": "--account", "description": "The ad account ID (with or without act_ prefix)", "type": "string", "required": true }, { "flag": "--ad", "description": "Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.", "type": "string", "required": false }, { "flag": "--ad-ids", "description": "Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination.", "type": "array", "required": false }, { "flag": "--adset", "description": "Filter by ad set ID", "type": "string", "required": false }, { "flag": "--search", "description": "Search ads by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by ad status: ACTIVE, PAUSED, DELETED, ARCHIVED", "type": "array", "required": false }, { "flag": "--limit", "description": "Number of ads per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "type": "boolean", "required": false }, { "flag": "--include-activities", "description": "Include recent activity log (last 7 days of changes) for each entity", "type": "boolean", "required": false }, { "flag": "--include-assets", "description": "Include resolved creative asset URLs (asset_url, thumbnail_url, asset_type) for each ad. Uses cached GCS URLs when available.", "type": "boolean", "required": false } ], "category": "ads", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "ad_id": { "type": "string", "minLength": 1, "description": "Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination." }, "ad_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination." }, "adset_id": { "type": "string", "minLength": 1, "description": "Filter by ad set ID" }, "search": { "type": "string", "minLength": 1, "description": "Search ads by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED" ] }, "description": "Filter by ad status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ads per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "include_assets": { "type": "boolean", "default": false, "description": "Include resolved creative asset URLs (asset_url, thumbnail_url, asset_type) for each ad. Uses cached GCS URLs when available." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "The ad account ID (with or without act_ prefix)", "constraints": { "min_length": 1 } }, { "name": "ad_id", "type": "string", "required": false, "description": "Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.", "constraints": { "min_length": 1 } }, { "name": "ad_ids", "type": "array", "required": false, "description": "Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination." }, { "name": "adset_id", "type": "string", "required": false, "description": "Filter by ad set ID", "constraints": { "min_length": 1 } }, { "name": "search", "type": "string", "required": false, "description": "Search ads by name (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "status", "type": "array", "required": false, "description": "Filter by ad status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of ads per page (default: 20, max: 100)", "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from previous response", "constraints": { "min_length": 1 } }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "default": false }, { "name": "include_activities", "type": "boolean", "required": false, "description": "Include recent activity log (last 7 days of changes) for each entity", "default": false }, { "name": "include_assets", "type": "boolean", "required": false, "description": "Include resolved creative asset URLs (asset_url, thumbnail_url, asset_type) for each ad. Uses cached GCS URLs when available.", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "List all", "mcp_params": { "account_id": "123456789", "reason": "List ads" }, "cli_command": "hopkin meta ads list --account 123456789", "natural_language": "List all" }, { "label": "Filter by ad set", "mcp_params": { "account_id": "123456789", "adset_id": "23842453456789", "reason": "List ads in ad set" }, "cli_command": "hopkin meta ads list --account 123456789 --adset 23842453456789", "natural_language": "Filter by ad set" }, { "label": "Filter by status", "mcp_params": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "List active/paused ads" }, "cli_command": "hopkin meta ads list --account 123456789 --status ACTIVE,PAUSED", "natural_language": "Filter by status" }, { "label": "Get by ID", "mcp_params": { "account_id": "123456789", "ad_id": "23842453456789", "reason": "Get specific ad" }, "cli_command": "hopkin meta ads list --account 123456789 --ad 23842453456789", "natural_language": "Get by ID" }, { "label": "Get multiple by IDs", "mcp_params": { "account_id": "123456789", "ad_ids": [ "23842453456789", "23842453456790" ], "reason": "Get specific ads" }, "cli_command": "hopkin meta ads list --account 123456789 --ad-ids 23842453456789,23842453456790", "natural_language": "Get multiple by IDs" }, { "label": "Search by name", "mcp_params": { "account_id": "123456789", "search": "Summer", "reason": "Find summer ads" }, "cli_command": "hopkin meta ads list --account 123456789 --search Summer", "natural_language": "Search by name" }, { "label": "With asset URLs", "mcp_params": { "account_id": "123456789", "include_assets": true, "reason": "List ads with creative assets" }, "cli_command": "hopkin meta ads list --account 123456789 --include-assets true", "natural_language": "With asset URLs" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_adsets", "relationship": "hierarchy" }, { "name": "google_ads_list_ads", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ads", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_ads", "relationship": "cross-platform" } ] }, { "name": "meta_ads_list_adsets", "title": "List Meta Ad Sets", "description": "List ad sets for a Meta ad account with campaign filtering, status, name search, single/multi-adset lookup by ID, and pagination. Entities may include _stored_preferences and optionally recent activities.", "cli_command": "hopkin meta adsets list", "cli_flags": [ { "flag": "--account", "description": "The ad account ID (with or without act_ prefix)", "type": "string", "required": true }, { "flag": "--adset", "description": "Get a specific ad set by ID. When provided, returns only that ad set and ignores other filters/pagination.", "type": "string", "required": false }, { "flag": "--adset-ids", "description": "Get multiple ad sets by ID. Mutually exclusive with adset_id. When provided, ignores other filters/pagination.", "type": "array", "required": false }, { "flag": "--campaign", "description": "Filter by campaign ID", "type": "string", "required": false }, { "flag": "--search", "description": "Search ad sets by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by ad set status: ACTIVE, PAUSED, DELETED, ARCHIVED", "type": "array", "required": false }, { "flag": "--limit", "description": "Number of ad sets per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "type": "boolean", "required": false }, { "flag": "--include-activities", "description": "Include recent activity log (last 7 days of changes) for each entity", "type": "boolean", "required": false } ], "category": "adsets", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "adset_id": { "type": "string", "minLength": 1, "description": "Get a specific ad set by ID. When provided, returns only that ad set and ignores other filters/pagination." }, "adset_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple ad sets by ID. Mutually exclusive with adset_id. When provided, ignores other filters/pagination." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Filter by campaign ID" }, "search": { "type": "string", "minLength": 1, "description": "Search ad sets by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED" ] }, "description": "Filter by ad set status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ad sets per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "The ad account ID (with or without act_ prefix)", "constraints": { "min_length": 1 } }, { "name": "adset_id", "type": "string", "required": false, "description": "Get a specific ad set by ID. When provided, returns only that ad set and ignores other filters/pagination.", "constraints": { "min_length": 1 } }, { "name": "adset_ids", "type": "array", "required": false, "description": "Get multiple ad sets by ID. Mutually exclusive with adset_id. When provided, ignores other filters/pagination." }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter by campaign ID", "constraints": { "min_length": 1 } }, { "name": "search", "type": "string", "required": false, "description": "Search ad sets by name (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "status", "type": "array", "required": false, "description": "Filter by ad set status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of ad sets per page (default: 20, max: 100)", "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from previous response", "constraints": { "min_length": 1 } }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "default": false }, { "name": "include_activities", "type": "boolean", "required": false, "description": "Include recent activity log (last 7 days of changes) for each entity", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "List all", "mcp_params": { "account_id": "123456789", "reason": "List ad sets" }, "cli_command": "hopkin meta adsets list --account 123456789", "natural_language": "List all" }, { "label": "Filter by campaign", "mcp_params": { "account_id": "123456789", "campaign_id": "23842453456789", "reason": "List ad sets in campaign" }, "cli_command": "hopkin meta adsets list --account 123456789 --campaign 23842453456789", "natural_language": "Filter by campaign" }, { "label": "Filter by status", "mcp_params": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "List active/paused ad sets" }, "cli_command": "hopkin meta adsets list --account 123456789 --status ACTIVE,PAUSED", "natural_language": "Filter by status" }, { "label": "Get by ID", "mcp_params": { "account_id": "123456789", "adset_id": "23842453456789", "reason": "Get specific ad set" }, "cli_command": "hopkin meta adsets list --account 123456789 --adset 23842453456789", "natural_language": "Get by ID" }, { "label": "Get multiple by IDs", "mcp_params": { "account_id": "123456789", "adset_ids": [ "23842453456789", "23842453456790" ], "reason": "Get specific ad sets" }, "cli_command": "hopkin meta adsets list --account 123456789 --adset-ids 23842453456789,23842453456790", "natural_language": "Get multiple by IDs" }, { "label": "Search by name", "mcp_params": { "account_id": "123456789", "search": "Retargeting", "reason": "Find retargeting ad sets" }, "cli_command": "hopkin meta adsets list --account 123456789 --search Retargeting", "natural_language": "Search by name" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ads", "relationship": "hierarchy" }, { "name": "meta_ads_list_campaigns", "relationship": "hierarchy" } ] }, { "name": "meta_ads_check_auth_status", "title": "Check Meta Ads Authentication Status", "description": "Troubleshoot authentication issues and get user profile info. Only use this tool when another tool fails with a permission or authentication error — do NOT call proactively.", "cli_command": "hopkin meta auth check", "cli_flags": [], "category": "auth", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Check auth", "mcp_params": { "reason": "Another tool returned an auth error, checking account connection status" }, "cli_command": "hopkin meta auth check", "natural_language": "Check auth" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_ping", "relationship": "sibling" }, { "name": "google_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "linkedin_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "reddit_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "tiktok_ads_check_auth_status", "relationship": "cross-platform" } ] }, { "name": "meta_ads_list_campaigns", "title": "List Meta Ad Campaigns", "description": "List campaigns for a Meta ad account with status filtering, name search, single/multi-campaign lookup by ID, and pagination. Entities may include _stored_preferences and optionally recent activities.", "cli_command": "hopkin meta campaigns list", "cli_flags": [ { "flag": "--account", "description": "The ad account ID (with or without act_ prefix)", "type": "string", "required": true }, { "flag": "--status", "description": "Filter by campaign status: ACTIVE, PAUSED, DELETED, ARCHIVED", "type": "array", "required": false }, { "flag": "--limit", "description": "Number of campaigns per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "type": "boolean", "required": false }, { "flag": "--campaign", "description": "Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination.", "type": "string", "required": false }, { "flag": "--campaign-ids", "description": "Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination.", "type": "array", "required": false }, { "flag": "--search", "description": "Search campaigns by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--include-activities", "description": "Include recent activity log (last 7 days of changes) for each entity", "type": "boolean", "required": false } ], "category": "campaigns", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED" ] }, "description": "Filter by campaign status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of campaigns per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination." }, "campaign_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search campaigns by name (case-insensitive partial match)" }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "The ad account ID (with or without act_ prefix)", "constraints": { "min_length": 1 } }, { "name": "status", "type": "array", "required": false, "description": "Filter by campaign status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of campaigns per page (default: 20, max: 100)", "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from previous response", "constraints": { "min_length": 1 } }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.", "default": false }, { "name": "campaign_id", "type": "string", "required": false, "description": "Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination.", "constraints": { "min_length": 1 } }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination." }, { "name": "search", "type": "string", "required": false, "description": "Search campaigns by name (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "include_activities", "type": "boolean", "required": false, "description": "Include recent activity log (last 7 days of changes) for each entity", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "List all", "mcp_params": { "account_id": "123456789", "reason": "List campaigns" }, "cli_command": "hopkin meta campaigns list --account 123456789", "natural_language": "List all" }, { "label": "Filter by status", "mcp_params": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "List active/paused campaigns" }, "cli_command": "hopkin meta campaigns list --account 123456789 --status ACTIVE,PAUSED", "natural_language": "Filter by status" }, { "label": "Get by ID", "mcp_params": { "account_id": "123456789", "campaign_id": "23842453456789", "reason": "Get specific campaign" }, "cli_command": "hopkin meta campaigns list --account 123456789 --campaign 23842453456789", "natural_language": "Get by ID" }, { "label": "Get multiple by IDs", "mcp_params": { "account_id": "123456789", "campaign_ids": [ "23842453456789", "23842453456790" ], "reason": "Get specific campaigns" }, "cli_command": "hopkin meta campaigns list --account 123456789 --campaign-ids 23842453456789,23842453456790", "natural_language": "Get multiple by IDs" }, { "label": "Search by name", "mcp_params": { "account_id": "123456789", "search": "Summer", "reason": "Find summer campaigns" }, "cli_command": "hopkin meta campaigns list --account 123456789 --search Summer", "natural_language": "Search by name" }, { "label": "Paginate", "mcp_params": { "account_id": "123456789", "limit": 10, "reason": "First page of campaigns" }, "cli_command": "hopkin meta campaigns list --account 123456789 --limit 10", "natural_language": "Paginate" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ad_accounts", "relationship": "hierarchy" }, { "name": "meta_ads_list_adsets", "relationship": "hierarchy" }, { "name": "google_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "linkedin_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "reddit_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_campaigns", "relationship": "cross-platform" } ] }, { "name": "meta_ads_developer_feedback", "title": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues like auth or API errors.", "cli_command": "hopkin meta developer-feedback send", "cli_flags": [ { "flag": "--feedback-type", "description": "Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)", "type": "string", "required": true }, { "flag": "--title", "description": "Concise title summarizing the feedback", "type": "string", "required": true }, { "flag": "--description", "description": "What is needed and why", "type": "string", "required": true }, { "flag": "--current-workaround", "description": "Current workaround, if any", "type": "string", "required": false }, { "flag": "--priority", "description": "Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)", "type": "string", "required": false }, { "flag": "--interface", "description": "Interface the feedback originated from: MCP (default) or CLI", "type": "string", "required": false } ], "category": "feedback", "annotations": { "readOnly": false, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "feedback_type": { "type": "string", "enum": [ "new_tool", "improvement", "bug", "workflow_gap" ], "description": "Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)" }, "title": { "type": "string", "minLength": 5, "maxLength": 200, "description": "Concise title summarizing the feedback" }, "description": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "What is needed and why" }, "current_workaround": { "type": "string", "maxLength": 1000, "description": "Current workaround, if any" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)" }, "interface": { "type": "string", "enum": [ "MCP", "CLI" ], "default": "MCP", "description": "Interface the feedback originated from: MCP (default) or CLI" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "feedback_type", "title", "description", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "feedback_type", "type": "string", "required": true, "description": "Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)", "enum_values": [ "new_tool", "improvement", "bug", "workflow_gap" ] }, { "name": "title", "type": "string", "required": true, "description": "Concise title summarizing the feedback", "constraints": { "min_length": 5, "max_length": 200 } }, { "name": "description", "type": "string", "required": true, "description": "What is needed and why", "constraints": { "min_length": 20, "max_length": 2000 } }, { "name": "current_workaround", "type": "string", "required": false, "description": "Current workaround, if any", "constraints": { "max_length": 1000 } }, { "name": "priority", "type": "string", "required": false, "description": "Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)", "enum_values": [ "low", "medium", "high" ], "default": "medium" }, { "name": "interface", "type": "string", "required": false, "description": "Interface the feedback originated from: MCP (default) or CLI", "enum_values": [ "MCP", "CLI" ], "default": "MCP" }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Missing tool", "mcp_params": { "feedback_type": "new_tool", "title": "Bulk campaign status toggle", "description": "Need to pause/enable multiple campaigns at once", "priority": "high", "reason": "User asked to pause 12 campaigns individually" }, "cli_command": "hopkin meta developer-feedback send --feedback-type new_tool --title Bulk campaign status toggle --description Need to pause/enable multiple campaigns at once --priority high", "natural_language": "Missing tool" }, { "label": "Workflow gap", "mcp_params": { "feedback_type": "workflow_gap", "title": "Campaign cloning with hierarchy", "description": "No way to duplicate a campaign including adsets and ads", "current_workaround": "Read and recreate each level one by one", "reason": "User wanted to duplicate campaign structure" }, "cli_command": "hopkin meta developer-feedback send --feedback-type workflow_gap --title Campaign cloning with hierarchy --description No way to duplicate a campaign including adsets and ads --current-workaround Read and recreate each level one by one", "natural_language": "Workflow gap" } ], "response_format": "markdown", "related_tools": [ { "name": "google_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "linkedin_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "reddit_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "tiktok_ads_developer_feedback", "relationship": "cross-platform" } ] }, { "name": "meta_ads_get_insights", "title": "Get Meta Ads Insights", "description": "Retrieve performance metrics from Meta Ads with date presets/custom ranges, time grouping, entity-level aggregation, dimensional breakdowns, and filtering. Always fetches fresh data. Provide date_preset or time_range. For standard full-funnel analysis, prefer meta_ads_get_performance_report; use this for custom fields, hourly/creative-asset breakdowns, or video metrics.", "cli_command": "hopkin meta insights get", "cli_flags": [ { "flag": "--account", "description": "Meta ad account ID", "type": "string", "required": true }, { "flag": "--date-preset", "description": "Predefined date range: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_quarter, last_quarter, this_year, last_year, lifetime, maximum", "type": "string", "required": false }, { "flag": "--time-range", "description": "Custom date range {since, until} in YYYY-MM-DD", "type": "object", "required": false }, { "flag": "--time-increment", "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"", "type": "unknown", "required": false }, { "flag": "--level", "description": "Aggregation level: account, campaign, adset, ad", "type": "string", "required": false }, { "flag": "--fields", "description": "Metrics to retrieve (defaults to standard set)", "type": "array", "required": false }, { "flag": "--breakdowns", "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, dma, device_platform, publisher_platform, platform_position, impression_device, frequency_value, place_page_id, product_id, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset", "type": "array", "required": false }, { "flag": "--action-breakdowns", "description": "Action breakdown dimensions: action_type, action_target_id, action_destination, action_reaction, action_video_sound, action_video_type, action_carousel_card_id, action_carousel_card_name", "type": "array", "required": false }, { "flag": "--filtering", "description": "Filters as [{field, operator, value}]", "type": "array", "required": false }, { "flag": "--action-attribution-windows", "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default", "type": "array", "required": false } ], "category": "insights", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "date_preset": { "type": "string", "enum": [ "today", "yesterday", "this_week_mon_today", "this_week_sun_today", "last_week_mon_sun", "last_week_sun_sat", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "lifetime", "maximum" ], "description": "Predefined date range: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_quarter, last_quarter, this_year, last_year, lifetime, maximum" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Custom date range {since, until} in YYYY-MM-DD" }, "time_increment": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "string", "const": "monthly" }, { "type": "string", "const": "all_days" } ], "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, "level": { "type": "string", "enum": [ "account", "campaign", "adset", "ad" ], "description": "Aggregation level: account, campaign, adset, ad" }, "fields": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Metrics to retrieve (defaults to standard set)" }, "breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "age", "gender", "country", "region", "dma", "device_platform", "publisher_platform", "platform_position", "impression_device", "hourly_stats_aggregated_by_advertiser_time_zone", "hourly_stats_aggregated_by_audience_time_zone", "frequency_value", "place_page_id", "product_id", "ad_format_asset", "body_asset", "call_to_action_asset", "description_asset", "image_asset", "link_url_asset", "title_asset", "video_asset" ] }, "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, dma, device_platform, publisher_platform, platform_position, impression_device, frequency_value, place_page_id, product_id, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset" }, "action_breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "action_type", "action_target_id", "action_destination", "action_reaction", "action_video_sound", "action_video_type", "action_carousel_card_id", "action_carousel_card_name" ] }, "description": "Action breakdown dimensions: action_type, action_target_id, action_destination, action_reaction, action_video_sound, action_video_type, action_carousel_card_id, action_carousel_card_name" }, "filtering": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Field to filter on" }, "operator": { "type": "string", "enum": [ "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "IN", "NOT_IN", "CONTAIN", "NOT_CONTAIN" ], "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) to compare against — numbers are coerced to strings automatically" } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "description": "Filters as [{field, operator, value}]" }, "action_attribution_windows": { "type": "array", "items": { "type": "string", "enum": [ "1d_click", "7d_click", "28d_click", "1d_view", "7d_view", "28d_view", "1d_ev", "default" ] }, "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Meta ad account ID", "constraints": { "min_length": 1 } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_quarter, last_quarter, this_year, last_year, lifetime, maximum", "enum_values": [ "today", "yesterday", "this_week_mon_today", "this_week_sun_today", "last_week_mon_sun", "last_week_sun_sat", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "lifetime", "maximum" ] }, { "name": "time_range", "type": "object", "required": false, "description": "Custom date range {since, until} in YYYY-MM-DD" }, { "name": "time_increment", "type": "unknown", "required": false, "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, { "name": "level", "type": "string", "required": false, "description": "Aggregation level: account, campaign, adset, ad", "enum_values": [ "account", "campaign", "adset", "ad" ] }, { "name": "fields", "type": "array", "required": false, "description": "Metrics to retrieve (defaults to standard set)" }, { "name": "breakdowns", "type": "array", "required": false, "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, dma, device_platform, publisher_platform, platform_position, impression_device, frequency_value, place_page_id, product_id, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset" }, { "name": "action_breakdowns", "type": "array", "required": false, "description": "Action breakdown dimensions: action_type, action_target_id, action_destination, action_reaction, action_video_sound, action_video_type, action_carousel_card_id, action_carousel_card_name" }, { "name": "filtering", "type": "array", "required": false, "description": "Filters as [{field, operator, value}]" }, { "name": "action_attribution_windows", "type": "array", "required": false, "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default" }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "7-day click only conversions", "mcp_params": { "account_id": "act_123456789", "date_preset": "last_7d", "action_attribution_windows": [ "7d_click" ], "reason": "Isolate 7-day click attribution conversions for accurate ROAS measurement" }, "cli_command": "hopkin meta insights get --account act_123456789 --date-preset last_7d --action-attribution-windows 7d_click", "natural_language": "7-day click only conversions" }, { "label": "Age and gender breakdown", "mcp_params": { "account_id": "act_123", "date_preset": "last_7d", "breakdowns": [ "age", "gender" ], "reason": "Demographic breakdown not available in performance report" }, "cli_command": "hopkin meta insights get --account act_123 --date-preset last_7d --breakdowns age,gender", "natural_language": "Age and gender breakdown" }, { "label": "Publisher platform breakdown", "mcp_params": { "account_id": "act_123", "date_preset": "last_7d", "level": "adset", "breakdowns": [ "publisher_platform", "platform_position" ], "reason": "Placement breakdown by publisher and position" }, "cli_command": "hopkin meta insights get --account act_123 --date-preset last_7d --level adset --breakdowns publisher_platform,platform_position", "natural_language": "Publisher platform breakdown" }, { "label": "Video asset metrics", "mcp_params": { "account_id": "act_123", "date_preset": "last_7d", "level": "ad", "fields": [ "video_p25_watched_actions", "video_p50_watched_actions", "video_p75_watched_actions", "video_p100_watched_actions", "video_avg_time_watched_actions" ], "reason": "Video completion funnel for creative analysis" }, "cli_command": "hopkin meta insights get --account act_123 --date-preset last_7d --level ad --fields video_p25_watched_actions,video_p50_watched_actions,video_p75_watched_actions,video_p100_watched_actions,video_avg_time_watched_actions", "natural_language": "Video asset metrics" } ], "response_format": "json", "related_tools": [ { "name": "google_ads_get_insights", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_insights", "relationship": "cross-platform" }, { "name": "tiktok_ads_get_insights", "relationship": "cross-platform" } ] }, { "name": "meta_ads_get_performance_report", "title": "Get Meta Ads Performance Report", "description": "Full impression-to-conversion funnel report with delivery, engagement, actions, conversions, ROAS, and quality rankings. Preferred over meta_ads_get_insights for standard analysis. Use get_insights only for custom fields, hourly/creative-asset breakdowns, or video metrics. Always fetches fresh data.", "cli_command": "hopkin meta performance-report get", "cli_flags": [ { "flag": "--account", "description": "Meta ad account ID", "type": "string", "required": true }, { "flag": "--time-range", "description": "Required date range {since, until} in YYYY-MM-DD", "type": "object", "required": true }, { "flag": "--time-increment", "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"", "type": "unknown", "required": false }, { "flag": "--level", "description": "Aggregation level (default: account): account, campaign, adset, ad", "type": "string", "required": false }, { "flag": "--breakdowns", "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma", "type": "array", "required": false }, { "flag": "--filtering", "description": "Filters as [{field, operator, value}]", "type": "array", "required": false }, { "flag": "--action-attribution-windows", "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default", "type": "array", "required": false } ], "category": "reporting", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Required date range {since, until} in YYYY-MM-DD" }, "time_increment": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "string", "const": "monthly" }, { "type": "string", "const": "all_days" } ], "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, "level": { "type": "string", "enum": [ "account", "campaign", "adset", "ad" ], "description": "Aggregation level (default: account): account, campaign, adset, ad" }, "breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "age", "gender", "country", "region", "device_platform", "publisher_platform", "platform_position", "impression_device", "dma" ] }, "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma" }, "filtering": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Field to filter on" }, "operator": { "type": "string", "enum": [ "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "IN", "NOT_IN", "CONTAIN", "NOT_CONTAIN" ], "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) to compare against — numbers are coerced to strings automatically" } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "description": "Filters as [{field, operator, value}]" }, "action_attribution_windows": { "type": "array", "items": { "type": "string", "enum": [ "1d_click", "7d_click", "28d_click", "1d_view", "7d_view", "28d_view", "1d_ev", "default" ] }, "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "time_range", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Meta ad account ID", "constraints": { "min_length": 1 } }, { "name": "time_range", "type": "object", "required": true, "description": "Required date range {since, until} in YYYY-MM-DD" }, { "name": "time_increment", "type": "unknown", "required": false, "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, { "name": "level", "type": "string", "required": false, "description": "Aggregation level (default: account): account, campaign, adset, ad", "enum_values": [ "account", "campaign", "adset", "ad" ] }, { "name": "breakdowns", "type": "array", "required": false, "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma" }, { "name": "filtering", "type": "array", "required": false, "description": "Filters as [{field, operator, value}]" }, { "name": "action_attribution_windows", "type": "array", "required": false, "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default" }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Account overview", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "reason": "Monthly performance review" }, "cli_command": "hopkin meta performance-report get --account act_123 --time-range [object Object]", "natural_language": "Account overview" }, { "label": "Campaign comparison", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "campaign", "reason": "Compare campaign performance" }, "cli_command": "hopkin meta performance-report get --account act_123 --time-range [object Object] --level campaign", "natural_language": "Campaign comparison" }, { "label": "Daily trend", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-07" }, "time_increment": 1, "reason": "Daily performance trend" }, "cli_command": "hopkin meta performance-report get --account act_123 --time-range [object Object] --time-increment 1", "natural_language": "Daily trend" }, { "label": "Demographics", "mcp_params": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "breakdowns": [ "age", "gender" ], "reason": "Demographic analysis" }, "cli_command": "hopkin meta performance-report get --account act_123 --time-range [object Object] --breakdowns age,gender", "natural_language": "Demographics" }, { "label": "7-day click attribution report", "mcp_params": { "account_id": "act_123456789", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "action_attribution_windows": [ "7d_click" ], "reason": "Full-funnel report scoped to 7-day click attribution only" }, "cli_command": "hopkin meta performance-report get --account act_123456789 --time-range [object Object] --action-attribution-windows 7d_click", "natural_language": "7-day click attribution report" } ], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_ad_creative_report", "relationship": "sibling" }, { "name": "google_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "reddit_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "tiktok_ads_get_performance_report", "relationship": "cross-platform" } ] }, { "name": "meta_ads_ping", "title": "Ping Meta Ads MCP Server", "description": "Health check for the Meta Ads MCP server.", "cli_command": "hopkin meta ping", "cli_flags": [ { "flag": "--message", "description": "Optional message to echo back", "type": "string", "required": false } ], "category": "auth", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 100, "description": "Optional message to echo back" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "message", "type": "string", "required": false, "description": "Optional message to echo back", "constraints": { "max_length": 100 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Health check", "mcp_params": { "reason": "Verify server is running" }, "cli_command": "hopkin meta ping", "natural_language": "Health check" }, { "label": "With message", "mcp_params": { "message": "hello", "reason": "Test connectivity" }, "cli_command": "hopkin meta ping --message hello", "natural_language": "With message" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_check_auth_status", "relationship": "sibling" }, { "name": "google_ads_ping", "relationship": "cross-platform" }, { "name": "linkedin_ads_ping", "relationship": "cross-platform" }, { "name": "reddit_ads_ping", "relationship": "cross-platform" }, { "name": "tiktok_ads_ping", "relationship": "cross-platform" } ] }, { "name": "meta_ads_get_pixel_health", "title": "Get Meta Pixel Health", "description": "Comprehensive pixel health check: metadata, CAPI connection status, event volume stats, automatic matching config, and diagnostic checks (including event match quality indicators). Use this to diagnose tracking issues before analyzing ad performance — low ROAS could be a tracking problem, not a campaign problem.", "cli_command": "hopkin meta pixel-health get", "cli_flags": [ { "flag": "--account", "description": "The ad account ID (with or without act_ prefix)", "type": "string", "required": true }, { "flag": "--pixel-id", "description": "Specific pixel ID to check. If omitted, checks all pixels on the account.", "type": "string", "required": false }, { "flag": "--event-names", "description": "Filter event stats to these event names (e.g. [\"Purchase\", \"Lead\"])", "type": "array", "required": false }, { "flag": "--days-back", "description": "Number of days of event stats to include (default: 28, max: 90)", "type": "integer", "required": false }, { "flag": "--limit", "description": "Max pixels per page (default: 5, max: 20)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false } ], "category": "pixel-health", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "pixel_id": { "type": "string", "minLength": 1, "description": "Specific pixel ID to check. If omitted, checks all pixels on the account." }, "event_names": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filter event stats to these event names (e.g. [\"Purchase\", \"Lead\"])" }, "days_back": { "type": "integer", "minimum": 1, "maximum": 90, "default": 28, "description": "Number of days of event stats to include (default: 28, max: 90)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Max pixels per page (default: 5, max: 20)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "The ad account ID (with or without act_ prefix)", "constraints": { "min_length": 1 } }, { "name": "pixel_id", "type": "string", "required": false, "description": "Specific pixel ID to check. If omitted, checks all pixels on the account.", "constraints": { "min_length": 1 } }, { "name": "event_names", "type": "array", "required": false, "description": "Filter event stats to these event names (e.g. [\"Purchase\", \"Lead\"])" }, { "name": "days_back", "type": "integer", "required": false, "description": "Number of days of event stats to include (default: 28, max: 90)", "default": 28, "constraints": { "min": 1, "max": 90 } }, { "name": "limit", "type": "integer", "required": false, "description": "Max pixels per page (default: 5, max: 20)", "default": 5, "constraints": { "min": 1, "max": 20 } }, { "name": "cursor", "type": "string", "required": false, "description": "Pagination cursor from previous response", "constraints": { "min_length": 1 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "All pixels for account", "mcp_params": { "account_id": "act_123", "reason": "Audit tracking setup" }, "cli_command": "hopkin meta pixel-health get --account act_123", "natural_language": "All pixels for account" }, { "label": "Specific pixel", "mcp_params": { "account_id": "act_123", "pixel_id": "456", "reason": "Check pixel firing status" }, "cli_command": "hopkin meta pixel-health get --account act_123 --pixel-id 456", "natural_language": "Specific pixel" }, { "label": "Filter to key events", "mcp_params": { "account_id": "act_123", "event_names": [ "Purchase", "Lead" ], "days_back": 7, "reason": "Check tracking health for key events" }, "cli_command": "hopkin meta pixel-health get --account act_123 --event-names Purchase,Lead --days-back 7", "natural_language": "Filter to key events" } ], "response_format": "markdown", "related_tools": [] }, { "name": "meta_ads_store_preference", "title": "Store Meta Ads Preference", "description": "Store a persistent preference for a Meta ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.", "cli_command": "hopkin meta preferences store", "cli_flags": [ { "flag": "--entity-type", "description": "Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad", "type": "string", "required": true }, { "flag": "--entity-id", "description": "The platform entity ID (e.g. act_123456, 23842453456789)", "type": "string", "required": true }, { "flag": "--key", "description": "Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)", "type": "string", "required": true }, { "flag": "--value", "description": "Preference value — string, number, boolean, or JSON object", "type": "unknown", "required": false }, { "flag": "--source", "description": "Who set this preference: agent (default), user, or system", "type": "string", "required": false }, { "flag": "--note", "description": "Optional context about why this preference was set", "type": "string", "required": false } ], "category": "preferences", "annotations": { "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID (e.g. act_123456, 23842453456789)" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)" }, "value": { "description": "Preference value — string, number, boolean, or JSON object" }, "source": { "type": "string", "enum": [ "agent", "user", "system" ], "default": "agent", "description": "Who set this preference: agent (default), user, or system" }, "note": { "type": "string", "maxLength": 500, "description": "Optional context about why this preference was set" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "key", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "entity_type", "type": "string", "required": true, "description": "Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad", "enum_values": [ "ad_account", "campaign", "ad_set", "ad" ] }, { "name": "entity_id", "type": "string", "required": true, "description": "The platform entity ID (e.g. act_123456, 23842453456789)", "constraints": { "min_length": 1 } }, { "name": "key", "type": "string", "required": true, "description": "Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)", "constraints": { "min_length": 1, "max_length": 100 } }, { "name": "value", "type": "unknown", "required": false, "description": "Preference value — string, number, boolean, or JSON object" }, { "name": "source", "type": "string", "required": false, "description": "Who set this preference: agent (default), user, or system", "enum_values": [ "agent", "user", "system" ], "default": "agent" }, { "name": "note", "type": "string", "required": false, "description": "Optional context about why this preference was set", "constraints": { "max_length": 500 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Set metric", "mcp_params": { "entity_type": "ad_account", "entity_id": "act_123", "key": "preferred_conversion_metric", "value": "ROAS", "reason": "User wants ROAS as default metric" }, "cli_command": "hopkin meta preferences store --entity-type ad_account --entity-id act_123 --key preferred_conversion_metric --value ROAS", "natural_language": "Set metric" }, { "label": "Set threshold", "mcp_params": { "entity_type": "campaign", "entity_id": "456", "key": "budget_alert_threshold", "value": 0.8, "reason": "Alert at 80% budget" }, "cli_command": "hopkin meta preferences store --entity-type campaign --entity-id 456 --key budget_alert_threshold --value 0.8", "natural_language": "Set threshold" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_preferences", "relationship": "sibling" }, { "name": "meta_ads_delete_preference", "relationship": "sibling" }, { "name": "google_ads_store_preference", "relationship": "cross-platform" }, { "name": "linkedin_ads_store_preference", "relationship": "cross-platform" }, { "name": "reddit_ads_store_preference", "relationship": "cross-platform" } ] }, { "name": "meta_ads_get_preferences", "title": "Get Meta Ads Preferences", "description": "Get all stored preferences for a Meta ad entity. Preferences are also auto-attached to list tool responses as _stored_preferences.", "cli_command": "hopkin meta preferences get", "cli_flags": [ { "flag": "--entity-type", "description": "Type of ad entity: ad_account, campaign, ad_set, or ad", "type": "string", "required": true }, { "flag": "--entity-id", "description": "The platform entity ID", "type": "string", "required": true } ], "category": "preferences", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set, or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "entity_type", "type": "string", "required": true, "description": "Type of ad entity: ad_account, campaign, ad_set, or ad", "enum_values": [ "ad_account", "campaign", "ad_set", "ad" ] }, { "name": "entity_id", "type": "string", "required": true, "description": "The platform entity ID", "constraints": { "min_length": 1 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Get prefs", "mcp_params": { "entity_type": "ad_account", "entity_id": "act_123", "reason": "Check stored preferences" }, "cli_command": "hopkin meta preferences get --entity-type ad_account --entity-id act_123", "natural_language": "Get prefs" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_store_preference", "relationship": "sibling" }, { "name": "meta_ads_delete_preference", "relationship": "sibling" }, { "name": "google_ads_get_preferences", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_preferences", "relationship": "cross-platform" }, { "name": "reddit_ads_get_preferences", "relationship": "cross-platform" } ] }, { "name": "meta_ads_delete_preference", "title": "Delete Meta Ads Preference", "description": "Delete a stored preference by key. No-op if it doesn't exist.", "cli_command": "hopkin meta preference delete", "cli_flags": [ { "flag": "--entity-type", "description": "Type of ad entity: ad_account, campaign, ad_set, or ad", "type": "string", "required": true }, { "flag": "--entity-id", "description": "The platform entity ID", "type": "string", "required": true }, { "flag": "--key", "description": "The preference key to delete", "type": "string", "required": true } ], "category": "preferences", "annotations": { "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "inputSchema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set, or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID" }, "key": { "type": "string", "minLength": 1, "description": "The preference key to delete" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "key", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "entity_type", "type": "string", "required": true, "description": "Type of ad entity: ad_account, campaign, ad_set, or ad", "enum_values": [ "ad_account", "campaign", "ad_set", "ad" ] }, { "name": "entity_id", "type": "string", "required": true, "description": "The platform entity ID", "constraints": { "min_length": 1 } }, { "name": "key", "type": "string", "required": true, "description": "The preference key to delete", "constraints": { "min_length": 1 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Delete pref", "mcp_params": { "entity_type": "campaign", "entity_id": "456", "key": "budget_alert_threshold", "reason": "User no longer wants budget alerts" }, "cli_command": "hopkin meta preference delete --entity-type campaign --entity-id 456 --key budget_alert_threshold", "natural_language": "Delete pref" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_store_preference", "relationship": "sibling" }, { "name": "meta_ads_get_preferences", "relationship": "sibling" }, { "name": "google_ads_delete_preference", "relationship": "cross-platform" }, { "name": "linkedin_ads_delete_preference", "relationship": "cross-platform" }, { "name": "reddit_ads_delete_preference", "relationship": "cross-platform" } ] } ]