[ { "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" } ] } ]