{ "commit_sha": "cffe5e3f8df8195626e134ee0676c0bf76e76310", "servers": [ { "id": "meta-ads", "name": "Meta Ads", "description": "Facebook and Instagram campaign management via Meta Marketing API v21.0", "tool_count": 16, "mcpUrl": "https://mcp.hopkin.ai/meta-ads/mcp", "tools": [ { "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" } ] } ] }, { "id": "google-ads", "name": "Google Ads", "description": "Google Ads campaign management with GAQL query support", "tool_count": 22, "mcpUrl": "https://mcp.hopkin.ai/google-ads/mcp", "tools": [ { "name": "google_ads_get_account_summary", "title": "Get Google Ads Account Summary", "description": "Standardized account-level performance summary for cross-platform comparison. Returns normalized metrics identical to meta_ads_get_account_summary, with per-conversion-action breakdown. Preferred over insights or performance report for quick account overviews. Always fetches fresh data.", "cli_command": "hopkin google account-summary get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--date-preset", "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "type": "string", "required": false }, { "flag": "--date-range", "description": "Custom date range {start_date, end_date} in YYYY-MM-DD", "type": "object", "required": false } ], "category": "account-summary", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "enum_values": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ] }, { "name": "date_range", "type": "object", "required": false, "description": "Custom date range {start_date, end_date} 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": { "customer_id": "1234567890", "reason": "Quick performance overview" }, "cli_command": "hopkin google account-summary get --customer-id 1234567890", "natural_language": "Last 30 days summary" }, { "label": "Last 7 days", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Weekly check-in" }, "cli_command": "hopkin google account-summary get --customer-id 1234567890 --date-preset LAST_7_DAYS", "natural_language": "Last 7 days" }, { "label": "With MCC", "mcp_params": { "customer_id": "1234567890", "login_customer_id": "9876543210", "date_preset": "LAST_30_DAYS", "reason": "Managed account overview" }, "cli_command": "hopkin google account-summary get --customer-id 1234567890 --login-customer-id 9876543210 --date-preset LAST_30_DAYS", "natural_language": "With MCC" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_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": "google_ads_get_activities", "title": "Get Google Ads Activities", "description": "Retrieve change history for a Google Ads account. Always fetches fresh data. Only changes within the past 30 days are available (API limit), and changes may take up to 3 minutes to appear. For CAMPAIGN_CRITERION events, use the description field as the definitive interpretation when present.", "cli_command": "hopkin google activities get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--start-date", "description": "Start date in YYYY-MM-DD format. Defaults to 7 days ago. Must be within the past 30 days.", "type": "string", "required": false }, { "flag": "--end-date", "description": "End date in YYYY-MM-DD format. Defaults to today.", "type": "string", "required": false }, { "flag": "--resource-type", "description": "Filter to a specific resource type: AD, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, CAMPAIGN, CAMPAIGN_BUDGET, CAMPAIGN_CRITERION, ASSET, ASSET_SET", "type": "string", "required": false }, { "flag": "--asset-ids", "description": "Filter to specific asset IDs (numeric). Automatically sets resource_type to ASSET.", "type": "array", "required": false }, { "flag": "--limit", "description": "Maximum number of activities to return (1-1000, default 50)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor from a previous response", "type": "string", "required": false } ], "category": "activities", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date in YYYY-MM-DD format. Defaults to 7 days ago. Must be within the past 30 days." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date in YYYY-MM-DD format. Defaults to today." }, "resource_type": { "type": "string", "enum": [ "AD", "AD_GROUP", "AD_GROUP_AD", "AD_GROUP_CRITERION", "CAMPAIGN", "CAMPAIGN_BUDGET", "CAMPAIGN_CRITERION", "ASSET", "ASSET_SET" ], "description": "Filter to a specific resource type: AD, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, CAMPAIGN, CAMPAIGN_BUDGET, CAMPAIGN_CRITERION, ASSET, ASSET_SET" }, "asset_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific asset IDs (numeric). Automatically sets resource_type to ASSET." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum number of activities to return (1-1000, default 50)" }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "start_date", "type": "string", "required": false, "description": "Start date in YYYY-MM-DD format. Defaults to 7 days ago. Must be within the past 30 days.", "constraints": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "end_date", "type": "string", "required": false, "description": "End date in YYYY-MM-DD format. Defaults to today.", "constraints": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "resource_type", "type": "string", "required": false, "description": "Filter to a specific resource type: AD, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, CAMPAIGN, CAMPAIGN_BUDGET, CAMPAIGN_CRITERION, ASSET, ASSET_SET", "enum_values": [ "AD", "AD_GROUP", "AD_GROUP_AD", "AD_GROUP_CRITERION", "CAMPAIGN", "CAMPAIGN_BUDGET", "CAMPAIGN_CRITERION", "ASSET", "ASSET_SET" ] }, { "name": "asset_ids", "type": "array", "required": false, "description": "Filter to specific asset IDs (numeric). Automatically sets resource_type to ASSET." }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of activities to return (1-1000, default 50)", "default": 50, "constraints": { "min": 1, "max": 1000 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor from a previous response" }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Recent account activity", "mcp_params": { "customer_id": "1234567890", "reason": "Review recent account changes" }, "cli_command": "hopkin google activities get --customer-id 1234567890", "natural_language": "Recent account activity" }, { "label": "Campaign changes only", "mcp_params": { "customer_id": "1234567890", "resource_type": "CAMPAIGN", "reason": "See recent campaign edits" }, "cli_command": "hopkin google activities get --customer-id 1234567890 --resource-type CAMPAIGN", "natural_language": "Campaign changes only" }, { "label": "Custom date range", "mcp_params": { "customer_id": "1234567890", "start_date": "2026-02-01", "end_date": "2026-02-28", "reason": "February activity audit" }, "cli_command": "hopkin google activities get --customer-id 1234567890 --start-date 2026-02-01 --end-date 2026-02-28", "natural_language": "Custom date range" }, { "label": "With MCC login", "mcp_params": { "customer_id": "1234567890", "login_customer_id": "9876543210", "reason": "Review changes on managed account" }, "cli_command": "hopkin google activities get --customer-id 1234567890 --login-customer-id 9876543210", "natural_language": "With MCC login" }, { "label": "Specific asset activity", "mcp_params": { "customer_id": "1234567890", "asset_ids": [ "123456789", "987654321" ], "reason": "Check recent changes to specific assets" }, "cli_command": "hopkin google activities get --customer-id 1234567890 --asset-ids 123456789,987654321", "natural_language": "Specific asset activity" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_activities", "relationship": "cross-platform" } ] }, { "name": "google_ads_list_accounts", "title": "List Google Ads Accounts", "description": "List Google Ads accounts accessible by the user, including MCC child accounts. When calling other tools for MCC child accounts, you MUST pass login_customer_id with the parent MCC Customer ID. Results are cached; pass refresh=true for latest data. To list only children of a specific MCC, use google_ads_list_mcc_child_accounts instead.", "cli_command": "hopkin google accounts list", "cli_flags": [ { "flag": "--customer-id", "description": "Get a specific account by Customer ID. When provided, returns only that account and ignores other filters/pagination.", "type": "string", "required": false }, { "flag": "--customer-ids", "description": "Get multiple accounts by Customer ID. Mutually exclusive with customer_id. When provided, ignores other filters/pagination.", "type": "array", "required": false }, { "flag": "--refresh", "description": "Force fresh data from Google Ads 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 accounts by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--limit", "description": "Number of accounts per page (default: 20, max: 100)", "type": "integer", "required": false } ], "category": "accounts", "annotations": { "readOnly": true, "destructive": false, "idempotent": false, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "Get a specific account by Customer ID. When provided, returns only that account and ignores other filters/pagination." }, "customer_ids": { "type": "array", "items": { "type": "string", "pattern": "^[\\d-]+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple accounts by Customer ID. Mutually exclusive with customer_id. When provided, ignores other filters/pagination." }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Google Ads 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 accounts by name (case-insensitive partial match)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of accounts per page (default: 20, max: 100)" }, "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": "customer_id", "type": "string", "required": false, "description": "Get a specific account by Customer ID. When provided, returns only that account and ignores other filters/pagination.", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "customer_ids", "type": "array", "required": false, "description": "Get multiple accounts by Customer ID. Mutually exclusive with customer_id. When provided, ignores other filters/pagination." }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force fresh data from Google Ads 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 accounts by name (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "limit", "type": "integer", "required": false, "description": "Number of accounts per page (default: 20, max: 100)", "constraints": { "min": 1, "max": 100 } }, { "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 google accounts list", "natural_language": "List all" }, { "label": "Get by ID", "mcp_params": { "customer_id": "1234567890", "reason": "Get account details" }, "cli_command": "hopkin google accounts list --customer-id 1234567890", "natural_language": "Get by ID" }, { "label": "Search by name", "mcp_params": { "search": "marketing", "reason": "Find marketing accounts" }, "cli_command": "hopkin google accounts list --search marketing", "natural_language": "Search by name" }, { "label": "Get multiple by ID", "mcp_params": { "customer_ids": [ "1234567890", "0987654321" ], "reason": "Get details for specific accounts" }, "cli_command": "hopkin google accounts list --customer-ids 1234567890,0987654321", "natural_language": "Get multiple by ID" }, { "label": "Force refresh", "mcp_params": { "refresh": true, "reason": "Get fresh data" }, "cli_command": "hopkin google accounts list --refresh true", "natural_language": "Force refresh" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_list_mcc_child_accounts", "title": "List MCC Child Accounts", "description": "List child accounts under a specific MCC (Manager) account. When calling other tools for these child accounts, you MUST pass login_customer_id with the MCC Customer ID. For all accessible accounts regardless of hierarchy, use google_ads_list_accounts instead.", "cli_command": "hopkin google mcc-child-accounts list", "cli_flags": [ { "flag": "--mcc-id", "description": "The MCC (Manager) Customer ID whose child accounts to list (10 digits, dashes accepted)", "type": "string", "required": true }, { "flag": "--search", "description": "Search child accounts by name or customer ID (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--limit", "description": "Number of accounts per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false } ], "category": "mcc-child-accounts", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "mcc_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The MCC (Manager) Customer ID whose child accounts to list (10 digits, dashes accepted)" }, "search": { "type": "string", "minLength": 1, "description": "Search child accounts by name or customer ID (case-insensitive partial match)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of accounts per page (default: 20, max: 100)" }, "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": [ "mcc_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "mcc_id", "type": "string", "required": true, "description": "The MCC (Manager) Customer ID whose child accounts to list (10 digits, dashes accepted)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "search", "type": "string", "required": false, "description": "Search child accounts by name or customer ID (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "limit", "type": "integer", "required": false, "description": "Number of accounts 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": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "List children", "mcp_params": { "mcc_id": "1234567890", "reason": "List MCC child accounts" }, "cli_command": "hopkin google mcc-child-accounts list --mcc-id 1234567890", "natural_language": "List children" }, { "label": "Search children", "mcp_params": { "mcc_id": "1234567890", "search": "marketing", "reason": "Find child accounts" }, "cli_command": "hopkin google mcc-child-accounts list --mcc-id 1234567890 --search marketing", "natural_language": "Search children" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_list_ad_groups", "title": "List Google Ads Ad Groups", "description": "List ad groups for a Google Ads account. Supports filtering by campaign, status, search, and pagination. Results are cached; pass refresh=true for latest data.", "cli_command": "hopkin google ad-groups list", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--campaign", "description": "Filter by campaign ID (optional)", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Get a specific ad group by ID. When provided, returns only that ad group and ignores other filters/pagination.", "type": "string", "required": false }, { "flag": "--ad-group-ids", "description": "Get multiple ad groups by ID. Mutually exclusive with ad_group_id. When provided, ignores other filters/pagination.", "type": "array", "required": false }, { "flag": "--search", "description": "Search ad groups by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by ad group status: ENABLED, PAUSED, REMOVED", "type": "array", "required": false }, { "flag": "--limit", "description": "Number of ad groups 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 Google Ads 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": "ad-groups", "annotations": { "readOnly": true, "destructive": false, "idempotent": false, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter by campaign ID (optional)" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Get a specific ad group by ID. When provided, returns only that ad group and ignores other filters/pagination." }, "ad_group_ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple ad groups by ID. Mutually exclusive with ad_group_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search ad groups by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by ad group status: ENABLED, PAUSED, REMOVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ad groups 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 Google Ads 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": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter by campaign ID (optional)", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Get a specific ad group by ID. When provided, returns only that ad group and ignores other filters/pagination.", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_ids", "type": "array", "required": false, "description": "Get multiple ad groups by ID. Mutually exclusive with ad_group_id. When provided, ignores other filters/pagination." }, { "name": "search", "type": "string", "required": false, "description": "Search ad groups by name (case-insensitive partial match)", "constraints": { "min_length": 1 } }, { "name": "status", "type": "array", "required": false, "description": "Filter by ad group status: ENABLED, PAUSED, REMOVED" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of ad groups 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 Google Ads 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": "List all", "mcp_params": { "customer_id": "1234567890", "reason": "List ad groups" }, "cli_command": "hopkin google ad-groups list --customer-id 1234567890", "natural_language": "List all" }, { "label": "Filter by campaign", "mcp_params": { "customer_id": "1234567890", "campaign_id": "9876543210", "reason": "List ad groups in campaign" }, "cli_command": "hopkin google ad-groups list --customer-id 1234567890 --campaign 9876543210", "natural_language": "Filter by campaign" }, { "label": "Get by ID", "mcp_params": { "customer_id": "1234567890", "ad_group_id": "5555555555", "reason": "Get ad group details" }, "cli_command": "hopkin google ad-groups list --customer-id 1234567890 --ad-group-id 5555555555", "natural_language": "Get by ID" }, { "label": "Search", "mcp_params": { "customer_id": "1234567890", "search": "brand", "reason": "Find brand ad groups" }, "cli_command": "hopkin google ad-groups list --customer-id 1234567890 --search brand", "natural_language": "Search" }, { "label": "Get multiple by ID", "mcp_params": { "customer_id": "1234567890", "ad_group_ids": [ "111", "222", "333" ], "reason": "Get details for specific ad groups" }, "cli_command": "hopkin google ad-groups list --customer-id 1234567890 --ad-group-ids 111,222,333", "natural_language": "Get multiple by ID" }, { "label": "Filter by status", "mcp_params": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled ad groups" }, "cli_command": "hopkin google ad-groups list --customer-id 1234567890 --status ENABLED", "natural_language": "Filter by status" } ], "response_format": "markdown", "related_tools": [ { "name": "google_ads_list_ads", "relationship": "hierarchy" }, { "name": "google_ads_list_campaigns", "relationship": "hierarchy" }, { "name": "reddit_ads_list_ad_groups", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_ad_groups", "relationship": "cross-platform" } ] }, { "name": "google_ads_list_ads", "title": "List Google Ads", "description": "List ads for a Google Ads account. Supports filtering by ad group, status, search, and pagination. Results are cached; pass refresh=true for latest data.", "cli_command": "hopkin google ads list", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter by ad group ID (optional)", "type": "string", "required": false }, { "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": "--search", "description": "Search ads by name (case-insensitive partial match)", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by ad status: ENABLED, PAUSED, REMOVED", "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 Google Ads 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": "ads", "annotations": { "readOnly": true, "destructive": false, "idempotent": false, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter by ad group ID (optional)" }, "ad_id": { "type": "string", "pattern": "^\\d+$", "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", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search ads by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by ad status: ENABLED, PAUSED, REMOVED" }, "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 Google Ads 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": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter by ad group ID (optional)", "constraints": { "pattern": "^\\d+$" } }, { "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": { "pattern": "^\\d+$" } }, { "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": "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: ENABLED, PAUSED, REMOVED" }, { "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 Google Ads 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": "List all", "mcp_params": { "customer_id": "1234567890", "reason": "List ads" }, "cli_command": "hopkin google ads list --customer-id 1234567890", "natural_language": "List all" }, { "label": "Filter by ad group", "mcp_params": { "customer_id": "1234567890", "ad_group_id": "5555555555", "reason": "List ads in ad group" }, "cli_command": "hopkin google ads list --customer-id 1234567890 --ad-group-id 5555555555", "natural_language": "Filter by ad group" }, { "label": "Get by ID", "mcp_params": { "customer_id": "1234567890", "ad_id": "7777777777", "reason": "Get ad details" }, "cli_command": "hopkin google ads list --customer-id 1234567890 --ad 7777777777", "natural_language": "Get by ID" }, { "label": "Search", "mcp_params": { "customer_id": "1234567890", "search": "promo", "reason": "Find promo ads" }, "cli_command": "hopkin google ads list --customer-id 1234567890 --search promo", "natural_language": "Search" }, { "label": "Get multiple by ID", "mcp_params": { "customer_id": "1234567890", "ad_ids": [ "111", "222", "333" ], "reason": "Get details for specific ads" }, "cli_command": "hopkin google ads list --customer-id 1234567890 --ad-ids 111,222,333", "natural_language": "Get multiple by ID" }, { "label": "Filter by status", "mcp_params": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled ads" }, "cli_command": "hopkin google ads list --customer-id 1234567890 --status ENABLED", "natural_language": "Filter by status" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ads", "relationship": "cross-platform" }, { "name": "google_ads_list_ad_groups", "relationship": "hierarchy" }, { "name": "reddit_ads_list_ads", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_ads", "relationship": "cross-platform" } ] }, { "name": "google_ads_check_auth_status", "title": "Check Google Ads Auth Status", "description": "Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.", "cli_command": "hopkin google 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 google auth check", "natural_language": "Check auth" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "google_ads_ping", "relationship": "sibling" }, { "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": "google_ads_get_auto_applied_recommendations", "title": "Check Google Ads Auto-Applied Recommendations", "description": "Check which Google Ads recommendation types are set to auto-apply for an account. Auto-applied recommendations can automatically change bids, budgets, keywords, and campaign structure without manual review. Essential for account audits.", "cli_command": "hopkin google auto-applied-recommendations get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false } ], "category": "auto-applied-recommendations", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Check auto-applied", "mcp_params": { "customer_id": "1234567890", "reason": "Audit auto-applied recommendation settings" }, "cli_command": "hopkin google auto-applied-recommendations get --customer-id 1234567890", "natural_language": "Check auto-applied" }, { "label": "MCC account", "mcp_params": { "customer_id": "1234567890", "login_customer_id": "9876543210", "reason": "Check auto-applied for managed account" }, "cli_command": "hopkin google auto-applied-recommendations get --customer-id 1234567890 --login-customer-id 9876543210", "natural_language": "MCC account" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_list_campaigns", "title": "List Google Ads Campaigns", "description": "List campaigns for a Google Ads account. Supports status filtering, search, and pagination. Results are cached; pass refresh=true for latest data.", "cli_command": "hopkin google campaigns list", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "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": "--status", "description": "Filter by campaign status: ENABLED, PAUSED, REMOVED", "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 Google Ads 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": "campaigns", "annotations": { "readOnly": true, "destructive": false, "idempotent": false, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "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", "pattern": "^\\d+$" }, "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)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by campaign status: ENABLED, PAUSED, REMOVED" }, "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 Google Ads 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": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "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": { "pattern": "^\\d+$" } }, { "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": "status", "type": "array", "required": false, "description": "Filter by campaign status: ENABLED, PAUSED, REMOVED" }, { "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 Google Ads 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": "List all", "mcp_params": { "customer_id": "1234567890", "reason": "List campaigns" }, "cli_command": "hopkin google campaigns list --customer-id 1234567890", "natural_language": "List all" }, { "label": "Filter by status", "mcp_params": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled campaigns" }, "cli_command": "hopkin google campaigns list --customer-id 1234567890 --status ENABLED", "natural_language": "Filter by status" }, { "label": "Get by ID", "mcp_params": { "customer_id": "1234567890", "campaign_id": "9876543210", "reason": "Get campaign details" }, "cli_command": "hopkin google campaigns list --customer-id 1234567890 --campaign 9876543210", "natural_language": "Get by ID" }, { "label": "Search", "mcp_params": { "customer_id": "1234567890", "search": "brand", "reason": "Find brand campaigns" }, "cli_command": "hopkin google campaigns list --customer-id 1234567890 --search brand", "natural_language": "Search" }, { "label": "Get multiple by ID", "mcp_params": { "customer_id": "1234567890", "campaign_ids": [ "111", "222", "333" ], "reason": "Get details for specific campaigns" }, "cli_command": "hopkin google campaigns list --customer-id 1234567890 --campaign-ids 111,222,333", "natural_language": "Get multiple by ID" }, { "label": "MCC child", "mcp_params": { "customer_id": "1234567890", "login_customer_id": "9999999999", "reason": "List campaigns for MCC child" }, "cli_command": "hopkin google campaigns list --customer-id 1234567890 --login-customer-id 9999999999", "natural_language": "MCC child" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "google_ads_list_ad_groups", "relationship": "hierarchy" }, { "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": "google_ads_get_conversion_actions", "title": "List Google Ads Conversion Actions", "description": "List conversion actions configured for a Google Ads account. Use this to understand which conversions are tracked before querying performance reports or insights with conversion segments.", "cli_command": "hopkin google conversion-actions get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by status (default: returns all non-REMOVED). ENABLED, REMOVED, HIDDEN", "type": "string", "required": false }, { "flag": "--limit", "description": "Maximum number of conversion actions to return (default: 100, max: 500)", "type": "number", "required": false } ], "category": "conversion-actions", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "minLength": 1, "description": "MCC (Manager) Customer ID; required for managed accounts" }, "status": { "type": "string", "enum": [ "ENABLED", "REMOVED", "HIDDEN" ], "description": "Filter by status (default: returns all non-REMOVED). ENABLED, REMOVED, HIDDEN" }, "limit": { "type": "number", "minimum": 1, "maximum": 500, "default": 100, "description": "Maximum number of conversion actions to return (default: 100, max: 500)" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "min_length": 1 } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "min_length": 1 } }, { "name": "status", "type": "string", "required": false, "description": "Filter by status (default: returns all non-REMOVED). ENABLED, REMOVED, HIDDEN", "enum_values": [ "ENABLED", "REMOVED", "HIDDEN" ] }, { "name": "limit", "type": "number", "required": false, "description": "Maximum number of conversion actions to return (default: 100, max: 500)", "default": 100, "constraints": { "min": 1, "max": 500 } }, { "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": { "customer_id": "1234567890", "reason": "See configured conversion actions" }, "cli_command": "hopkin google conversion-actions get --customer-id 1234567890", "natural_language": "List all" }, { "label": "Enabled only", "mcp_params": { "customer_id": "1234567890", "status": "ENABLED", "reason": "Active conversion actions" }, "cli_command": "hopkin google conversion-actions get --customer-id 1234567890 --status ENABLED", "natural_language": "Enabled only" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_developer_feedback", "title": "Submit Developer Feedback", "description": "Submit feedback about missing tools, needed improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues (auth errors, API errors).", "cli_command": "hopkin google 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 google 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 ad groups", "description": "No way to duplicate a campaign including ad groups and ads", "current_workaround": "Read and recreate each level one by one", "reason": "User wanted to duplicate campaign structure" }, "cli_command": "hopkin google developer-feedback send --feedback-type workflow_gap --title Campaign cloning with ad groups --description No way to duplicate a campaign including ad groups and ads --current-workaround Read and recreate each level one by one", "natural_language": "Workflow gap" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_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": "google_ads_get_geo_performance", "title": "Get Google Ads Geographic Performance", "description": "Get geographic performance data from the geographic_view resource. Only ONE geo level per query. Returns both AREA_OF_INTEREST and LOCATION_OF_PRESENCE location types with auto-resolved location names. Includes a parallel conversion action breakdown. Location names are resolved automatically from criterion IDs.", "cli_command": "hopkin google geo-performance get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--date-preset", "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "type": "string", "required": false }, { "flag": "--date-range", "description": "Custom date range {start_date, end_date} in YYYY-MM-DD", "type": "object", "required": false }, { "flag": "--geo-level", "description": "Geographic granularity. \"country\" uses geographic_view.country_criterion_id; others add a segments.geo_target_* drill-down. Only one geo level per query.", "type": "string", "required": false }, { "flag": "--level", "description": "Entity breakdown level", "type": "string", "required": false }, { "flag": "--segments", "description": "Additional non-geo segments: date, device, ad_network_type", "type": "array", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign ID", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter to a specific ad group ID", "type": "string", "required": false }, { "flag": "--limit", "description": "Max rows returned (default 50, max 200)", "type": "number", "required": false }, { "flag": "--include-all-conversions", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\".", "type": "boolean", "required": false } ], "category": "geo-performance", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "geo_level": { "type": "string", "enum": [ "country", "geo_target_city", "geo_target_region", "geo_target_state", "geo_target_metro", "geo_target_province", "geo_target_county", "geo_target_district", "geo_target_most_specific_location", "geo_target_postal_code", "geo_target_airport", "geo_target_canton" ], "default": "country", "description": "Geographic granularity. \"country\" uses geographic_view.country_criterion_id; others add a segments.geo_target_* drill-down. Only one geo level per query." }, "level": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP" ], "default": "CAMPAIGN", "description": "Entity breakdown level" }, "segments": { "type": "array", "items": { "type": "string", "enum": [ "date", "device", "ad_network_type" ] }, "description": "Additional non-geo segments: date, device, ad_network_type" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "limit": { "type": "number", "minimum": 1, "maximum": 200, "default": 50, "description": "Max rows returned (default 50, max 200)" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "enum_values": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ] }, { "name": "date_range", "type": "object", "required": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, { "name": "geo_level", "type": "string", "required": false, "description": "Geographic granularity. \"country\" uses geographic_view.country_criterion_id; others add a segments.geo_target_* drill-down. Only one geo level per query.", "enum_values": [ "country", "geo_target_city", "geo_target_region", "geo_target_state", "geo_target_metro", "geo_target_province", "geo_target_county", "geo_target_district", "geo_target_most_specific_location", "geo_target_postal_code", "geo_target_airport", "geo_target_canton" ], "default": "country" }, { "name": "level", "type": "string", "required": false, "description": "Entity breakdown level", "enum_values": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP" ], "default": "CAMPAIGN" }, { "name": "segments", "type": "array", "required": false, "description": "Additional non-geo segments: date, device, ad_network_type" }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter to a specific ad group ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "limit", "type": "number", "required": false, "description": "Max rows returned (default 50, max 200)", "default": 50, "constraints": { "min": 1, "max": 200 } }, { "name": "include_all_conversions", "type": "boolean", "required": false, "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Country performance", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "geo_level": "country", "reason": "Compare spend by country" }, "cli_command": "hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_7_DAYS --geo-level country", "natural_language": "Country performance" }, { "label": "City-level breakdown", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "geo_level": "geo_target_city", "level": "CAMPAIGN", "reason": "City performance analysis" }, "cli_command": "hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_30_DAYS --geo-level geo_target_city --level CAMPAIGN", "natural_language": "City-level breakdown" }, { "label": "Country by campaign", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "geo_level": "country", "level": "CAMPAIGN", "segments": [ "date" ], "reason": "Daily country trends per campaign" }, "cli_command": "hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_7_DAYS --geo-level country --level CAMPAIGN --segments date", "natural_language": "Country by campaign" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_get_insights", "title": "Get Google Ads Insights", "description": "Retrieve performance metrics using GAQL with full control over metrics, segments, levels, and date ranges. Always fetches fresh data. Use segments=['ad_network_type'] to break down Performance Max campaigns by channel (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.). For standard analysis, prefer google_ads_get_performance_report; use this only for custom metric selection, search impression share diagnostics, ad_network_type channel breakdowns, or segment combinations not available in the performance report. For geographic data, use google_ads_get_geo_performance instead. Conversion action segments automatically remove incompatible cost-based metrics. Budget-lost impression share variants are campaign-level only.", "cli_command": "hopkin google insights get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--date-preset", "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "type": "string", "required": false }, { "flag": "--date-range", "description": "Custom date range {start_date, end_date} in YYYY-MM-DD", "type": "object", "required": false }, { "flag": "--level", "description": "Report level (default: ACCOUNT): ACCOUNT, CAMPAIGN, AD_GROUP, AD", "type": "string", "required": false }, { "flag": "--metrics", "description": "Metrics to retrieve (defaults to standard set)", "type": "array", "required": false }, { "flag": "--segments", "description": "Segments to break down by (e.g., date, device, ad_network_type). Use ad_network_type to see which channel delivered traffic (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.) — essential for Performance Max analysis.", "type": "array", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign ID", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter to a specific ad group ID", "type": "string", "required": false } ], "category": "insights", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "level": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP", "AD" ], "default": "ACCOUNT", "description": "Report level (default: ACCOUNT): ACCOUNT, CAMPAIGN, AD_GROUP, AD" }, "metrics": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Metrics to retrieve (defaults to standard set)" }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Segments to break down by (e.g., date, device, ad_network_type). Use ad_network_type to see which channel delivered traffic (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.) — essential for Performance Max analysis." }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "enum_values": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ] }, { "name": "date_range", "type": "object", "required": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, { "name": "level", "type": "string", "required": false, "description": "Report level (default: ACCOUNT): ACCOUNT, CAMPAIGN, AD_GROUP, AD", "enum_values": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP", "AD" ], "default": "ACCOUNT" }, { "name": "metrics", "type": "array", "required": false, "description": "Metrics to retrieve (defaults to standard set)" }, { "name": "segments", "type": "array", "required": false, "description": "Segments to break down by (e.g., date, device, ad_network_type). Use ad_network_type to see which channel delivered traffic (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.) — essential for Performance Max analysis." }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter to a specific ad group ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "All conversions by action", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "metrics": [ "all_conversions", "all_conversions_value", "value_per_all_conversions" ], "segments": [ "conversion_action_name" ], "reason": "All conversions breakdown by action" }, "cli_command": "hopkin google insights get --customer-id 1234567890 --date-preset LAST_30_DAYS --metrics all_conversions,all_conversions_value,value_per_all_conversions --segments conversion_action_name", "natural_language": "All conversions by action" }, { "label": "Search impression share", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "level": "CAMPAIGN", "metrics": [ "search_impression_share", "search_top_impression_share", "search_absolute_top_impression_share", "search_budget_lost_impression_share", "search_rank_lost_impression_share" ], "reason": "Search IS diagnostics" }, "cli_command": "hopkin google insights get --customer-id 1234567890 --date-preset LAST_7_DAYS --level CAMPAIGN --metrics search_impression_share,search_top_impression_share,search_absolute_top_impression_share,search_budget_lost_impression_share,search_rank_lost_impression_share", "natural_language": "Search impression share" }, { "label": "Device breakdown with custom metrics", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "CAMPAIGN", "segments": [ "device" ], "metrics": [ "impressions", "clicks", "cost_micros", "conversions", "view_through_conversions" ], "reason": "Device breakdown with view-through conversions" }, "cli_command": "hopkin google insights get --customer-id 1234567890 --date-preset LAST_30_DAYS --level CAMPAIGN --segments device --metrics impressions,clicks,cost_micros,conversions,view_through_conversions", "natural_language": "Device breakdown with custom metrics" }, { "label": "PMax channel breakdown", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "CAMPAIGN", "segments": [ "ad_network_type" ], "reason": "PMax channel-level performance breakdown" }, "cli_command": "hopkin google insights get --customer-id 1234567890 --date-preset LAST_30_DAYS --level CAMPAIGN --segments ad_network_type", "natural_language": "PMax channel breakdown" } ], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_insights", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_insights", "relationship": "cross-platform" }, { "name": "tiktok_ads_get_insights", "relationship": "cross-platform" } ] }, { "name": "google_ads_get_keyword_performance", "title": "Get Google Ads Keyword Performance", "description": "Get keyword-level performance metrics including quality score, match type, status, and search impression share. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per keyword. Includes a parallel conversion breakdown by ad group. Always fetches fresh data.", "cli_command": "hopkin google keyword-performance get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--date-preset", "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "type": "string", "required": false }, { "flag": "--date-range", "description": "Custom date range {start_date, end_date} in YYYY-MM-DD", "type": "object", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign ID", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter to a specific ad group ID", "type": "string", "required": false }, { "flag": "--keyword-match-type", "description": "Filter by match type: EXACT, PHRASE, BROAD", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by keyword status: ENABLED, PAUSED, REMOVED", "type": "array", "required": false }, { "flag": "--limit", "description": "Maximum number of rows to return (1-1000, default 100)", "type": "integer", "required": false }, { "flag": "--order-by", "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr", "type": "string", "required": false }, { "flag": "--include-all-conversions", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\".", "type": "boolean", "required": false }, { "flag": "--segments", "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split keyword metrics by channel (SEARCH vs SEARCH_PARTNERS).", "type": "array", "required": false } ], "category": "keyword-performance", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "keyword_match_type": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ], "description": "Filter by match type: EXACT, PHRASE, BROAD" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by keyword status: ENABLED, PAUSED, REMOVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Maximum number of rows to return (1-1000, default 100)" }, "order_by": { "type": "string", "enum": [ "impressions", "clicks", "cost", "conversions", "ctr" ], "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split keyword metrics by channel (SEARCH vs SEARCH_PARTNERS)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "enum_values": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ] }, { "name": "date_range", "type": "object", "required": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter to a specific ad group ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "keyword_match_type", "type": "string", "required": false, "description": "Filter by match type: EXACT, PHRASE, BROAD", "enum_values": [ "EXACT", "PHRASE", "BROAD" ] }, { "name": "status", "type": "array", "required": false, "description": "Filter by keyword status: ENABLED, PAUSED, REMOVED" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of rows to return (1-1000, default 100)", "default": 100, "constraints": { "min": 1, "max": 1000 } }, { "name": "order_by", "type": "string", "required": false, "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr", "enum_values": [ "impressions", "clicks", "cost", "conversions", "ctr" ] }, { "name": "include_all_conversions", "type": "boolean", "required": false, "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, { "name": "segments", "type": "array", "required": false, "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split keyword metrics by channel (SEARCH vs SEARCH_PARTNERS)." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Top keywords", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Keyword performance review" }, "cli_command": "hopkin google keyword-performance get --customer-id 1234567890 --date-preset LAST_7_DAYS", "natural_language": "Top keywords" }, { "label": "Exact match only", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "keyword_match_type": "EXACT", "reason": "Exact match keyword analysis" }, "cli_command": "hopkin google keyword-performance get --customer-id 1234567890 --date-preset LAST_7_DAYS --keyword-match-type EXACT", "natural_language": "Exact match only" }, { "label": "Top converters", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "order_by": "conversions", "status": [ "ENABLED" ], "reason": "Find top converting keywords" }, "cli_command": "hopkin google keyword-performance get --customer-id 1234567890 --date-preset LAST_30_DAYS --order-by conversions --status ENABLED", "natural_language": "Top converters" }, { "label": "By network channel", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "ad_network_type" ], "reason": "Keyword performance by ad network" }, "cli_command": "hopkin google keyword-performance get --customer-id 1234567890 --date-preset LAST_30_DAYS --segments ad_network_type", "natural_language": "By network channel" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_get_search_terms_report", "title": "Get Google Ads Search Terms Report", "description": "Get actual search queries that triggered ads, with performance metrics and keyword match status. Google may not disclose all terms for privacy. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per search term. Always fetches fresh data. Conversion breakdown and landing page lookups are opt-in to control response size. For Performance Max campaigns, set pmax_search_categories=true to get search category insights (grouped themes) instead of individual search terms.", "cli_command": "hopkin google search-terms-report get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--date-preset", "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "type": "string", "required": false }, { "flag": "--date-range", "description": "Custom date range {start_date, end_date} in YYYY-MM-DD", "type": "object", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign ID", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter to a specific ad group ID", "type": "string", "required": false }, { "flag": "--search-term-status", "description": "Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE", "type": "array", "required": false }, { "flag": "--limit", "description": "Maximum number of rows to return (1-1000, default 100)", "type": "integer", "required": false }, { "flag": "--order-by", "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr", "type": "string", "required": false }, { "flag": "--include-all-conversions", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\".", "type": "boolean", "required": false }, { "flag": "--include-conversion-breakdown", "description": "When true, runs a parallel query to include conversion breakdown by ad group and conversion action. Adds significant response size — omit when response size is a concern. Default: false.", "type": "boolean", "required": false }, { "flag": "--include-landing-pages", "description": "When true, runs a parallel query against ad_group_ad to fetch final_urls for each ad group in the results. Returns landing_pages_by_ad_group map keyed by ad_group_id. Default: false.", "type": "boolean", "required": false }, { "flag": "--pmax-search-categories", "description": "When true, queries campaign_search_term_insight for PMax search category data (grouped themes, not individual queries). ad_group_id and search_term_status are ignored in this mode. Default: false.", "type": "boolean", "required": false }, { "flag": "--segments", "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). Ignored when pmax_search_categories is true.", "type": "array", "required": false } ], "category": "search-terms-report", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "search_term_status": { "type": "array", "items": { "type": "string", "enum": [ "ADDED", "EXCLUDED", "ADDED_EXCLUDED", "NONE" ] }, "description": "Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Maximum number of rows to return (1-1000, default 100)" }, "order_by": { "type": "string", "enum": [ "impressions", "clicks", "cost", "conversions", "ctr" ], "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, "include_conversion_breakdown": { "type": "boolean", "default": false, "description": "When true, runs a parallel query to include conversion breakdown by ad group and conversion action. Adds significant response size — omit when response size is a concern. Default: false." }, "include_landing_pages": { "type": "boolean", "default": false, "description": "When true, runs a parallel query against ad_group_ad to fetch final_urls for each ad group in the results. Returns landing_pages_by_ad_group map keyed by ad_group_id. Default: false." }, "pmax_search_categories": { "type": "boolean", "default": false, "description": "When true, queries campaign_search_term_insight for PMax search category data (grouped themes, not individual queries). ad_group_id and search_term_status are ignored in this mode. Default: false." }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). Ignored when pmax_search_categories is true." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "enum_values": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ] }, { "name": "date_range", "type": "object", "required": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter to a specific ad group ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "search_term_status", "type": "array", "required": false, "description": "Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of rows to return (1-1000, default 100)", "default": 100, "constraints": { "min": 1, "max": 1000 } }, { "name": "order_by", "type": "string", "required": false, "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr", "enum_values": [ "impressions", "clicks", "cost", "conversions", "ctr" ] }, { "name": "include_all_conversions", "type": "boolean", "required": false, "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, { "name": "include_conversion_breakdown", "type": "boolean", "required": false, "description": "When true, runs a parallel query to include conversion breakdown by ad group and conversion action. Adds significant response size — omit when response size is a concern. Default: false.", "default": false }, { "name": "include_landing_pages", "type": "boolean", "required": false, "description": "When true, runs a parallel query against ad_group_ad to fetch final_urls for each ad group in the results. Returns landing_pages_by_ad_group map keyed by ad_group_id. Default: false.", "default": false }, { "name": "pmax_search_categories", "type": "boolean", "required": false, "description": "When true, queries campaign_search_term_insight for PMax search category data (grouped themes, not individual queries). ad_group_id and search_term_status are ignored in this mode. Default: false.", "default": false }, { "name": "segments", "type": "array", "required": false, "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). Ignored when pmax_search_categories is true." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Top search terms", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Search term analysis" }, "cli_command": "hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_7_DAYS", "natural_language": "Top search terms" }, { "label": "New terms only", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "search_term_status": [ "NONE" ], "order_by": "conversions", "reason": "Find new converting search terms" }, "cli_command": "hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_7_DAYS --search-term-status NONE --order-by conversions", "natural_language": "New terms only" }, { "label": "With landing pages", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "include_landing_pages": true, "reason": "Find which landing pages top search terms go to" }, "cli_command": "hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_7_DAYS --include-landing-pages true", "natural_language": "With landing pages" }, { "label": "PMax search categories", "mcp_params": { "customer_id": "1234567890", "campaign_id": "5555555555", "date_preset": "LAST_30_DAYS", "pmax_search_categories": true, "reason": "PMax search category analysis" }, "cli_command": "hopkin google search-terms-report get --customer-id 1234567890 --campaign 5555555555 --date-preset LAST_30_DAYS --pmax-search-categories true", "natural_language": "PMax search categories" }, { "label": "By network channel", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "ad_network_type" ], "reason": "Search terms by ad network" }, "cli_command": "hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_30_DAYS --segments ad_network_type", "natural_language": "By network channel" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_list_negative_keyword_lists", "title": "List Google Ads Negative Keyword Lists", "description": "List shared negative keyword lists at the account level. Optionally includes the keywords within each list and which campaigns each list is attached to. Use for auditing shared exclusion lists and finding coverage gaps.", "cli_command": "hopkin google negative-keyword-lists list", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--list-id", "description": "Filter to a specific shared set ID to see its keywords and campaign associations", "type": "string", "required": false }, { "flag": "--include-keywords", "description": "Include the keywords in each list. Defaults to false for overview.", "type": "boolean", "required": false }, { "flag": "--include-campaign-associations", "description": "Include which campaigns each list is attached to. Defaults to false.", "type": "boolean", "required": false }, { "flag": "--limit", "description": "Number of lists per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false } ], "category": "negative-keyword-lists", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "list_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific shared set ID to see its keywords and campaign associations" }, "include_keywords": { "type": "boolean", "default": false, "description": "Include the keywords in each list. Defaults to false for overview." }, "include_campaign_associations": { "type": "boolean", "default": false, "description": "Include which campaigns each list is attached to. Defaults to false." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of lists per page (default: 20, max: 100)" }, "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": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "list_id", "type": "string", "required": false, "description": "Filter to a specific shared set ID to see its keywords and campaign associations", "constraints": { "pattern": "^\\d+$" } }, { "name": "include_keywords", "type": "boolean", "required": false, "description": "Include the keywords in each list. Defaults to false for overview.", "default": false }, { "name": "include_campaign_associations", "type": "boolean", "required": false, "description": "Include which campaigns each list is attached to. Defaults to false.", "default": false }, { "name": "limit", "type": "integer", "required": false, "description": "Number of lists 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": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "All lists", "mcp_params": { "customer_id": "1234567890", "reason": "Audit shared negative keyword lists" }, "cli_command": "hopkin google negative-keyword-lists list --customer-id 1234567890", "natural_language": "All lists" }, { "label": "With keywords", "mcp_params": { "customer_id": "1234567890", "include_keywords": true, "reason": "View all negative keyword list contents" }, "cli_command": "hopkin google negative-keyword-lists list --customer-id 1234567890 --include-keywords true", "natural_language": "With keywords" }, { "label": "Single list detail", "mcp_params": { "customer_id": "1234567890", "list_id": "5555555555", "include_keywords": true, "include_campaign_associations": true, "reason": "Full audit of a specific list" }, "cli_command": "hopkin google negative-keyword-lists list --customer-id 1234567890 --list-id 5555555555 --include-keywords true --include-campaign-associations true", "natural_language": "Single list detail" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_list_negative_keywords", "title": "List Google Ads Negative Keywords", "description": "List negative keywords at the campaign and/or ad-group level. Supports filtering by campaign, ad group, match type, and level. Always fetches fresh data. Use this during search term audits to cross-check recommended negatives against existing ones.", "cli_command": "hopkin google negative-keywords list", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign ID", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter to a specific ad group ID", "type": "string", "required": false }, { "flag": "--level", "description": "Which level of negative keywords to return. Defaults to ALL.", "type": "string", "required": false }, { "flag": "--match-type", "description": "Filter by match type: EXACT, PHRASE, BROAD", "type": "array", "required": false }, { "flag": "--limit", "description": "Number of negative keywords per page (default: 20, max: 100)", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Pagination cursor from previous response", "type": "string", "required": false } ], "category": "negative-keywords", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "level": { "type": "string", "enum": [ "CAMPAIGN", "AD_GROUP", "ALL" ], "default": "ALL", "description": "Which level of negative keywords to return. Defaults to ALL." }, "match_type": { "type": "array", "items": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ] }, "description": "Filter by match type: EXACT, PHRASE, BROAD" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of negative keywords per page (default: 20, max: 100)" }, "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": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "pattern": "^[\\d-]+$" } }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter to a specific ad group ID", "constraints": { "pattern": "^\\d+$" } }, { "name": "level", "type": "string", "required": false, "description": "Which level of negative keywords to return. Defaults to ALL.", "enum_values": [ "CAMPAIGN", "AD_GROUP", "ALL" ], "default": "ALL" }, { "name": "match_type", "type": "array", "required": false, "description": "Filter by match type: EXACT, PHRASE, BROAD" }, { "name": "limit", "type": "integer", "required": false, "description": "Number of negative keywords 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": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "All negatives", "mcp_params": { "customer_id": "1234567890", "reason": "Audit negative keywords" }, "cli_command": "hopkin google negative-keywords list --customer-id 1234567890", "natural_language": "All negatives" }, { "label": "Campaign level", "mcp_params": { "customer_id": "1234567890", "campaign_id": "5555555555", "level": "CAMPAIGN", "reason": "Cross-check campaign negatives during search term audit" }, "cli_command": "hopkin google negative-keywords list --customer-id 1234567890 --campaign 5555555555 --level CAMPAIGN", "natural_language": "Campaign level" }, { "label": "Filter by match type", "mcp_params": { "customer_id": "1234567890", "match_type": [ "BROAD" ], "reason": "Find broad match negatives that may be too aggressive" }, "cli_command": "hopkin google negative-keywords list --customer-id 1234567890 --match-type BROAD", "natural_language": "Filter by match type" } ], "response_format": "markdown", "related_tools": [] }, { "name": "google_ads_get_performance_report", "title": "Get Google Ads Performance Report", "description": "Comprehensive performance report with funnel metrics and per-conversion-action breakdowns. Preferred over google_ads_get_insights for standard analysis. Runs parallel queries for top-level funnel and conversion action breakdown. Search impression share is included at CAMPAIGN and AD_GROUP levels (budget-lost variants campaign-level only). Use google_ads_get_insights for custom metric selection. For geographic data, use google_ads_get_geo_performance instead.", "cli_command": "hopkin google performance-report get", "cli_flags": [ { "flag": "--customer-id", "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "type": "string", "required": true }, { "flag": "--login-customer-id", "description": "MCC (Manager) Customer ID; required for managed accounts", "type": "string", "required": false }, { "flag": "--date-preset", "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "type": "string", "required": false }, { "flag": "--date-range", "description": "Custom date range {start_date, end_date} in YYYY-MM-DD", "type": "object", "required": false }, { "flag": "--level", "description": "Report level (default: CAMPAIGN): ACCOUNT, CAMPAIGN, AD_GROUP, AD", "type": "string", "required": false }, { "flag": "--segments", "description": "Additional segments for the main metrics: date, device, ad_network_type. Conversion action breakdowns are always included automatically via a separate query.", "type": "array", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign ID", "type": "string", "required": false }, { "flag": "--ad-group-id", "description": "Filter to a specific ad group ID", "type": "string", "required": false }, { "flag": "--include-all-conversions", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\" (e.g., view-through, cross-device, store visits).", "type": "boolean", "required": false } ], "category": "reporting", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "minLength": 1, "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "level": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP", "AD" ], "default": "CAMPAIGN", "description": "Report level (default: CAMPAIGN): ACCOUNT, CAMPAIGN, AD_GROUP, AD" }, "segments": { "type": "array", "items": { "type": "string", "enum": [ "date", "device", "ad_network_type" ] }, "description": "Additional segments for the main metrics: date, device, ad_network_type. Conversion action breakdowns are always included automatically via a separate query." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "minLength": 1, "description": "Filter to a specific ad group ID" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\" (e.g., view-through, cross-device, store visits)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "customer_id", "type": "string", "required": true, "description": "The Google Ads Customer ID (10 digits, with or without dashes)", "constraints": { "min_length": 1 } }, { "name": "login_customer_id", "type": "string", "required": false, "description": "MCC (Manager) Customer ID; required for managed accounts", "constraints": { "min_length": 1 } }, { "name": "date_preset", "type": "string", "required": false, "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH", "enum_values": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ] }, { "name": "date_range", "type": "object", "required": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, { "name": "level", "type": "string", "required": false, "description": "Report level (default: CAMPAIGN): ACCOUNT, CAMPAIGN, AD_GROUP, AD", "enum_values": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP", "AD" ], "default": "CAMPAIGN" }, { "name": "segments", "type": "array", "required": false, "description": "Additional segments for the main metrics: date, device, ad_network_type. Conversion action breakdowns are always included automatically via a separate query." }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign ID", "constraints": { "min_length": 1 } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter to a specific ad group ID", "constraints": { "min_length": 1 } }, { "name": "include_all_conversions", "type": "boolean", "required": false, "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\" (e.g., view-through, cross-device, store visits)." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Campaign overview", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "reason": "Monthly performance review" }, "cli_command": "hopkin google performance-report get --customer-id 1234567890 --date-preset LAST_30_DAYS", "natural_language": "Campaign overview" }, { "label": "Daily trend", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "segments": [ "date" ], "reason": "Daily performance trend" }, "cli_command": "hopkin google performance-report get --customer-id 1234567890 --date-preset LAST_7_DAYS --segments date", "natural_language": "Daily trend" }, { "label": "Account summary", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "ACCOUNT", "reason": "Account-level overview" }, "cli_command": "hopkin google performance-report get --customer-id 1234567890 --date-preset LAST_30_DAYS --level ACCOUNT", "natural_language": "Account summary" }, { "label": "Device breakdown", "mcp_params": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "device" ], "reason": "Device analysis" }, "cli_command": "hopkin google performance-report get --customer-id 1234567890 --date-preset LAST_30_DAYS --segments device", "natural_language": "Device breakdown" } ], "response_format": "json", "related_tools": [ { "name": "meta_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": "google_ads_ping", "title": "Ping Google Ads MCP Server", "description": "Health check for the Google Ads MCP server.", "cli_command": "hopkin google 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 google ping", "natural_language": "Health check" }, { "label": "With message", "mcp_params": { "message": "hello", "reason": "Test connectivity" }, "cli_command": "hopkin google ping --message hello", "natural_language": "With message" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_ping", "relationship": "cross-platform" }, { "name": "google_ads_check_auth_status", "relationship": "sibling" }, { "name": "linkedin_ads_ping", "relationship": "cross-platform" }, { "name": "reddit_ads_ping", "relationship": "cross-platform" }, { "name": "tiktok_ads_ping", "relationship": "cross-platform" } ] }, { "name": "google_ads_store_preference", "title": "Store Google Ads Preference", "description": "Store a persistent preference for a Google Ads entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.", "cli_command": "hopkin google 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": "1234567890", "key": "preferred_conversion_metric", "value": "conversions", "reason": "User wants conversions as default metric" }, "cli_command": "hopkin google preferences store --entity-type ad_account --entity-id 1234567890 --key preferred_conversion_metric --value conversions", "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 google 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_store_preference", "relationship": "cross-platform" }, { "name": "google_ads_get_preferences", "relationship": "sibling" }, { "name": "google_ads_delete_preference", "relationship": "sibling" }, { "name": "linkedin_ads_store_preference", "relationship": "cross-platform" }, { "name": "reddit_ads_store_preference", "relationship": "cross-platform" } ] }, { "name": "google_ads_get_preferences", "title": "Get Google Ads Preferences", "description": "Get all stored preferences for a Google Ads entity. Preferences are also automatically attached to entity-listing tool responses as _stored_preferences, so you often don't need to call this explicitly.", "cli_command": "hopkin google 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": "1234567890", "reason": "Check stored preferences" }, "cli_command": "hopkin google preferences get --entity-type ad_account --entity-id 1234567890", "natural_language": "Get prefs" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_preferences", "relationship": "cross-platform" }, { "name": "google_ads_store_preference", "relationship": "sibling" }, { "name": "google_ads_delete_preference", "relationship": "sibling" }, { "name": "linkedin_ads_get_preferences", "relationship": "cross-platform" }, { "name": "reddit_ads_get_preferences", "relationship": "cross-platform" } ] }, { "name": "google_ads_delete_preference", "title": "Delete Google Ads Preference", "description": "Delete a stored preference for a Google Ads entity by key. No-op if the preference doesn't exist.", "cli_command": "hopkin google 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 google preference delete --entity-type campaign --entity-id 456 --key budget_alert_threshold", "natural_language": "Delete pref" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_delete_preference", "relationship": "cross-platform" }, { "name": "google_ads_store_preference", "relationship": "sibling" }, { "name": "google_ads_get_preferences", "relationship": "sibling" }, { "name": "linkedin_ads_delete_preference", "relationship": "cross-platform" }, { "name": "reddit_ads_delete_preference", "relationship": "cross-platform" } ] } ] }, { "id": "linkedin-ads", "name": "LinkedIn Ads", "description": "LinkedIn Marketing API v202602 for B2B advertising", "tool_count": 15, "mcpUrl": "https://mcp.hopkin.ai/linkedin-ads/mcp", "tools": [ { "name": "linkedin_ads_get_account_summary", "title": "Get LinkedIn Account Summary", "description": "Get a high-level performance summary for a LinkedIn Ads account including spend, impressions, clicks, conversions, leads, and conversion breakdown. Conversion data may be delayed 24-72 hours.", "cli_command": "hopkin linkedin account-summary get", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--date-preset", "description": "", "type": "string", "required": false }, { "flag": "--start-date", "description": "", "type": "string", "required": false }, { "flag": "--end-date", "description": "", "type": "string", "required": false } ], "category": "account-summary", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "date_preset": { "type": "string", "enum": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS" ], "default": "LAST_30_DAYS" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "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": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "date_preset", "type": "string", "required": false, "description": "", "enum_values": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS" ], "default": "LAST_30_DAYS" }, { "name": "start_date", "type": "string", "required": false, "description": "" }, { "name": "end_date", "type": "string", "required": false, "description": "" }, { "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", "mcp_params": { "account_id": "123456789", "date_preset": "LAST_30_DAYS", "reason": "User wants an account overview" }, "cli_command": "hopkin linkedin account-summary get --account 123456789 --date-preset LAST_30_DAYS", "natural_language": "Last 30 days" }, { "label": "This month", "mcp_params": { "account_id": "123456789", "date_preset": "THIS_MONTH", "reason": "Monthly performance summary" }, "cli_command": "hopkin linkedin account-summary get --account 123456789 --date-preset THIS_MONTH", "natural_language": "This month" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_account_summary", "relationship": "cross-platform" }, { "name": "google_ads_get_account_summary", "relationship": "cross-platform" }, { "name": "reddit_ads_get_account_summary", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_list_ad_accounts", "title": "List LinkedIn Ad Accounts", "description": "List LinkedIn Sponsored Ad Accounts accessible to the authenticated user.", "cli_command": "hopkin linkedin ad-accounts list", "cli_flags": [ { "flag": "--status", "description": "Filter by account status. Defaults to [ACTIVE].", "type": "array", "required": false }, { "flag": "--type", "description": "Filter by account type.", "type": "string", "required": false }, { "flag": "--include-test-accounts", "description": "Include test accounts. Defaults to false.", "type": "boolean", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor.", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "type": "boolean", "required": false } ], "category": "ad-accounts", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "CANCELED", "PENDING_DELETION", "REMOVED" ] }, "description": "Filter by account status. Defaults to [ACTIVE]." }, "type": { "type": "string", "enum": [ "BUSINESS", "ENTERPRISE" ], "description": "Filter by account type." }, "include_test_accounts": { "type": "boolean", "default": false, "description": "Include test accounts. Defaults to false." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "description": "Opaque pagination cursor." }, "refresh": { "type": "boolean", "default": false }, "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": "status", "type": "array", "required": false, "description": "Filter by account status. Defaults to [ACTIVE]." }, { "name": "type", "type": "string", "required": false, "description": "Filter by account type.", "enum_values": [ "BUSINESS", "ENTERPRISE" ] }, { "name": "include_test_accounts", "type": "boolean", "required": false, "description": "Include test accounts. Defaults to false.", "default": false }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor." }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "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 active accounts", "mcp_params": { "reason": "User wants to see their LinkedIn ad accounts" }, "cli_command": "hopkin linkedin ad-accounts list", "natural_language": "List active accounts" }, { "label": "Include test accounts", "mcp_params": { "include_test_accounts": true, "reason": "User wants to see test accounts" }, "cli_command": "hopkin linkedin ad-accounts list --include-test-accounts true", "natural_language": "Include test accounts" }, { "label": "By type", "mcp_params": { "type": "BUSINESS", "reason": "Filter to business accounts only" }, "cli_command": "hopkin linkedin ad-accounts list --type BUSINESS", "natural_language": "By type" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ad_accounts", "relationship": "cross-platform" }, { "name": "linkedin_ads_list_campaign_groups", "relationship": "hierarchy" }, { "name": "linkedin_ads_list_campaigns", "relationship": "hierarchy" }, { "name": "reddit_ads_list_ad_accounts", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_check_auth_status", "title": "Check LinkedIn Ads Authentication Status", "description": "Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.", "cli_command": "hopkin linkedin 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 LinkedIn account connection status" }, "cli_command": "hopkin linkedin auth check", "natural_language": "Check auth" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "google_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "linkedin_ads_ping", "relationship": "sibling" }, { "name": "reddit_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "tiktok_ads_check_auth_status", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_get_budget_pricing", "title": "Get LinkedIn Budget & Pricing", "description": "Get bid ranges and daily budget limits for a LinkedIn campaign type and audience. Call this before creating a campaign to understand recommended bids. DYNAMIC campaign type is not supported by this endpoint.", "cli_command": "hopkin linkedin budget-pricing get", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--campaign-type", "description": "Campaign type. DYNAMIC is not supported by this endpoint.", "type": "string", "required": true }, { "flag": "--bid-type", "description": "Bid type. CPV is only valid for SPONSORED_UPDATES video campaigns.", "type": "string", "required": true }, { "flag": "--match-type", "description": "", "type": "string", "required": true }, { "flag": "--currency", "description": "ISO-4217 currency code (e.g. USD, GBP).", "type": "string", "required": true }, { "flag": "--location-urns", "description": "Target location URNs (e.g. urn:li:geo:103644278 for USA).", "type": "array", "required": true }, { "flag": "--seniority-urns", "description": "Target seniority URNs (e.g. urn:li:seniority:4 for Senior).", "type": "array", "required": false }, { "flag": "--job-function-urns", "description": "Target job function URNs.", "type": "array", "required": false }, { "flag": "--industry-urns", "description": "Target industry URNs.", "type": "array", "required": false }, { "flag": "--company-size-urns", "description": "Target company size range URNs (e.g. urn:li:staffCountRange:(51,200)).", "type": "array", "required": false }, { "flag": "--objective-type", "description": "Affects suggested bid.", "type": "string", "required": false }, { "flag": "--daily-budget-amount", "description": "Current or target daily budget (influences suggested bid calculation).", "type": "number", "required": false } ], "category": "budget-pricing", "annotations": { "readOnly": true, "destructive": false, "idempotent": false, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "campaign_type": { "type": "string", "enum": [ "TEXT_AD", "SPONSORED_UPDATES", "SPONSORED_INMAILS" ], "description": "Campaign type. DYNAMIC is not supported by this endpoint." }, "bid_type": { "type": "string", "enum": [ "CPM", "CPC", "CPV" ], "description": "Bid type. CPV is only valid for SPONSORED_UPDATES video campaigns." }, "match_type": { "type": "string", "enum": [ "EXACT", "AUDIENCE_EXPANDED" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 currency code (e.g. USD, GBP)." }, "location_urns": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Target location URNs (e.g. urn:li:geo:103644278 for USA)." }, "seniority_urns": { "type": "array", "items": { "type": "string" }, "description": "Target seniority URNs (e.g. urn:li:seniority:4 for Senior)." }, "job_function_urns": { "type": "array", "items": { "type": "string" }, "description": "Target job function URNs." }, "industry_urns": { "type": "array", "items": { "type": "string" }, "description": "Target industry URNs." }, "company_size_urns": { "type": "array", "items": { "type": "string" }, "description": "Target company size range URNs (e.g. urn:li:staffCountRange:(51,200))." }, "objective_type": { "type": "string", "description": "Affects suggested bid." }, "daily_budget_amount": { "type": "number", "description": "Current or target daily budget (influences suggested bid calculation)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "campaign_type", "bid_type", "match_type", "currency", "location_urns", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "campaign_type", "type": "string", "required": true, "description": "Campaign type. DYNAMIC is not supported by this endpoint.", "enum_values": [ "TEXT_AD", "SPONSORED_UPDATES", "SPONSORED_INMAILS" ] }, { "name": "bid_type", "type": "string", "required": true, "description": "Bid type. CPV is only valid for SPONSORED_UPDATES video campaigns.", "enum_values": [ "CPM", "CPC", "CPV" ] }, { "name": "match_type", "type": "string", "required": true, "description": "", "enum_values": [ "EXACT", "AUDIENCE_EXPANDED" ] }, { "name": "currency", "type": "string", "required": true, "description": "ISO-4217 currency code (e.g. USD, GBP).", "constraints": { "min_length": 3, "max_length": 3 } }, { "name": "location_urns", "type": "array", "required": true, "description": "Target location URNs (e.g. urn:li:geo:103644278 for USA)." }, { "name": "seniority_urns", "type": "array", "required": false, "description": "Target seniority URNs (e.g. urn:li:seniority:4 for Senior)." }, { "name": "job_function_urns", "type": "array", "required": false, "description": "Target job function URNs." }, { "name": "industry_urns", "type": "array", "required": false, "description": "Target industry URNs." }, { "name": "company_size_urns", "type": "array", "required": false, "description": "Target company size range URNs (e.g. urn:li:staffCountRange:(51,200))." }, { "name": "objective_type", "type": "string", "required": false, "description": "Affects suggested bid." }, { "name": "daily_budget_amount", "type": "number", "required": false, "description": "Current or target daily budget (influences suggested bid calculation)." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Sponsored Content CPM", "mcp_params": { "account_id": "123456789", "campaign_type": "SPONSORED_UPDATES", "bid_type": "CPM", "match_type": "EXACT", "currency": "USD", "location_urns": [ "urn:li:geo:103644278" ], "reason": "User wants to know bid ranges before creating a campaign" }, "cli_command": "hopkin linkedin budget-pricing get --account 123456789 --campaign-type SPONSORED_UPDATES --bid-type CPM --match-type EXACT --currency USD --location-urns urn:li:geo:103644278", "natural_language": "Sponsored Content CPM" }, { "label": "Text Ad CPC", "mcp_params": { "account_id": "123456789", "campaign_type": "TEXT_AD", "bid_type": "CPC", "match_type": "BROAD", "currency": "USD", "location_urns": [ "urn:li:geo:103644278" ], "reason": "Get text ad pricing for US audience" }, "cli_command": "hopkin linkedin budget-pricing get --account 123456789 --campaign-type TEXT_AD --bid-type CPC --match-type BROAD --currency USD --location-urns urn:li:geo:103644278", "natural_language": "Text Ad CPC" } ], "response_format": "markdown", "related_tools": [] }, { "name": "linkedin_ads_list_campaign_groups", "title": "List LinkedIn Campaign Groups", "description": "List LinkedIn Campaign Groups for an ad account. Campaign groups are the top-level organizational unit containing campaigns.", "cli_command": "hopkin linkedin campaign-groups list", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--status", "description": "Filter by status. Defaults to [ACTIVE, PAUSED].", "type": "array", "required": false }, { "flag": "--campaign-group-id", "description": "Fetch a single campaign group by numeric ID.", "type": "string", "required": false }, { "flag": "--campaign-group-ids", "description": "Fetch specific campaign groups by numeric IDs (batch GET).", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "type": "boolean", "required": false } ], "category": "campaign-groups", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DRAFT", "ARCHIVED", "CANCELED", "PENDING_DELETION", "REMOVED" ] }, "description": "Filter by status. Defaults to [ACTIVE, PAUSED]." }, "campaign_group_id": { "type": "string", "description": "Fetch a single campaign group by numeric ID." }, "campaign_group_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific campaign groups by numeric IDs (batch GET)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string" }, "refresh": { "type": "boolean", "default": false }, "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": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "status", "type": "array", "required": false, "description": "Filter by status. Defaults to [ACTIVE, PAUSED]." }, { "name": "campaign_group_id", "type": "string", "required": false, "description": "Fetch a single campaign group by numeric ID." }, { "name": "campaign_group_ids", "type": "array", "required": false, "description": "Fetch specific campaign groups by numeric IDs (batch GET)." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "" }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "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 active groups", "mcp_params": { "account_id": "123456789", "reason": "User wants to see campaign groups" }, "cli_command": "hopkin linkedin campaign-groups list --account 123456789", "natural_language": "List active groups" }, { "label": "Filter by status", "mcp_params": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "Show active and paused campaign groups" }, "cli_command": "hopkin linkedin campaign-groups list --account 123456789 --status ACTIVE,PAUSED", "natural_language": "Filter by status" } ], "response_format": "markdown", "related_tools": [ { "name": "linkedin_ads_list_ad_accounts", "relationship": "hierarchy" }, { "name": "linkedin_ads_list_campaigns", "relationship": "hierarchy" } ] }, { "name": "linkedin_ads_list_campaigns", "title": "List LinkedIn Campaigns", "description": "List LinkedIn Campaigns for an ad account. Campaigns define targeting, bidding, and budget within a campaign group.", "cli_command": "hopkin linkedin campaigns list", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--status", "description": "Filter by status. Defaults to [ACTIVE, PAUSED].", "type": "array", "required": false }, { "flag": "--campaign-group-id", "description": "Filter by campaign group (numeric ID).", "type": "string", "required": false }, { "flag": "--type", "description": "Filter by campaign type.", "type": "array", "required": false }, { "flag": "--campaign", "description": "Fetch a single campaign by numeric ID.", "type": "string", "required": false }, { "flag": "--campaign-ids", "description": "Fetch specific campaigns by numeric IDs (batch filter).", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "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": "Ad account ID (numeric, without URN prefix)." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DRAFT", "ARCHIVED", "COMPLETED", "CANCELED", "PENDING_DELETION", "REMOVED" ] }, "description": "Filter by status. Defaults to [ACTIVE, PAUSED]." }, "campaign_group_id": { "type": "string", "description": "Filter by campaign group (numeric ID)." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "TEXT_AD", "SPONSORED_UPDATES", "SPONSORED_INMAILS", "DYNAMIC", "EVENT_AD" ] }, "description": "Filter by campaign type." }, "campaign_id": { "type": "string", "description": "Fetch a single campaign by numeric ID." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific campaigns by numeric IDs (batch filter)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string" }, "refresh": { "type": "boolean", "default": false }, "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": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "status", "type": "array", "required": false, "description": "Filter by status. Defaults to [ACTIVE, PAUSED]." }, { "name": "campaign_group_id", "type": "string", "required": false, "description": "Filter by campaign group (numeric ID)." }, { "name": "type", "type": "array", "required": false, "description": "Filter by campaign type." }, { "name": "campaign_id", "type": "string", "required": false, "description": "Fetch a single campaign by numeric ID." }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Fetch specific campaigns by numeric IDs (batch filter)." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "" }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "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 active campaigns", "mcp_params": { "account_id": "123456789", "reason": "User wants to see campaigns" }, "cli_command": "hopkin linkedin campaigns list --account 123456789", "natural_language": "List active campaigns" }, { "label": "By campaign group", "mcp_params": { "account_id": "123456789", "campaign_group_id": "987654", "reason": "List campaigns under a specific campaign group" }, "cli_command": "hopkin linkedin campaigns list --account 123456789 --campaign-group-id 987654", "natural_language": "By campaign group" }, { "label": "By type", "mcp_params": { "account_id": "123456789", "type": [ "SPONSORED_UPDATES" ], "reason": "Filter to sponsored content campaigns" }, "cli_command": "hopkin linkedin campaigns list --account 123456789 --type SPONSORED_UPDATES", "natural_language": "By type" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "google_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "linkedin_ads_list_ad_accounts", "relationship": "hierarchy" }, { "name": "linkedin_ads_list_campaign_groups", "relationship": "hierarchy" }, { "name": "linkedin_ads_list_creatives", "relationship": "hierarchy" }, { "name": "reddit_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_campaigns", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_list_creatives", "title": "List LinkedIn Creatives", "description": "List LinkedIn Creatives (ads) for an ad account. IMPORTANT: Always explicitly pass resolve_content=true when the user asks about ad copy, headlines, body text, URLs, or creative details — do not omit it and rely on the default. Only set resolve_content=false when the user needs metadata-only and has NOT asked about content.", "cli_command": "hopkin linkedin creatives list", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--campaign-ids", "description": "Filter by campaign IDs (numeric).", "type": "array", "required": false }, { "flag": "--status", "description": "Filter by intended status. Defaults to [ACTIVE, PAUSED, DRAFT].", "type": "array", "required": false }, { "flag": "--resolve-content", "description": "Resolve ad copy (headline, body text, destination URL) from linked posts/shares. Default: true. Set to false only when you need metadata-only (IDs, status, content type) and explicitly do NOT need ad copy.", "type": "boolean", "required": false }, { "flag": "--creative-id", "description": "Fetch a single creative by URN or numeric ID.", "type": "string", "required": false }, { "flag": "--creative-ids", "description": "Fetch specific creatives by numeric IDs (batch filter).", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "type": "boolean", "required": false } ], "category": "creatives", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "Filter by campaign IDs (numeric)." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DRAFT", "ARCHIVED", "CANCELED", "PENDING_DELETION", "REMOVED" ] }, "description": "Filter by intended status. Defaults to [ACTIVE, PAUSED, DRAFT]." }, "resolve_content": { "type": "boolean", "default": true, "description": "Resolve ad copy (headline, body text, destination URL) from linked posts/shares. Default: true. Set to false only when you need metadata-only (IDs, status, content type) and explicitly do NOT need ad copy." }, "creative_id": { "type": "string", "description": "Fetch a single creative by URN or numeric ID." }, "creative_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific creatives by numeric IDs (batch filter)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string" }, "refresh": { "type": "boolean", "default": false }, "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": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Filter by campaign IDs (numeric)." }, { "name": "status", "type": "array", "required": false, "description": "Filter by intended status. Defaults to [ACTIVE, PAUSED, DRAFT]." }, { "name": "resolve_content", "type": "boolean", "required": false, "description": "Resolve ad copy (headline, body text, destination URL) from linked posts/shares. Default: true. Set to false only when you need metadata-only (IDs, status, content type) and explicitly do NOT need ad copy.", "default": true }, { "name": "creative_id", "type": "string", "required": false, "description": "Fetch a single creative by URN or numeric ID." }, { "name": "creative_ids", "type": "array", "required": false, "description": "Fetch specific creatives by numeric IDs (batch filter)." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "" }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "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 active creatives", "mcp_params": { "account_id": "123456789", "reason": "User wants to see ads" }, "cli_command": "hopkin linkedin creatives list --account 123456789", "natural_language": "List active creatives" }, { "label": "By campaign", "mcp_params": { "account_id": "123456789", "campaign_ids": [ "654321" ], "reason": "Show creatives for a specific campaign" }, "cli_command": "hopkin linkedin creatives list --account 123456789 --campaign-ids 654321", "natural_language": "By campaign" }, { "label": "With content resolved", "mcp_params": { "account_id": "123456789", "resolve_content": true, "reason": "Show ad copy and headline text" }, "cli_command": "hopkin linkedin creatives list --account 123456789 --resolve-content true", "natural_language": "With content resolved" } ], "response_format": "markdown", "related_tools": [ { "name": "linkedin_ads_list_campaigns", "relationship": "hierarchy" } ] }, { "name": "linkedin_ads_developer_feedback", "title": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, or workflow gaps in the LinkedIn Ads MCP toolset. Not for user-facing issues like auth or API errors.", "cli_command": "hopkin linkedin 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 LinkedIn campaigns at once rather than one by one", "priority": "high", "reason": "User asked to pause 8 campaigns individually" }, "cli_command": "hopkin linkedin developer-feedback send --feedback-type new_tool --title Bulk campaign status toggle --description Need to pause/enable multiple LinkedIn campaigns at once rather than one by one --priority high", "natural_language": "Missing tool" }, { "label": "Workflow gap", "mcp_params": { "feedback_type": "workflow_gap", "title": "Campaign group hierarchy cloning", "description": "No way to duplicate a campaign group including all campaigns and creatives", "current_workaround": "Read and recreate each level one by one", "reason": "User wanted to duplicate campaign structure for A/B test" }, "cli_command": "hopkin linkedin developer-feedback send --feedback-type workflow_gap --title Campaign group hierarchy cloning --description No way to duplicate a campaign group including all campaigns and creatives --current-workaround Read and recreate each level one by one", "natural_language": "Workflow gap" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "google_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "reddit_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "tiktok_ads_developer_feedback", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_get_insights", "title": "Get LinkedIn Ads Insights", "description": "Get LinkedIn Ads analytics with a single pivot dimension. For standard analysis, prefer linkedin_ads_get_performance_report; use this only for MEMBER_* demographic pivots (unique to LinkedIn) or custom metric queries not available in the performance report. MEMBER_* pivots have a 3-event minimum threshold and 12-24 hour data delay, so totals may not match account-level numbers. Max 18 metrics per query.", "cli_command": "hopkin linkedin insights get", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--pivot", "description": "Analytics pivot dimension. MEMBER_* pivots provide demographic breakdowns unique to LinkedIn.", "type": "string", "required": true }, { "flag": "--date-preset", "description": "", "type": "string", "required": false }, { "flag": "--start-date", "description": "ISO date YYYY-MM-DD. Use with end_date to override date_preset.", "type": "string", "required": false }, { "flag": "--end-date", "description": "", "type": "string", "required": false }, { "flag": "--time-granularity", "description": "", "type": "string", "required": false }, { "flag": "--campaign-ids", "description": "Filter to specific campaigns (numeric IDs).", "type": "array", "required": false }, { "flag": "--campaign-group-ids", "description": "Filter to specific campaign groups (numeric IDs).", "type": "array", "required": false }, { "flag": "--metrics", "description": "LinkedIn adAnalytics metric field names (camelCase, exact names required). Core: impressions, clicks, costInLocalCurrency, costInUsd. Conversions: externalWebsiteConversions, externalWebsitePostClickConversions, externalWebsitePostViewConversions, conversionValueInLocalCurrency. Leads: oneClickLeads, oneClickLeadFormOpens, qualifiedLeads. Video: videoViews, videoCompletions. Engagement: totalEngagements, shares, follows, reactions, comments, landingPageClicks, textUrlClicks, companyPageClicks. Card: cardImpressions, cardClicks, viralCardImpressions, viralCardClicks. Reach: approximateMemberReach (only with ACCOUNT/CAMPAIGN_GROUP/CAMPAIGN pivot, ≤92 day range). IMPORTANT: Do NOT use aliases like \"conversions\", \"leads\", \"spend\", or \"reach\" — use the exact camelCase field names listed above. Max 18 (pivotValues + dateRange count toward the 20-field API limit). Defaults to: impressions, clicks, costInLocalCurrency, costInUsd, externalWebsiteConversions, oneClickLeads, videoViews, totalEngagements.", "type": "array", "required": false }, { "flag": "--include-conversion-breakdown", "description": "When true (and pivot is not CONVERSION), runs a second query to break down conversions per action with names.", "type": "boolean", "required": false } ], "category": "insights", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "pivot": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN_GROUP", "CAMPAIGN", "CREATIVE", "SHARE", "COMPANY", "CONVERSION", "CONVERSATION_NODE", "SERVING_LOCATION", "PLACEMENT_NAME", "IMPRESSION_DEVICE_TYPE", "CARD_INDEX", "MEMBER_COMPANY_SIZE", "MEMBER_INDUSTRY", "MEMBER_SENIORITY", "MEMBER_JOB_TITLE", "MEMBER_JOB_FUNCTION", "MEMBER_COUNTRY_V2", "MEMBER_REGION_V2", "MEMBER_COUNTY", "MEMBER_COMPANY" ], "description": "Analytics pivot dimension. MEMBER_* pivots provide demographic breakdowns unique to LinkedIn." }, "date_preset": { "type": "string", "enum": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS" ], "default": "LAST_30_DAYS" }, "start_date": { "type": "string", "description": "ISO date YYYY-MM-DD. Use with end_date to override date_preset." }, "end_date": { "type": "string" }, "time_granularity": { "type": "string", "enum": [ "ALL", "DAILY", "MONTHLY" ], "default": "ALL" }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter to specific campaigns (numeric IDs)." }, "campaign_group_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "Filter to specific campaign groups (numeric IDs)." }, "metrics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 18, "description": "LinkedIn adAnalytics metric field names (camelCase, exact names required). Core: impressions, clicks, costInLocalCurrency, costInUsd. Conversions: externalWebsiteConversions, externalWebsitePostClickConversions, externalWebsitePostViewConversions, conversionValueInLocalCurrency. Leads: oneClickLeads, oneClickLeadFormOpens, qualifiedLeads. Video: videoViews, videoCompletions. Engagement: totalEngagements, shares, follows, reactions, comments, landingPageClicks, textUrlClicks, companyPageClicks. Card: cardImpressions, cardClicks, viralCardImpressions, viralCardClicks. Reach: approximateMemberReach (only with ACCOUNT/CAMPAIGN_GROUP/CAMPAIGN pivot, ≤92 day range). IMPORTANT: Do NOT use aliases like \"conversions\", \"leads\", \"spend\", or \"reach\" — use the exact camelCase field names listed above. Max 18 (pivotValues + dateRange count toward the 20-field API limit). Defaults to: impressions, clicks, costInLocalCurrency, costInUsd, externalWebsiteConversions, oneClickLeads, videoViews, totalEngagements." }, "include_conversion_breakdown": { "type": "boolean", "default": false, "description": "When true (and pivot is not CONVERSION), runs a second query to break down conversions per action with names." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "pivot", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "pivot", "type": "string", "required": true, "description": "Analytics pivot dimension. MEMBER_* pivots provide demographic breakdowns unique to LinkedIn.", "enum_values": [ "ACCOUNT", "CAMPAIGN_GROUP", "CAMPAIGN", "CREATIVE", "SHARE", "COMPANY", "CONVERSION", "CONVERSATION_NODE", "SERVING_LOCATION", "PLACEMENT_NAME", "IMPRESSION_DEVICE_TYPE", "CARD_INDEX", "MEMBER_COMPANY_SIZE", "MEMBER_INDUSTRY", "MEMBER_SENIORITY", "MEMBER_JOB_TITLE", "MEMBER_JOB_FUNCTION", "MEMBER_COUNTRY_V2", "MEMBER_REGION_V2", "MEMBER_COUNTY", "MEMBER_COMPANY" ] }, { "name": "date_preset", "type": "string", "required": false, "description": "", "enum_values": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS" ], "default": "LAST_30_DAYS" }, { "name": "start_date", "type": "string", "required": false, "description": "ISO date YYYY-MM-DD. Use with end_date to override date_preset." }, { "name": "end_date", "type": "string", "required": false, "description": "" }, { "name": "time_granularity", "type": "string", "required": false, "description": "", "enum_values": [ "ALL", "DAILY", "MONTHLY" ], "default": "ALL" }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Filter to specific campaigns (numeric IDs)." }, { "name": "campaign_group_ids", "type": "array", "required": false, "description": "Filter to specific campaign groups (numeric IDs)." }, { "name": "metrics", "type": "array", "required": false, "description": "LinkedIn adAnalytics metric field names (camelCase, exact names required). Core: impressions, clicks, costInLocalCurrency, costInUsd. Conversions: externalWebsiteConversions, externalWebsitePostClickConversions, externalWebsitePostViewConversions, conversionValueInLocalCurrency. Leads: oneClickLeads, oneClickLeadFormOpens, qualifiedLeads. Video: videoViews, videoCompletions. Engagement: totalEngagements, shares, follows, reactions, comments, landingPageClicks, textUrlClicks, companyPageClicks. Card: cardImpressions, cardClicks, viralCardImpressions, viralCardClicks. Reach: approximateMemberReach (only with ACCOUNT/CAMPAIGN_GROUP/CAMPAIGN pivot, ≤92 day range). IMPORTANT: Do NOT use aliases like \"conversions\", \"leads\", \"spend\", or \"reach\" — use the exact camelCase field names listed above. Max 18 (pivotValues + dateRange count toward the 20-field API limit). Defaults to: impressions, clicks, costInLocalCurrency, costInUsd, externalWebsiteConversions, oneClickLeads, videoViews, totalEngagements." }, { "name": "include_conversion_breakdown", "type": "boolean", "required": false, "description": "When true (and pivot is not CONVERSION), runs a second query to break down conversions per action with names.", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Job function breakdown", "mcp_params": { "account_id": "123456789", "pivot": "MEMBER_JOB_FUNCTION", "date_preset": "LAST_30_DAYS", "reason": "Demographic breakdown by job function" }, "cli_command": "hopkin linkedin insights get --account 123456789 --pivot MEMBER_JOB_FUNCTION --date-preset LAST_30_DAYS", "natural_language": "Job function breakdown" }, { "label": "Seniority breakdown", "mcp_params": { "account_id": "123456789", "pivot": "MEMBER_SENIORITY", "date_preset": "LAST_30_DAYS", "reason": "Performance by member seniority level" }, "cli_command": "hopkin linkedin insights get --account 123456789 --pivot MEMBER_SENIORITY --date-preset LAST_30_DAYS", "natural_language": "Seniority breakdown" }, { "label": "Industry breakdown", "mcp_params": { "account_id": "123456789", "pivot": "MEMBER_INDUSTRY", "date_preset": "LAST_30_DAYS", "reason": "Reach and engagement by industry" }, "cli_command": "hopkin linkedin insights get --account 123456789 --pivot MEMBER_INDUSTRY --date-preset LAST_30_DAYS", "natural_language": "Industry breakdown" }, { "label": "Device type breakdown", "mcp_params": { "account_id": "123456789", "pivot": "IMPRESSION_DEVICE_TYPE", "date_preset": "LAST_30_DAYS", "reason": "Performance split by device type" }, "cli_command": "hopkin linkedin insights get --account 123456789 --pivot IMPRESSION_DEVICE_TYPE --date-preset LAST_30_DAYS", "natural_language": "Device type breakdown" } ], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_insights", "relationship": "cross-platform" }, { "name": "google_ads_get_insights", "relationship": "cross-platform" }, { "name": "tiktok_ads_get_insights", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_get_partner_conversions", "title": "Get LinkedIn Partner Conversions", "description": "List partner conversions (conversion actions) configured for a LinkedIn Ads account. Use this to understand what conversion tracking is set up before analyzing performance data.", "cli_command": "hopkin linkedin partner-conversions get", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true } ], "category": "partner-conversions", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "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": "Ad account ID (numeric, without URN prefix).", "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": "List all partner conversions", "mcp_params": { "account_id": "123456789", "reason": "User wants to see what partner conversions are configured" }, "cli_command": "hopkin linkedin partner-conversions get --account 123456789", "natural_language": "List all partner conversions" } ], "response_format": "markdown", "related_tools": [] }, { "name": "linkedin_ads_get_performance_report", "title": "Get LinkedIn Ads Performance Report", "description": "Get a full-funnel performance report with up to 3 pivot dimensions and optional per-conversion-action breakdown. MEMBER_* demographic pivots are not supported here — use linkedin_ads_get_insights instead.", "cli_command": "hopkin linkedin performance-report get", "cli_flags": [ { "flag": "--account", "description": "Ad account ID (numeric, without URN prefix).", "type": "string", "required": true }, { "flag": "--pivots", "description": "Up to 3 pivot dimensions. OBJECTIVE_TYPE is only available in q=statistics.", "type": "array", "required": false }, { "flag": "--date-preset", "description": "", "type": "string", "required": false }, { "flag": "--start-date", "description": "", "type": "string", "required": false }, { "flag": "--end-date", "description": "", "type": "string", "required": false }, { "flag": "--time-granularity", "description": "", "type": "string", "required": false }, { "flag": "--campaign-ids", "description": "", "type": "array", "required": false }, { "flag": "--campaign-group-ids", "description": "", "type": "array", "required": false }, { "flag": "--include-conversion-breakdown", "description": "Run a second query for per-conversion-action breakdown. Adds one extra API call.", "type": "boolean", "required": false } ], "category": "reporting", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Ad account ID (numeric, without URN prefix)." }, "pivots": { "type": "array", "items": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN_GROUP", "CAMPAIGN", "CREATIVE", "SHARE", "COMPANY", "CONVERSION", "SERVING_LOCATION", "PLACEMENT_NAME", "IMPRESSION_DEVICE_TYPE", "CARD_INDEX", "OBJECTIVE_TYPE" ] }, "minItems": 1, "maxItems": 3, "default": [ "CAMPAIGN" ], "description": "Up to 3 pivot dimensions. OBJECTIVE_TYPE is only available in q=statistics." }, "date_preset": { "type": "string", "enum": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS" ], "default": "LAST_30_DAYS" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "time_granularity": { "type": "string", "enum": [ "ALL", "DAILY", "MONTHLY" ], "default": "ALL" }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "campaign_group_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 }, "include_conversion_breakdown": { "type": "boolean", "default": true, "description": "Run a second query for per-conversion-action breakdown. Adds one extra API call." }, "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": "Ad account ID (numeric, without URN prefix).", "constraints": { "min_length": 1 } }, { "name": "pivots", "type": "array", "required": false, "description": "Up to 3 pivot dimensions. OBJECTIVE_TYPE is only available in q=statistics.", "default": [ "CAMPAIGN" ] }, { "name": "date_preset", "type": "string", "required": false, "description": "", "enum_values": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS" ], "default": "LAST_30_DAYS" }, { "name": "start_date", "type": "string", "required": false, "description": "" }, { "name": "end_date", "type": "string", "required": false, "description": "" }, { "name": "time_granularity", "type": "string", "required": false, "description": "", "enum_values": [ "ALL", "DAILY", "MONTHLY" ], "default": "ALL" }, { "name": "campaign_ids", "type": "array", "required": false, "description": "" }, { "name": "campaign_group_ids", "type": "array", "required": false, "description": "" }, { "name": "include_conversion_breakdown", "type": "boolean", "required": false, "description": "Run a second query for per-conversion-action breakdown. Adds one extra API call.", "default": true }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [ { "label": "Campaign report", "mcp_params": { "account_id": "123456789", "pivots": [ "CAMPAIGN" ], "date_preset": "LAST_30_DAYS", "reason": "User wants full campaign performance report" }, "cli_command": "hopkin linkedin performance-report get --account 123456789 --pivots CAMPAIGN --date-preset LAST_30_DAYS", "natural_language": "Campaign report" }, { "label": "With conversion breakdown", "mcp_params": { "account_id": "123456789", "pivots": [ "CAMPAIGN" ], "date_preset": "LAST_30_DAYS", "include_conversion_breakdown": true, "reason": "Show conversion breakdown by campaign" }, "cli_command": "hopkin linkedin performance-report get --account 123456789 --pivots CAMPAIGN --date-preset LAST_30_DAYS --include-conversion-breakdown true", "natural_language": "With conversion breakdown" }, { "label": "Daily campaign group", "mcp_params": { "account_id": "123456789", "pivots": [ "CAMPAIGN_GROUP" ], "time_granularity": "DAILY", "date_preset": "LAST_7_DAYS", "reason": "Daily trend by campaign group" }, "cli_command": "hopkin linkedin performance-report get --account 123456789 --pivots CAMPAIGN_GROUP --time-granularity DAILY --date-preset LAST_7_DAYS", "natural_language": "Daily campaign group" } ], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "google_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": "linkedin_ads_ping", "title": "Ping LinkedIn Ads MCP Server", "description": "Health check for the LinkedIn Ads MCP server. Does not call the LinkedIn API.", "cli_command": "hopkin linkedin 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 linkedin ping", "natural_language": "Health check" }, { "label": "With message", "mcp_params": { "message": "hello", "reason": "Test connectivity" }, "cli_command": "hopkin linkedin ping --message hello", "natural_language": "With message" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_ping", "relationship": "cross-platform" }, { "name": "google_ads_ping", "relationship": "cross-platform" }, { "name": "linkedin_ads_check_auth_status", "relationship": "sibling" }, { "name": "reddit_ads_ping", "relationship": "cross-platform" }, { "name": "tiktok_ads_ping", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_store_preference", "title": "Store LinkedIn Ads Preference", "description": "Store a persistent preference for a LinkedIn ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys. Entity type \"ad_set\" maps to LinkedIn campaigns; \"ad\" maps to creatives.", "cli_command": "hopkin linkedin 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": "123456789", "key": "preferred_conversion_metric", "value": "oneClickLeads", "reason": "User wants lead conversions as default metric" }, "cli_command": "hopkin linkedin preferences store --entity-type ad_account --entity-id 123456789 --key preferred_conversion_metric --value oneClickLeads", "natural_language": "Set metric" }, { "label": "Set threshold", "mcp_params": { "entity_type": "campaign", "entity_id": "987654321", "key": "budget_alert_threshold", "value": 0.8, "reason": "Alert at 80% of campaign budget" }, "cli_command": "hopkin linkedin preferences store --entity-type campaign --entity-id 987654321 --key budget_alert_threshold --value 0.8", "natural_language": "Set threshold" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_store_preference", "relationship": "cross-platform" }, { "name": "google_ads_store_preference", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_preferences", "relationship": "sibling" }, { "name": "linkedin_ads_delete_preference", "relationship": "sibling" }, { "name": "reddit_ads_store_preference", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_get_preferences", "title": "Get LinkedIn Ads Preferences", "description": "Get all stored preferences for a LinkedIn Ads entity. Preferences are also automatically attached to entity-listing responses, so you often don't need to call this explicitly.", "cli_command": "hopkin linkedin 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": "123456789", "reason": "Check stored preferences before running report" }, "cli_command": "hopkin linkedin preferences get --entity-type ad_account --entity-id 123456789", "natural_language": "Get prefs" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_preferences", "relationship": "cross-platform" }, { "name": "google_ads_get_preferences", "relationship": "cross-platform" }, { "name": "linkedin_ads_store_preference", "relationship": "sibling" }, { "name": "linkedin_ads_delete_preference", "relationship": "sibling" }, { "name": "reddit_ads_get_preferences", "relationship": "cross-platform" } ] }, { "name": "linkedin_ads_delete_preference", "title": "Delete LinkedIn Ads Preference", "description": "Delete a stored preference for a LinkedIn Ads entity by key. No-op if the preference doesn't exist.", "cli_command": "hopkin linkedin 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": "987654321", "key": "budget_alert_threshold", "reason": "User no longer wants budget alerts for this campaign" }, "cli_command": "hopkin linkedin preference delete --entity-type campaign --entity-id 987654321 --key budget_alert_threshold", "natural_language": "Delete pref" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_delete_preference", "relationship": "cross-platform" }, { "name": "google_ads_delete_preference", "relationship": "cross-platform" }, { "name": "linkedin_ads_store_preference", "relationship": "sibling" }, { "name": "linkedin_ads_get_preferences", "relationship": "sibling" }, { "name": "reddit_ads_delete_preference", "relationship": "cross-platform" } ] } ] }, { "id": "reddit-ads", "name": "Reddit Ads", "description": "Reddit Ads API for community-driven advertising campaigns", "tool_count": 13, "mcpUrl": "https://mcp.hopkin.ai/reddit-ads/mcp", "tools": [ { "name": "reddit_ads_get_account_summary", "title": "Get Reddit Ads Account Summary", "description": "Get a high-level performance summary for a Reddit ad account over a date range.", "cli_command": "hopkin reddit account-summary get", "cli_flags": [ { "flag": "--account", "description": "Reddit ad account ID.", "type": "string", "required": true }, { "flag": "--date-start", "description": "Start date in YYYY-MM-DD format.", "type": "string", "required": true }, { "flag": "--date-end", "description": "End date in YYYY-MM-DD format.", "type": "string", "required": true } ], "category": "account-summary", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Reddit ad account ID." }, "date_start": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "date_end": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "date_start", "date_end", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Reddit ad account ID.", "constraints": { "min_length": 1 } }, { "name": "date_start", "type": "string", "required": true, "description": "Start date in YYYY-MM-DD format." }, { "name": "date_end", "type": "string", "required": true, "description": "End date in YYYY-MM-DD format." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_account_summary", "relationship": "cross-platform" }, { "name": "google_ads_get_account_summary", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_account_summary", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_list_ad_accounts", "title": "List Reddit Ad Accounts", "description": "List Reddit ad accounts accessible to the authenticated user.", "cli_command": "hopkin reddit ad-accounts list", "cli_flags": [ { "flag": "--account", "description": "Fetch a single ad account by ID.", "type": "string", "required": false }, { "flag": "--account-ids", "description": "Fetch specific accounts by IDs.", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor.", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "type": "boolean", "required": false } ], "category": "ad-accounts", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Fetch a single ad account by ID." }, "account_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific accounts by IDs." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "description": "Opaque pagination cursor." }, "refresh": { "type": "boolean", "default": false }, "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": "account_id", "type": "string", "required": false, "description": "Fetch a single ad account by ID." }, { "name": "account_ids", "type": "array", "required": false, "description": "Fetch specific accounts by IDs." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor." }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ad_accounts", "relationship": "cross-platform" }, { "name": "linkedin_ads_list_ad_accounts", "relationship": "cross-platform" }, { "name": "reddit_ads_list_campaigns", "relationship": "hierarchy" } ] }, { "name": "reddit_ads_list_ad_groups", "title": "List Reddit Ad Groups", "description": "List Reddit ad groups for an ad account. Shows targeting, bid strategy, and campaign association.", "cli_command": "hopkin reddit ad-groups list", "cli_flags": [ { "flag": "--account", "description": "Reddit ad account ID.", "type": "string", "required": true }, { "flag": "--ad-group-id", "description": "Fetch a single ad group by ID.", "type": "string", "required": false }, { "flag": "--ad-group-ids", "description": "Fetch specific ad groups by IDs.", "type": "array", "required": false }, { "flag": "--campaign", "description": "Filter by parent campaign ID.", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by status.", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor.", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "type": "boolean", "required": false } ], "category": "ad-groups", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Reddit ad account ID." }, "ad_group_id": { "type": "string", "description": "Fetch a single ad group by ID." }, "ad_group_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ad groups by IDs." }, "campaign_id": { "type": "string", "description": "Filter by parent campaign ID." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "description": "Filter by status." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "description": "Opaque pagination cursor." }, "refresh": { "type": "boolean", "default": false }, "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": "Reddit ad account ID.", "constraints": { "min_length": 1 } }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Fetch a single ad group by ID." }, { "name": "ad_group_ids", "type": "array", "required": false, "description": "Fetch specific ad groups by IDs." }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter by parent campaign ID." }, { "name": "status", "type": "array", "required": false, "description": "Filter by status." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor." }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "google_ads_list_ad_groups", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ads", "relationship": "hierarchy" }, { "name": "reddit_ads_list_campaigns", "relationship": "hierarchy" }, { "name": "tiktok_ads_list_ad_groups", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_list_ads", "title": "List Reddit Ads", "description": "List Reddit ads for an ad account. Shows creative type, headline, click URL, and status.", "cli_command": "hopkin reddit ads list", "cli_flags": [ { "flag": "--account", "description": "Reddit ad account ID.", "type": "string", "required": true }, { "flag": "--ad", "description": "Fetch a single ad by ID.", "type": "string", "required": false }, { "flag": "--ad-ids", "description": "Fetch specific ads by IDs.", "type": "array", "required": false }, { "flag": "--ad-group-id", "description": "Filter by parent ad group ID.", "type": "string", "required": false }, { "flag": "--status", "description": "Filter by status.", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor.", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "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": "Reddit ad account ID." }, "ad_id": { "type": "string", "description": "Fetch a single ad by ID." }, "ad_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ads by IDs." }, "ad_group_id": { "type": "string", "description": "Filter by parent ad group ID." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "description": "Filter by status." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "description": "Opaque pagination cursor." }, "refresh": { "type": "boolean", "default": false }, "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": "Reddit ad account ID.", "constraints": { "min_length": 1 } }, { "name": "ad_id", "type": "string", "required": false, "description": "Fetch a single ad by ID." }, { "name": "ad_ids", "type": "array", "required": false, "description": "Fetch specific ads by IDs." }, { "name": "ad_group_id", "type": "string", "required": false, "description": "Filter by parent ad group ID." }, { "name": "status", "type": "array", "required": false, "description": "Filter by status." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor." }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ads", "relationship": "cross-platform" }, { "name": "google_ads_list_ads", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ad_groups", "relationship": "hierarchy" }, { "name": "tiktok_ads_list_ads", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_check_auth_status", "title": "Check Reddit Ads Authentication Status", "description": "Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.", "cli_command": "hopkin reddit auth check", "cli_flags": [], "category": "auth", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "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": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "google_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "linkedin_ads_check_auth_status", "relationship": "cross-platform" }, { "name": "reddit_ads_ping", "relationship": "sibling" }, { "name": "tiktok_ads_check_auth_status", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_list_campaigns", "title": "List Reddit Campaigns", "description": "List Reddit ad campaigns for an ad account. Shows name, status, objective, and budget information.", "cli_command": "hopkin reddit campaigns list", "cli_flags": [ { "flag": "--account", "description": "Reddit ad account ID.", "type": "string", "required": true }, { "flag": "--campaign", "description": "Fetch a single campaign by ID.", "type": "string", "required": false }, { "flag": "--campaign-ids", "description": "Fetch specific campaigns by IDs.", "type": "array", "required": false }, { "flag": "--status", "description": "Filter by status.", "type": "array", "required": false }, { "flag": "--search", "description": "Search by campaign name (case-insensitive).", "type": "string", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor.", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "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": "Reddit ad account ID." }, "campaign_id": { "type": "string", "description": "Fetch a single campaign by ID." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific campaigns by IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "description": "Filter by status." }, "search": { "type": "string", "description": "Search by campaign name (case-insensitive)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "description": "Opaque pagination cursor." }, "refresh": { "type": "boolean", "default": false }, "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": "Reddit ad account ID.", "constraints": { "min_length": 1 } }, { "name": "campaign_id", "type": "string", "required": false, "description": "Fetch a single campaign by ID." }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Fetch specific campaigns by IDs." }, { "name": "status", "type": "array", "required": false, "description": "Filter by status." }, { "name": "search", "type": "string", "required": false, "description": "Search by campaign name (case-insensitive)." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor." }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "google_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "linkedin_ads_list_campaigns", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ad_accounts", "relationship": "hierarchy" }, { "name": "reddit_ads_list_ad_groups", "relationship": "hierarchy" }, { "name": "tiktok_ads_list_campaigns", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_list_custom_audiences", "title": "List Reddit Custom Audiences", "description": "List Reddit custom audiences for an ad account. Shows name, type, size, and status.", "cli_command": "hopkin reddit custom-audiences list", "cli_flags": [ { "flag": "--account", "description": "Reddit ad account ID.", "type": "string", "required": true }, { "flag": "--audience-id", "description": "Fetch a single custom audience by ID.", "type": "string", "required": false }, { "flag": "--audience-ids", "description": "Fetch specific audiences by IDs.", "type": "array", "required": false }, { "flag": "--limit", "description": "", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor.", "type": "string", "required": false }, { "flag": "--refresh", "description": "", "type": "boolean", "required": false } ], "category": "custom-audiences", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Reddit ad account ID." }, "audience_id": { "type": "string", "description": "Fetch a single custom audience by ID." }, "audience_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific audiences by IDs." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "description": "Opaque pagination cursor." }, "refresh": { "type": "boolean", "default": false }, "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": "Reddit ad account ID.", "constraints": { "min_length": 1 } }, { "name": "audience_id", "type": "string", "required": false, "description": "Fetch a single custom audience by ID." }, { "name": "audience_ids", "type": "array", "required": false, "description": "Fetch specific audiences by IDs." }, { "name": "limit", "type": "integer", "required": false, "description": "", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor." }, { "name": "refresh", "type": "boolean", "required": false, "description": "", "default": false }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [] }, { "name": "reddit_ads_developer_feedback", "title": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the Reddit Ads MCP toolset. Not for user-facing issues like auth or API errors.", "cli_command": "hopkin reddit 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 ad group status toggle", "description": "Need to pause/enable multiple ad groups at once rather than one by one", "priority": "high", "reason": "User asked to pause 10 ad groups individually" }, "cli_command": "hopkin reddit developer-feedback send --feedback-type new_tool --title Bulk ad group status toggle --description Need to pause/enable multiple ad groups at once rather than one by one --priority high", "natural_language": "Missing tool" }, { "label": "Workflow gap", "mcp_params": { "feedback_type": "workflow_gap", "title": "Campaign cloning with ad groups", "description": "No way to duplicate a campaign including all ad groups and ads", "current_workaround": "Read and recreate each level one by one", "reason": "User wanted to duplicate campaign structure" }, "cli_command": "hopkin reddit developer-feedback send --feedback-type workflow_gap --title Campaign cloning with ad groups --description No way to duplicate a campaign including all ad groups and ads --current-workaround Read and recreate each level one by one", "natural_language": "Workflow gap" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "google_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "linkedin_ads_developer_feedback", "relationship": "cross-platform" }, { "name": "tiktok_ads_developer_feedback", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_ping", "title": "Ping Reddit Ads MCP Server", "description": "Health check for the Reddit Ads MCP server.", "cli_command": "hopkin reddit 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 reddit ping", "natural_language": "Health check" }, { "label": "With message", "mcp_params": { "message": "hello", "reason": "Test connectivity" }, "cli_command": "hopkin reddit ping --message hello", "natural_language": "With message" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_ping", "relationship": "cross-platform" }, { "name": "google_ads_ping", "relationship": "cross-platform" }, { "name": "linkedin_ads_ping", "relationship": "cross-platform" }, { "name": "reddit_ads_check_auth_status", "relationship": "sibling" }, { "name": "tiktok_ads_ping", "relationship": "cross-platform" } ] }, { "name": "reddit_ads_store_preference", "title": "Store Reddit Ads Preference", "description": "Store a persistent preference for a Reddit ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.", "cli_command": "hopkin reddit 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": "t2_123", "key": "preferred_conversion_metric", "value": "ROAS", "reason": "User wants ROAS as default metric" }, "cli_command": "hopkin reddit preferences store --entity-type ad_account --entity-id t2_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 reddit 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_store_preference", "relationship": "cross-platform" }, { "name": "google_ads_store_preference", "relationship": "cross-platform" }, { "name": "linkedin_ads_store_preference", "relationship": "cross-platform" }, { "name": "reddit_ads_get_preferences", "relationship": "sibling" }, { "name": "reddit_ads_delete_preference", "relationship": "sibling" } ] }, { "name": "reddit_ads_get_preferences", "title": "Get Reddit Ads Preferences", "description": "Get all stored preferences for a Reddit ad entity. Preferences are also auto-attached to list tool responses as _stored_preferences.", "cli_command": "hopkin reddit 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": "t2_123", "reason": "Check stored preferences" }, "cli_command": "hopkin reddit preferences get --entity-type ad_account --entity-id t2_123", "natural_language": "Get prefs" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_get_preferences", "relationship": "cross-platform" }, { "name": "google_ads_get_preferences", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_preferences", "relationship": "cross-platform" }, { "name": "reddit_ads_store_preference", "relationship": "sibling" }, { "name": "reddit_ads_delete_preference", "relationship": "sibling" } ] }, { "name": "reddit_ads_delete_preference", "title": "Delete Reddit Ads Preference", "description": "Delete a stored preference by key. No-op if it doesn't exist.", "cli_command": "hopkin reddit 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 reddit preference delete --entity-type campaign --entity-id 456 --key budget_alert_threshold", "natural_language": "Delete pref" } ], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_delete_preference", "relationship": "cross-platform" }, { "name": "google_ads_delete_preference", "relationship": "cross-platform" }, { "name": "linkedin_ads_delete_preference", "relationship": "cross-platform" }, { "name": "reddit_ads_store_preference", "relationship": "sibling" }, { "name": "reddit_ads_get_preferences", "relationship": "sibling" } ] }, { "name": "reddit_ads_get_performance_report", "title": "Get Reddit Ads Performance Report", "description": "Get a performance report for a Reddit ad account over a date range, with optional breakdowns and entity filters.", "cli_command": "hopkin reddit performance-report get", "cli_flags": [ { "flag": "--account", "description": "Reddit ad account ID.", "type": "string", "required": true }, { "flag": "--campaign-ids", "description": "Filter to specific campaign IDs.", "type": "array", "required": false }, { "flag": "--ad-group-ids", "description": "Filter to specific ad group IDs.", "type": "array", "required": false }, { "flag": "--ad-ids", "description": "Filter to specific ad IDs.", "type": "array", "required": false }, { "flag": "--date-start", "description": "Start date in YYYY-MM-DD format.", "type": "string", "required": true }, { "flag": "--date-end", "description": "End date in YYYY-MM-DD format.", "type": "string", "required": true }, { "flag": "--breakdown", "description": "Up to 3 breakdown dimensions. \"community\" shows subreddit-level data.", "type": "array", "required": false } ], "category": "reporting", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Reddit ad account ID." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific campaign IDs." }, "ad_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific ad group IDs." }, "ad_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific ad IDs." }, "date_start": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "date_end": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "breakdown": { "type": "array", "items": { "type": "string", "enum": [ "campaign", "ad_group", "ad", "community", "date", "country", "region", "placement", "device_os" ] }, "maxItems": 3, "description": "Up to 3 breakdown dimensions. \"community\" shows subreddit-level data." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "date_start", "date_end", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "account_id", "type": "string", "required": true, "description": "Reddit ad account ID.", "constraints": { "min_length": 1 } }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Filter to specific campaign IDs." }, { "name": "ad_group_ids", "type": "array", "required": false, "description": "Filter to specific ad group IDs." }, { "name": "ad_ids", "type": "array", "required": false, "description": "Filter to specific ad IDs." }, { "name": "date_start", "type": "string", "required": true, "description": "Start date in YYYY-MM-DD format." }, { "name": "date_end", "type": "string", "required": true, "description": "End date in YYYY-MM-DD format." }, { "name": "breakdown", "type": "array", "required": false, "description": "Up to 3 breakdown dimensions. \"community\" shows subreddit-level data." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "google_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_performance_report", "relationship": "cross-platform" }, { "name": "tiktok_ads_get_performance_report", "relationship": "cross-platform" } ] } ] }, { "id": "tiktok-ads", "name": "TikTok Ads", "description": "TikTok Marketing API for short-form video advertising", "tool_count": 17, "mcpUrl": "https://mcp.hopkin.ai/tiktok-ads/mcp", "tools": [ { "name": "tiktok_ads_list_ad_groups", "title": "List TikTok Ad Groups", "description": "List TikTok ad groups for an advertiser. Shows name, status, targeting, and budget.", "cli_command": "hopkin tiktok ad-groups list", "cli_flags": [ { "flag": "--limit", "description": "Maximum number of results to return (1–100). Default: 20.", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor from a previous response.", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force a fresh fetch bypassing the cache.", "type": "boolean", "required": false }, { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--adgroup-id", "description": "Fetch a single ad group by ID.", "type": "string", "required": false }, { "flag": "--adgroup-ids", "description": "Fetch specific ad groups by IDs.", "type": "array", "required": false }, { "flag": "--campaign-ids", "description": "Filter by parent campaign IDs.", "type": "array", "required": false }, { "flag": "--status", "description": "Filter by primary status.", "type": "array", "required": false }, { "flag": "--search", "description": "Search ad groups by name (case-insensitive).", "type": "string", "required": false } ], "category": "ad-groups", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "adgroup_id": { "type": "string", "description": "Fetch a single ad group by ID." }, "adgroup_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ad groups by IDs." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter by parent campaign IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "STATUS_ALL", "STATUS_ON", "STATUS_OFF", "STATUS_BUDGET_EXCEED", "STATUS_DONE", "STATUS_DELETE" ] }, "description": "Filter by primary status." }, "search": { "type": "string", "description": "Search ad groups by name (case-insensitive)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of results to return (1–100). Default: 20.", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor from a previous response." }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force a fresh fetch bypassing the cache.", "default": false }, { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "adgroup_id", "type": "string", "required": false, "description": "Fetch a single ad group by ID." }, { "name": "adgroup_ids", "type": "array", "required": false, "description": "Fetch specific ad groups by IDs." }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Filter by parent campaign IDs." }, { "name": "status", "type": "array", "required": false, "description": "Filter by primary status." }, { "name": "search", "type": "string", "required": false, "description": "Search ad groups by name (case-insensitive)." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "google_ads_list_ad_groups", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ad_groups", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_ads", "relationship": "hierarchy" }, { "name": "tiktok_ads_list_campaigns", "relationship": "hierarchy" } ] }, { "name": "tiktok_ads_get_ad_group", "title": "Get TikTok Ad Group", "description": "Get details for a single TikTok ad group by ID.", "cli_command": "hopkin tiktok ad-group get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--adgroup-id", "description": "Ad group ID.", "type": "string", "required": true } ], "category": "ad-group", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "adgroup_id": { "type": "string", "minLength": 1, "description": "Ad group ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "adgroup_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "adgroup_id", "type": "string", "required": true, "description": "Ad group 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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_list_ads", "title": "List TikTok Ads", "description": "List TikTok ads for an advertiser. Shows name, status, creative, and ad group association.", "cli_command": "hopkin tiktok ads list", "cli_flags": [ { "flag": "--limit", "description": "Maximum number of results to return (1–100). Default: 20.", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor from a previous response.", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force a fresh fetch bypassing the cache.", "type": "boolean", "required": false }, { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--ad", "description": "Fetch a single ad by ID.", "type": "string", "required": false }, { "flag": "--ad-ids", "description": "Fetch specific ads by IDs.", "type": "array", "required": false }, { "flag": "--campaign-ids", "description": "Filter by parent campaign IDs.", "type": "array", "required": false }, { "flag": "--adgroup-ids", "description": "Filter by parent ad group IDs.", "type": "array", "required": false }, { "flag": "--status", "description": "Filter by primary status.", "type": "array", "required": false }, { "flag": "--search", "description": "Search ads by name (case-insensitive).", "type": "string", "required": false } ], "category": "ads", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "ad_id": { "type": "string", "description": "Fetch a single ad by ID." }, "ad_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ads by IDs." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter by parent campaign IDs." }, "adgroup_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter by parent ad group IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "STATUS_ALL", "STATUS_ON", "STATUS_OFF", "STATUS_BUDGET_EXCEED", "STATUS_DONE", "STATUS_DELETE" ] }, "description": "Filter by primary status." }, "search": { "type": "string", "description": "Search ads by name (case-insensitive)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of results to return (1–100). Default: 20.", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor from a previous response." }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force a fresh fetch bypassing the cache.", "default": false }, { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "ad_id", "type": "string", "required": false, "description": "Fetch a single ad by ID." }, { "name": "ad_ids", "type": "array", "required": false, "description": "Fetch specific ads by IDs." }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Filter by parent campaign IDs." }, { "name": "adgroup_ids", "type": "array", "required": false, "description": "Filter by parent ad group IDs." }, { "name": "status", "type": "array", "required": false, "description": "Filter by primary status." }, { "name": "search", "type": "string", "required": false, "description": "Search ads by name (case-insensitive)." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_ads", "relationship": "cross-platform" }, { "name": "google_ads_list_ads", "relationship": "cross-platform" }, { "name": "reddit_ads_list_ads", "relationship": "cross-platform" }, { "name": "tiktok_ads_list_ad_groups", "relationship": "hierarchy" } ] }, { "name": "tiktok_ads_get_ad", "title": "Get TikTok Ad", "description": "Get details for a single TikTok ad by ID.", "cli_command": "hopkin tiktok ad get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--ad", "description": "Ad ID.", "type": "string", "required": true } ], "category": "ad", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "ad_id": { "type": "string", "minLength": 1, "description": "Ad ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "ad_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "ad_id", "type": "string", "required": true, "description": "Ad 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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_list_advertisers", "title": "List TikTok Advertisers", "description": "List TikTok advertiser accounts accessible to the authenticated user. Shows name, ID, status, currency, and timezone.", "cli_command": "hopkin tiktok advertisers list", "cli_flags": [ { "flag": "--limit", "description": "Maximum number of results to return (1–100). Default: 20.", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor from a previous response.", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force a fresh fetch bypassing the cache.", "type": "boolean", "required": false }, { "flag": "--advertiser-id", "description": "Fetch a single advertiser by ID.", "type": "string", "required": false } ], "category": "advertisers", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "description": "Fetch a single advertiser by ID." }, "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": "limit", "type": "integer", "required": false, "description": "Maximum number of results to return (1–100). Default: 20.", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor from a previous response." }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force a fresh fetch bypassing the cache.", "default": false }, { "name": "advertiser_id", "type": "string", "required": false, "description": "Fetch a single advertiser by ID." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_get_advertiser", "title": "Get TikTok Advertiser", "description": "Get details for a single TikTok advertiser by ID.", "cli_command": "hopkin tiktok advertiser get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true } ], "category": "advertiser", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser 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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_list_audiences", "title": "List TikTok Audiences", "description": "List custom and lookalike audiences for a TikTok advertiser.", "cli_command": "hopkin tiktok audiences list", "cli_flags": [ { "flag": "--limit", "description": "Maximum number of results to return (1–100). Default: 20.", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor from a previous response.", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force a fresh fetch bypassing the cache.", "type": "boolean", "required": false }, { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true } ], "category": "audiences", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of results to return (1–100). Default: 20.", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor from a previous response." }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force a fresh fetch bypassing the cache.", "default": false }, { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser 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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_check_auth_status", "title": "Check TikTok Ads Authentication Status", "description": "Check whether the user's TikTok Ads account is authenticated. Returns auth method and email. Use ONLY when the user asks about auth status or connectivity — to get advertiser accounts, use tiktok_ads_list_advertisers instead.", "cli_command": "hopkin tiktok auth check", "cli_flags": [], "category": "auth", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "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": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_check_auth_status", "relationship": "cross-platform" }, { "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_ping", "relationship": "sibling" } ] }, { "name": "tiktok_ads_get_login_url", "title": "Get TikTok Ads Login URL", "description": "Get the URL to connect a TikTok Ads account via OAuth.", "cli_command": "hopkin tiktok login-url get", "cli_flags": [], "category": "login-url", "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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_get_user_info", "title": "Get TikTok Ads User Info", "description": "Get detailed profile information about the authenticated TikTok Ads user (email, display name, role). Use this for user profile details — for checking auth status or listing advertiser IDs, use tiktok_ads_check_auth_status instead.", "cli_command": "hopkin tiktok user-info get", "cli_flags": [], "category": "user-info", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_list_campaigns", "title": "List TikTok Campaigns", "description": "List TikTok ad campaigns for an advertiser. Shows name, status, objective, and budget.", "cli_command": "hopkin tiktok campaigns list", "cli_flags": [ { "flag": "--limit", "description": "Maximum number of results to return (1–100). Default: 20.", "type": "integer", "required": false }, { "flag": "--cursor", "description": "Opaque pagination cursor from a previous response.", "type": "string", "required": false }, { "flag": "--refresh", "description": "Force a fresh fetch bypassing the cache.", "type": "boolean", "required": false }, { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--campaign", "description": "Fetch a single campaign by ID.", "type": "string", "required": false }, { "flag": "--campaign-ids", "description": "Fetch specific campaigns by IDs.", "type": "array", "required": false }, { "flag": "--status", "description": "Filter by primary status.", "type": "array", "required": false }, { "flag": "--search", "description": "Search campaigns by name (case-insensitive).", "type": "string", "required": false } ], "category": "campaigns", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "campaign_id": { "type": "string", "description": "Fetch a single campaign by ID." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific campaigns by IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "STATUS_ALL", "STATUS_ON", "STATUS_OFF", "STATUS_BUDGET_EXCEED", "STATUS_DONE", "STATUS_DELETE" ] }, "description": "Filter by primary status." }, "search": { "type": "string", "description": "Search campaigns by name (case-insensitive)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of results to return (1–100). Default: 20.", "default": 20, "constraints": { "min": 1, "max": 100 } }, { "name": "cursor", "type": "string", "required": false, "description": "Opaque pagination cursor from a previous response." }, { "name": "refresh", "type": "boolean", "required": false, "description": "Force a fresh fetch bypassing the cache.", "default": false }, { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "campaign_id", "type": "string", "required": false, "description": "Fetch a single campaign by ID." }, { "name": "campaign_ids", "type": "array", "required": false, "description": "Fetch specific campaigns by IDs." }, { "name": "status", "type": "array", "required": false, "description": "Filter by primary status." }, { "name": "search", "type": "string", "required": false, "description": "Search campaigns by name (case-insensitive)." }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_list_campaigns", "relationship": "cross-platform" }, { "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_ad_groups", "relationship": "hierarchy" } ] }, { "name": "tiktok_ads_get_campaign", "title": "Get TikTok Campaign", "description": "Get details for a single TikTok campaign by ID.", "cli_command": "hopkin tiktok campaign get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--campaign", "description": "Campaign ID.", "type": "string", "required": true } ], "category": "campaign", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Campaign ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "campaign_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "campaign_id", "type": "string", "required": true, "description": "Campaign 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": [], "response_format": "markdown", "related_tools": [] }, { "name": "tiktok_ads_developer_feedback", "title": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the TikTok Ads MCP toolset. Not for user-facing issues like auth or API errors.", "cli_command": "hopkin tiktok 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": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_developer_feedback", "relationship": "cross-platform" }, { "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_ping", "title": "Ping TikTok Ads MCP Server", "description": "Health check for the TikTok Ads MCP server.", "cli_command": "hopkin tiktok 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": [], "response_format": "markdown", "related_tools": [ { "name": "meta_ads_ping", "relationship": "cross-platform" }, { "name": "google_ads_ping", "relationship": "cross-platform" }, { "name": "linkedin_ads_ping", "relationship": "cross-platform" }, { "name": "reddit_ads_ping", "relationship": "cross-platform" }, { "name": "tiktok_ads_check_auth_status", "relationship": "sibling" } ] }, { "name": "tiktok_ads_get_performance_report", "title": "Get TikTok Ads Performance Report", "description": "Get a performance report for a TikTok advertiser over a date range, with optional breakdowns and entity filters.", "cli_command": "hopkin tiktok performance-report get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--level", "description": "Reporting level — mapped to data_level internally.", "type": "string", "required": true }, { "flag": "--date-preset", "description": "Shortcut date range. Overridden by explicit start_date/end_date.", "type": "string", "required": false }, { "flag": "--start-date", "description": "Start date in YYYY-MM-DD format.", "type": "string", "required": false }, { "flag": "--end-date", "description": "End date in YYYY-MM-DD format.", "type": "string", "required": false }, { "flag": "--campaign", "description": "Filter to a specific campaign.", "type": "string", "required": false }, { "flag": "--adgroup-id", "description": "Filter to a specific ad group.", "type": "string", "required": false }, { "flag": "--page", "description": "Page number (1-indexed). Default: 1.", "type": "integer", "required": false }, { "flag": "--page-size", "description": "Results per page. Default: 20.", "type": "integer", "required": false } ], "category": "reporting", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "level": { "type": "string", "enum": [ "campaign", "adgroup", "ad" ], "description": "Reporting level — mapped to data_level internally." }, "date_preset": { "type": "string", "enum": [ "last_7d", "last_14d", "last_30d" ], "description": "Shortcut date range. Overridden by explicit start_date/end_date." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "campaign_id": { "type": "string", "description": "Filter to a specific campaign." }, "adgroup_id": { "type": "string", "description": "Filter to a specific ad group." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "level", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "level", "type": "string", "required": true, "description": "Reporting level — mapped to data_level internally.", "enum_values": [ "campaign", "adgroup", "ad" ] }, { "name": "date_preset", "type": "string", "required": false, "description": "Shortcut date range. Overridden by explicit start_date/end_date.", "enum_values": [ "last_7d", "last_14d", "last_30d" ] }, { "name": "start_date", "type": "string", "required": false, "description": "Start date in YYYY-MM-DD format." }, { "name": "end_date", "type": "string", "required": false, "description": "End date in YYYY-MM-DD format." }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign." }, { "name": "adgroup_id", "type": "string", "required": false, "description": "Filter to a specific ad group." }, { "name": "page", "type": "integer", "required": false, "description": "Page number (1-indexed). Default: 1.", "default": 1, "constraints": { "min": 1 } }, { "name": "page_size", "type": "integer", "required": false, "description": "Results per page. Default: 20.", "default": 20, "constraints": { "min": 1, "max": 1000 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_performance_report", "relationship": "cross-platform" }, { "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_insights", "title": "Get TikTok Ads Insights", "description": "Get aggregated insights and analytics for TikTok ad entities with custom dimensions (age, gender, country, placement). Use this for audience demographic breakdowns and flexible dimension-based analysis — for video/creative metrics, use tiktok_ads_get_creative_report instead.", "cli_command": "hopkin tiktok insights get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--report-type", "description": "Type of report. AUDIENCE for demographic breakdowns (age, gender, country). Default: BASIC.", "type": "string", "required": false }, { "flag": "--data-level", "description": "Granularity level for the report.", "type": "string", "required": true }, { "flag": "--dimensions", "description": "Grouping dimensions, e.g. [\"campaign_id\", \"stat_time_day\"].", "type": "array", "required": true }, { "flag": "--metrics", "description": "Metrics to retrieve. Defaults to standard funnel metrics if omitted.", "type": "array", "required": false }, { "flag": "--start-date", "description": "Start date in YYYY-MM-DD format.", "type": "string", "required": false }, { "flag": "--end-date", "description": "End date in YYYY-MM-DD format.", "type": "string", "required": false }, { "flag": "--lifetime", "description": "If true, return lifetime metrics instead of date-ranged.", "type": "boolean", "required": false }, { "flag": "--page", "description": "Page number (1-indexed). Default: 1.", "type": "integer", "required": false }, { "flag": "--page-size", "description": "Results per page. Default: 20.", "type": "integer", "required": false } ], "category": "insights", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "report_type": { "type": "string", "enum": [ "BASIC", "AUDIENCE" ], "default": "BASIC", "description": "Type of report. AUDIENCE for demographic breakdowns (age, gender, country). Default: BASIC." }, "data_level": { "type": "string", "enum": [ "AUCTION_ADVERTISER", "AUCTION_CAMPAIGN", "AUCTION_ADGROUP", "AUCTION_AD" ], "description": "Granularity level for the report." }, "dimensions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Grouping dimensions, e.g. [\"campaign_id\", \"stat_time_day\"]." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "Metrics to retrieve. Defaults to standard funnel metrics if omitted." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "lifetime": { "type": "boolean", "description": "If true, return lifetime metrics instead of date-ranged." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "data_level", "dimensions", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "report_type", "type": "string", "required": false, "description": "Type of report. AUDIENCE for demographic breakdowns (age, gender, country). Default: BASIC.", "enum_values": [ "BASIC", "AUDIENCE" ], "default": "BASIC" }, { "name": "data_level", "type": "string", "required": true, "description": "Granularity level for the report.", "enum_values": [ "AUCTION_ADVERTISER", "AUCTION_CAMPAIGN", "AUCTION_ADGROUP", "AUCTION_AD" ] }, { "name": "dimensions", "type": "array", "required": true, "description": "Grouping dimensions, e.g. [\"campaign_id\", \"stat_time_day\"]." }, { "name": "metrics", "type": "array", "required": false, "description": "Metrics to retrieve. Defaults to standard funnel metrics if omitted." }, { "name": "start_date", "type": "string", "required": false, "description": "Start date in YYYY-MM-DD format." }, { "name": "end_date", "type": "string", "required": false, "description": "End date in YYYY-MM-DD format." }, { "name": "lifetime", "type": "boolean", "required": false, "description": "If true, return lifetime metrics instead of date-ranged." }, { "name": "page", "type": "integer", "required": false, "description": "Page number (1-indexed). Default: 1.", "default": 1, "constraints": { "min": 1 } }, { "name": "page_size", "type": "integer", "required": false, "description": "Results per page. Default: 20.", "default": 20, "constraints": { "min": 1, "max": 1000 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "json", "related_tools": [ { "name": "meta_ads_get_insights", "relationship": "cross-platform" }, { "name": "google_ads_get_insights", "relationship": "cross-platform" }, { "name": "linkedin_ads_get_insights", "relationship": "cross-platform" } ] }, { "name": "tiktok_ads_get_creative_report", "title": "Get TikTok Ads Creative Report", "description": "Get video creative performance metrics for TikTok ads — video views, watch time, completion rates (p25/p50/p75/p100), engagement, and per-creative breakdowns. Supports filtering by campaign_id or adgroup_id to narrow results. Use this tool for video-specific metrics and creative-level analysis.", "cli_command": "hopkin tiktok creative-report get", "cli_flags": [ { "flag": "--advertiser-id", "description": "TikTok advertiser ID.", "type": "string", "required": true }, { "flag": "--campaign", "description": "Filter to a specific campaign.", "type": "string", "required": false }, { "flag": "--adgroup-id", "description": "Filter to a specific ad group.", "type": "string", "required": false }, { "flag": "--start-date", "description": "Start date in YYYY-MM-DD format.", "type": "string", "required": false }, { "flag": "--end-date", "description": "End date in YYYY-MM-DD format.", "type": "string", "required": false }, { "flag": "--page", "description": "Page number (1-indexed). Default: 1.", "type": "integer", "required": false }, { "flag": "--page-size", "description": "Results per page. Default: 20.", "type": "integer", "required": false } ], "category": "creative-report", "annotations": { "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "inputSchema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "campaign_id": { "type": "string", "description": "Filter to a specific campaign." }, "adgroup_id": { "type": "string", "description": "Filter to a specific ad group." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "parameters": [ { "name": "advertiser_id", "type": "string", "required": true, "description": "TikTok advertiser ID.", "constraints": { "min_length": 1 } }, { "name": "campaign_id", "type": "string", "required": false, "description": "Filter to a specific campaign." }, { "name": "adgroup_id", "type": "string", "required": false, "description": "Filter to a specific ad group." }, { "name": "start_date", "type": "string", "required": false, "description": "Start date in YYYY-MM-DD format." }, { "name": "end_date", "type": "string", "required": false, "description": "End date in YYYY-MM-DD format." }, { "name": "page", "type": "integer", "required": false, "description": "Page number (1-indexed). Default: 1.", "default": 1, "constraints": { "min": 1 } }, { "name": "page_size", "type": "integer", "required": false, "description": "Results per page. Default: 20.", "default": 20, "constraints": { "min": 1, "max": 1000 } }, { "name": "reason", "type": "string", "required": true, "description": "Why this tool call is needed", "constraints": { "min_length": 1, "max_length": 500 } } ], "examples": [], "response_format": "markdown", "related_tools": [] } ] } ] }