{ "openapi": "3.1.0", "info": { "title": "Google Ads MCP Server", "description": "Google Ads campaign management with GAQL query support", "version": "1.0.0", "contact": { "name": "Hopkin", "url": "https://hopkin.ai" } }, "servers": [ { "url": "https://google.mcp.hopkin.ai", "description": "Production MCP endpoint" } ], "paths": { "/tools": { "get": { "operationId": "listTools", "summary": "List available tools", "description": "Returns all tools registered on this server with their names, descriptions, and input schemas.", "tags": [ "discovery" ], "responses": { "200": { "description": "Tool list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } } } } }, "/tools/google_ads_get_account_summary": { "post": { "operationId": "google_ads_get_account_summary", "summary": "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 plus the supported Demand Gen Platform Comparable conversion family, with per-conversion-action breakdown. Preferred over insights or performance report for quick account overviews. Always fetches fresh data.", "tags": [ "account-summary" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "last-30-days-summary": { "summary": "Last 30 days summary", "value": { "customer_id": "1234567890", "reason": "Quick performance overview" } }, "last-7-days": { "summary": "Last 7 days", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Weekly check-in" } }, "with-mcc": { "summary": "With MCC", "value": { "customer_id": "1234567890", "login_customer_id": "9876543210", "date_preset": "LAST_30_DAYS", "reason": "Managed account overview" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_activities": { "post": { "operationId": "google_ads_get_activities", "summary": "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.", "tags": [ "activities" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "recent-account-activity": { "summary": "Recent account activity", "value": { "customer_id": "1234567890", "reason": "Review recent account changes" } }, "campaign-changes-only": { "summary": "Campaign changes only", "value": { "customer_id": "1234567890", "resource_type": "CAMPAIGN", "reason": "See recent campaign edits" } }, "custom-date-range": { "summary": "Custom date range", "value": { "customer_id": "1234567890", "start_date": "2026-02-01", "end_date": "2026-02-28", "reason": "February activity audit" } }, "with-mcc-login": { "summary": "With MCC login", "value": { "customer_id": "1234567890", "login_customer_id": "9876543210", "reason": "Review changes on managed account" } }, "specific-asset-activity": { "summary": "Specific asset activity", "value": { "customer_id": "1234567890", "asset_ids": [ "123456789", "987654321" ], "reason": "Check recent changes to specific assets" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_accounts": { "post": { "operationId": "google_ads_list_accounts", "summary": "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.", "tags": [ "accounts" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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)" }, "label_filter": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Filter by labels. Accepts an array whose entries are any of: label name (e.g. \"Big Boom\"), bare label ID (e.g. \"9876543210\"), or full label resource name (e.g. \"customers/1234567890/labels/9876543210\"). Names are resolved against cached labels for the relevant customer scope. Unknown names return an empty result with a warning rather than an error." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "list-all": { "summary": "List all", "value": { "reason": "List all ad accounts" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "reason": "Get account details" } }, "search-by-name": { "summary": "Search by name", "value": { "search": "marketing", "reason": "Find marketing accounts" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_ids": [ "1234567890", "0987654321" ], "reason": "Get details for specific accounts" } }, "force-refresh": { "summary": "Force refresh", "value": { "refresh": true, "reason": "Get fresh data" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_mcc_child_accounts": { "post": { "operationId": "google_ads_list_mcc_child_accounts", "summary": "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.", "tags": [ "mcc-child-accounts" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch of labels for this MCC scope. Defaults to false (cache-first)." }, "label_filter": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Filter by labels. Accepts an array whose entries are any of: label name (e.g. \"Big Boom\"), bare label ID (e.g. \"9876543210\"), or full label resource name (e.g. \"customers/1234567890/labels/9876543210\"). Names are resolved against cached labels for the relevant customer scope. Unknown names return an empty result with a warning rather than an error." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "list-children": { "summary": "List children", "value": { "mcc_id": "1234567890", "reason": "List MCC child accounts" } }, "search-children": { "summary": "Search children", "value": { "mcc_id": "1234567890", "search": "marketing", "reason": "Find child accounts" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_ad_groups": { "post": { "operationId": "google_ads_list_ad_groups", "summary": "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. Set include_audience_criteria=true to include ad-group-level audience targeting (USER_LIST, USER_INTEREST) with bid modifiers.", "tags": [ "ad-groups" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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." }, "include_audience_criteria": { "type": "boolean", "default": false, "description": "Include ad-group-level audience criteria (USER_LIST, USER_INTEREST) with bid modifiers. Useful for auditing RLSA audiences and observation/targeting mode." }, "label_filter": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Filter by labels. Accepts an array whose entries are any of: label name (e.g. \"Big Boom\"), bare label ID (e.g. \"9876543210\"), or full label resource name (e.g. \"customers/1234567890/labels/9876543210\"). Names are resolved against cached labels for the relevant customer scope. Unknown names return an empty result with a warning rather than an error." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "List ad groups" } }, "filter-by-campaign": { "summary": "Filter by campaign", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "reason": "List ad groups in campaign" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "ad_group_id": "5555555555", "reason": "Get ad group details" } }, "search": { "summary": "Search", "value": { "customer_id": "1234567890", "search": "brand", "reason": "Find brand ad groups" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_id": "1234567890", "ad_group_ids": [ "111", "222", "333" ], "reason": "Get details for specific ad groups" } }, "filter-by-status": { "summary": "Filter by status", "value": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled ad groups" } }, "with-audiences": { "summary": "With audiences", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "include_audience_criteria": true, "reason": "Audit RLSA audiences" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_preview_ads": { "post": { "operationId": "google_ads_preview_ads", "summary": "Preview Google Ads", "description": "Interactive UI for displaying Google ad previews with creative content and metrics", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads customer ID" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC manager account ID if needed" }, "ads": { "type": "array", "items": { "type": "object", "properties": { "ad_id": { "type": "string", "pattern": "^\\d+$", "description": "The Google ad ID" }, "metrics": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] }, "description": "Metric name-value pairs to display" } }, "required": [ "ad_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "Ads to preview (1-20)" }, "metric_labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Display labels for metric keys" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "ads", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "single-ad": { "summary": "Single ad", "value": { "customer_id": "1234567890", "ads": [ { "ad_id": "12345" } ], "reason": "Preview ad creative" } }, "with-metrics": { "summary": "With metrics", "value": { "customer_id": "1234567890", "ads": [ { "ad_id": "12345", "metrics": { "spend": "150.00", "ctr": "2.5%" } } ], "metric_labels": { "spend": "Spend", "ctr": "Click Rate" }, "reason": "Preview ad with performance metrics" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } }, "x-mcp-tool-type": "app" } }, "/tools/google_ads_list_ads": { "post": { "operationId": "google_ads_list_ads", "summary": "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.", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "List ads" } }, "filter-by-ad-group": { "summary": "Filter by ad group", "value": { "customer_id": "1234567890", "ad_group_id": "5555555555", "reason": "List ads in ad group" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "ad_id": "7777777777", "reason": "Get ad details" } }, "search": { "summary": "Search", "value": { "customer_id": "1234567890", "search": "promo", "reason": "Find promo ads" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_id": "1234567890", "ad_ids": [ "111", "222", "333" ], "reason": "Get details for specific ads" } }, "filter-by-status": { "summary": "Filter by status", "value": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled ads" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_audiences": { "post": { "operationId": "google_ads_list_audiences", "summary": "List Google Ads Audiences", "description": "List audience lists (user lists) for a Google Ads account. Returns Customer Match lists, remarketing audiences, rule-based audiences, similar audiences, and lookalike segments. Shows list names, types, sizes (for Search and Display), membership status, and match rates. Supports filtering by type and membership status, plus name search.", "tags": [ "audiences" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "type": { "type": "array", "items": { "type": "string", "enum": [ "CRM_BASED", "REMARKETING", "LOGICAL_USER_LIST", "EXTERNAL_REMARKETING", "RULE_BASED", "SIMILAR", "LOOKALIKE" ] }, "description": "Filter by audience type(s). Examples: CRM_BASED, REMARKETING, RULE_BASED, LOOKALIKE" }, "membership_status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "Filter by membership status: OPEN (accepting new members) or CLOSED" }, "search": { "type": "string", "description": "Case-insensitive search filter applied to audience list names" }, "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "all-audiences": { "summary": "All audiences", "value": { "customer_id": "1234567890", "reason": "Audit all audience lists on the account" } }, "customer-match-only": { "summary": "Customer Match only", "value": { "customer_id": "1234567890", "type": [ "CRM_BASED" ], "reason": "View Customer Match lists and match rates" } }, "search-by-name": { "summary": "Search by name", "value": { "customer_id": "1234567890", "search": "remarketing", "reason": "Find remarketing audiences by name" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_check_auth_status": { "post": { "operationId": "google_ads_check_auth_status", "summary": "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.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "check-auth": { "summary": "Check auth", "value": { "reason": "Another tool returned an auth error, checking account connection status" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_auto_applied_recommendations": { "post": { "operationId": "google_ads_get_auto_applied_recommendations", "summary": "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.", "tags": [ "auto-applied-recommendations" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "check-auto-applied": { "summary": "Check auto-applied", "value": { "customer_id": "1234567890", "reason": "Audit auto-applied recommendation settings" } }, "mcc-account": { "summary": "MCC account", "value": { "customer_id": "1234567890", "login_customer_id": "9876543210", "reason": "Check auto-applied for managed account" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_campaigns": { "post": { "operationId": "google_ads_list_campaigns", "summary": "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. Use include_criteria to control audience/schedule detail: \"none\" (fastest), \"summary\" (default, capped), or \"full\" (uncapped, requires campaign_id/campaign_ids).", "tags": [ "campaigns" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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." }, "include_criteria": { "type": "string", "enum": [ "none", "summary", "full" ], "default": "summary", "description": "Controls campaign criteria detail level. \"none\" omits criteria (fastest). \"summary\" (default) returns capped criteria with total counts. \"full\" returns all criteria uncapped — requires campaign_id or campaign_ids (max 10)." }, "label_filter": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Filter by labels. Accepts an array whose entries are any of: label name (e.g. \"Big Boom\"), bare label ID (e.g. \"9876543210\"), or full label resource name (e.g. \"customers/1234567890/labels/9876543210\"). Names are resolved against cached labels for the relevant customer scope. Unknown names return an empty result with a warning rather than an error." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "List campaigns" } }, "filter-by-status": { "summary": "Filter by status", "value": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled campaigns" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "reason": "Get campaign details" } }, "search": { "summary": "Search", "value": { "customer_id": "1234567890", "search": "brand", "reason": "Find brand campaigns" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_id": "1234567890", "campaign_ids": [ "111", "222", "333" ], "reason": "Get details for specific campaigns" } }, "mcc-child": { "summary": "MCC child", "value": { "customer_id": "1234567890", "login_customer_id": "9999999999", "reason": "List campaigns for MCC child" } }, "full-criteria-for-campaign": { "summary": "Full criteria for campaign", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "include_criteria": "full", "reason": "Get all audiences for campaign" } }, "fast-listing-no-criteria": { "summary": "Fast listing (no criteria)", "value": { "customer_id": "1234567890", "include_criteria": "none", "reason": "Quick campaign overview" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_render_chart": { "post": { "operationId": "google_ads_render_chart", "summary": "Render Chart", "description": "Interactive UI for rendering data visualization charts", "tags": [ "chart" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Brief explanation of why you are rendering this chart" }, "chart": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "bar" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "required": [ "label", "values" ], "additionalProperties": false } }, "metric": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" }, "tickFormat": { "type": "string" }, "labelFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "format": { "type": "string" }, "suffix": { "type": "string" } }, "required": [ "field" ], "additionalProperties": false } } }, "required": [ "field", "label" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" }, "tickFormat": { "type": "string" }, "labelFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "format": { "type": "string" }, "suffix": { "type": "string" } }, "required": [ "field" ], "additionalProperties": false } } }, "required": [ "field", "label" ], "additionalProperties": false } } ] }, "orientation": { "type": "string", "enum": [ "horizontal", "vertical" ], "default": "horizontal" }, "sort": { "type": "string", "enum": [ "asc", "desc", "none" ], "default": "desc" }, "colorBy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "field": { "type": "string" }, "threshold": { "type": "number" }, "sentiment": { "type": "string", "enum": [ "above-positive", "above-negative" ], "default": "above-positive" } }, "required": [ "type", "field", "threshold" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "continuous" }, "field": { "type": "string" }, "scheme": { "type": "string" }, "reverse": { "type": "boolean", "default": false }, "muteZero": { "type": "boolean", "default": false }, "label": { "type": "string" } }, "required": [ "type", "field", "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "categorical" } }, "required": [ "type" ], "additionalProperties": false } ] }, "referenceLines": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "label": { "type": "string" }, "dash": { "type": "string", "enum": [ "solid", "dashed" ], "default": "dashed" } }, "required": [ "value" ], "additionalProperties": false } }, "table": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "columns" ], "additionalProperties": false }, "panelWidth": { "type": "number" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 400 } }, "required": [ "type", "data", "metric" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scatter" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "label", "values" ], "additionalProperties": false } }, "x": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "scale": { "type": "string", "enum": [ "linear", "log" ], "default": "linear" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false }, "y": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "scale": { "type": "string", "enum": [ "linear", "log" ], "default": "linear" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false }, "size": { "type": "object", "properties": { "field": { "type": "string" }, "range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "default": [ 3, 20 ] } }, "required": [ "field" ], "additionalProperties": false }, "color": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "continuous" }, "field": { "type": "string" }, "scheme": { "type": "string" }, "reverse": { "type": "boolean", "default": false } }, "required": [ "type", "field", "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "field": { "type": "string" }, "threshold": { "type": "number" }, "sentiment": { "type": "string", "enum": [ "above-positive", "above-negative" ], "default": "above-positive" } }, "required": [ "type", "field", "threshold" ], "additionalProperties": false } ] }, "referenceLines": { "type": "object", "properties": { "medianX": { "type": "boolean", "default": false }, "medianY": { "type": "boolean", "default": false }, "targets": { "type": "array", "items": { "type": "object", "properties": { "slope": { "type": "number" }, "label": { "type": "string" } }, "required": [ "slope", "label" ], "additionalProperties": false } }, "regression": { "type": "boolean", "default": false } }, "additionalProperties": false }, "table": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "columns" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 450 } }, "required": [ "type", "data", "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "timeseries" }, "data": { "type": "object", "properties": { "current": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } }, "previous": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } }, "projection": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } } }, "required": [ "current" ], "additionalProperties": false }, "primaryAxis": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "mark": { "type": "string", "enum": [ "bar", "area", "line" ] }, "groupBars": { "type": "boolean" } }, "required": [ "field", "label", "mark" ], "additionalProperties": false }, "secondaryAxis": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "dash": { "type": "string", "enum": [ "solid", "dashed" ], "default": "solid" } }, "required": [ "field", "label" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 400 } }, "required": [ "type", "data", "primaryAxis" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "funnel" }, "data": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "string" } }, "volume": { "type": "array", "items": { "type": "number" } }, "costPer": { "type": "array", "items": { "type": "number" } } }, "required": [ "stages", "volume" ], "additionalProperties": false }, "showConversionRates": { "type": "boolean", "default": true }, "showCostPer": { "type": "boolean", "default": true }, "colorScheme": { "type": "string", "default": "Blues" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 350 } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "waterfall" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "number" }, "colorValue": { "type": "number" } }, "required": [ "label", "value", "colorValue" ], "additionalProperties": false } }, "colorScheme": { "type": "string", "default": "RdYlGn" }, "colorLabel": { "type": "string", "default": "CPA ($)" }, "valueLabel": { "type": "string", "default": "Cumulative Spend ($)" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choropleth" }, "data": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "value": { "type": "number" }, "meta": { "type": "object", "additionalProperties": { "type": [ "string", "number", "null" ] } } }, "required": [ "state", "value" ], "additionalProperties": false } }, "valueLabel": { "type": "string" }, "colorScheme": { "type": "string", "default": "YlOrRd" }, "colorType": { "type": "string", "enum": [ "quantize", "linear", "threshold" ], "default": "quantize" }, "reverse": { "type": "boolean", "default": false }, "tip": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "fields" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 450 } }, "required": [ "type", "data", "valueLabel" ], "additionalProperties": false } ] } }, "required": [ "reason", "chart" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } }, "x-mcp-tool-type": "app", "x-mcp-chart-types": [ "bar", "scatter", "timeseries", "funnel", "waterfall", "choropleth" ] } }, "/tools/google_ads_list_connections": { "post": { "operationId": "google_ads_list_connections", "summary": "List Google Connections", "description": "List the Google Ads connections available to you — both ones you own and ones shared with you via an organization. Use this to discover connection IDs for set_default / share / rename / revoke.", "tags": [ "connections" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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#" }, "examples": { "list-connections": { "summary": "List connections", "value": { "reason": "User asked which Google accounts they have connected" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_set_default_connection": { "post": { "operationId": "google_ads_set_default_connection", "summary": "Set Default Google Connection", "description": "Set the Google connection that should be used by default for subsequent Google Ads tool calls. The default is scoped to the calling actor (your user account, or the API key being used).", "tags": [ "set-default-connection" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Google connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "set-default": { "summary": "Set default", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User picked their primary Google workspace" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_share_connection": { "post": { "operationId": "google_ads_share_connection", "summary": "Share Google Connection With Organization", "description": "Share an owned Google connection with all members of your organization, so teammates can use it without having to reconnect Google themselves. You must be the owner of the connection.", "tags": [ "share-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to share with your organization. You must be the owner." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "share-with-org": { "summary": "Share with org", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User asked to share this Google connection with their teammates" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_unshare_connection": { "post": { "operationId": "google_ads_unshare_connection", "summary": "Unshare Google Connection From Organization", "description": "Stop sharing an owned Google connection with your organization. Teammates lose access immediately. You must be the owner.", "tags": [ "unshare-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to stop sharing with your organization. You must be the owner." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "stop-sharing": { "summary": "Stop sharing", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User no longer wants the team to access this Google connection" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_rename_connection": { "post": { "operationId": "google_ads_rename_connection", "summary": "Rename Google Connection", "description": "Rename the display name of an owned Google connection. The OAuth grant and underlying account are unaffected — this only changes the human-readable label. You must be the owner.", "tags": [ "rename-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to rename. You must be the owner." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New human-readable name for the connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "display_name", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "rename": { "summary": "Rename", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "display_name": "Acme — Production", "reason": "User wanted a clearer label for this Google connection" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_revoke_connection": { "post": { "operationId": "google_ads_revoke_connection", "summary": "Revoke Google Connection", "description": "Revoke (soft-delete) an owned Google connection. Any defaults pointing to it are invalidated and shared org members lose access. The OAuth grant at Google is NOT revoked by this tool — the user must disconnect via the dashboard if they want to fully revoke at Google. You must be the owner.", "tags": [ "revoke-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to revoke. You must be the owner." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "revoke": { "summary": "Revoke", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User asked to disconnect this Google account" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_conversion_actions": { "post": { "operationId": "google_ads_get_conversion_actions", "summary": "List Google Ads Conversion Actions", "description": "List conversion actions for a Google Ads account, including (a) the account-default goal flag, (b) **effective** inclusion across active campaigns (factoring in custom conversion goals and selective optimization), and (c) measured \\", "tags": [ "conversion-actions" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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)" }, "lookback_days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30, "description": "Lookback window (days) for recent conversion counts. Default 30." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "effective", "recent", "campaign_overrides", "tag_snippets", "attribution" ] }, "default": [ "effective", "recent" ], "description": "Which optional blocks to compute. 'effective' = goal-hierarchy walk (3 extra GAQL queries). 'recent' = metrics.conversions over the lookback window (1 extra query). 'campaign_overrides' = list the contributing campaign IDs per action, grouped by source (HEAVY — full list, no cap; only request when the user explicitly asks 'which campaigns?'). Implies 'effective'. 'tag_snippets' = include tag snippet HTML per row. 'attribution' = include attribution-model + value settings. Default: ['effective','recent']. Pass [] for the lightest possible response." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "list-all-default-effective-recent": { "summary": "List all (default: effective + recent)", "value": { "customer_id": "1234567890", "reason": "Audit which conversion actions are firing" } }, "enabled-only": { "summary": "Enabled only", "value": { "customer_id": "1234567890", "status": "ENABLED", "reason": "Active conversion actions" } }, "lightweight-list": { "summary": "Lightweight list", "value": { "customer_id": "1234567890", "include": [], "reason": "Just list the conversion actions, no goal walk" } }, "custom-lookback-7-days": { "summary": "Custom lookback (7 days)", "value": { "customer_id": "1234567890", "lookback_days": 7, "reason": "Recent week of conversions" } }, "which-campaigns-count-this-action": { "summary": "Which campaigns count this action?", "value": { "customer_id": "1234567890", "include": [ "effective", "campaign_overrides" ], "reason": "Per-campaign attribution audit" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_developer_feedback": { "post": { "operationId": "google_ads_developer_feedback", "summary": "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).", "tags": [ "feedback" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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#" }, "examples": { "missing-tool": { "summary": "Missing tool", "value": { "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" } }, "workflow-gap": { "summary": "Workflow gap", "value": { "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" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_geo_performance": { "post": { "operationId": "google_ads_get_geo_performance", "summary": "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.", "tags": [ "geo-performance" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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\"." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "country-performance": { "summary": "Country performance", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "geo_level": "country", "reason": "Compare spend by country" } }, "city-level-breakdown": { "summary": "City-level breakdown", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "geo_level": "geo_target_city", "level": "CAMPAIGN", "reason": "City performance analysis" } }, "country-by-campaign": { "summary": "Country by campaign", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "geo_level": "country", "level": "CAMPAIGN", "segments": [ "date" ], "reason": "Daily country trends per campaign" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_insights": { "post": { "operationId": "google_ads_get_insights", "summary": "Get Google Ads Insights", "description": "Retrieve performance metrics using GAQL with full control over metrics, segments, levels, and date ranges. Always fetches fresh data. Default metrics include the supported Demand Gen Platform Comparable conversion family. Custom metrics accept Platform Comparable columns with or without the metrics. prefix (for example platform_comparable_conversions or metrics.platform_comparable_conversions). Supports device breakdowns, ad_network_type channel analysis, and search impression share diagnostics. 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.", "tags": [ "insights" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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). Demand Gen Platform Comparable columns are accepted with or without the metrics. prefix, e.g. platform_comparable_conversions or metrics.platform_comparable_conversions. These Demand Gen-only columns include view-through conversions; see https://support.google.com/google-ads/answer/15299024." }, "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "all-conversions-by-action": { "summary": "All conversions by action", "value": { "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" } }, "search-impression-share": { "summary": "Search impression share", "value": { "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" } }, "device-breakdown-with-custom-metrics": { "summary": "Device breakdown with custom metrics", "value": { "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" } }, "pmax-channel-breakdown": { "summary": "PMax channel breakdown", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "CAMPAIGN", "segments": [ "ad_network_type" ], "reason": "PMax channel-level performance breakdown" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_generate_keyword_ideas": { "post": { "operationId": "google_ads_generate_keyword_ideas", "summary": "Generate Google Ads Keyword Ideas", "description": "Generate keyword suggestions from seed keywords and/or a URL. Returns keyword ideas with average monthly searches, competition level, and estimated bid ranges. Supports pagination for large result sets. Examples: seed with [\"running shoes\", \"athletic footwear\"] for shoe campaigns, or provide a competitor URL to discover relevant keywords. Use include_monthly_volumes=true for seasonal trend data.", "tags": [ "generate-keyword-ideas" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Seed keywords to generate ideas from (max 20). At least one of keywords or url must be provided." }, "url": { "type": "string", "format": "uri", "description": "Seed URL to generate keyword ideas from. At least one of keywords or url must be provided." }, "language": { "type": "string", "minLength": 2, "maxLength": 5, "default": "en", "description": "ISO 639-1 language code (e.g., \"en\", \"es\"). Default: \"en\"." }, "geo_targets": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "default": [ "US" ], "description": "ISO 3166-1 alpha-2 country codes (e.g., [\"US\", \"GB\"]). Default: [\"US\"]." }, "network": { "type": "string", "enum": [ "GOOGLE_SEARCH", "GOOGLE_SEARCH_AND_PARTNERS" ], "default": "GOOGLE_SEARCH", "description": "Keyword plan network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS" }, "include_adult_keywords": { "type": "boolean", "default": false, "description": "Whether to include adult keyword ideas. Default: false." }, "include_monthly_volumes": { "type": "boolean", "default": false, "description": "When true, includes per-month search volume history for each keyword. Default: false." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum keyword ideas to return per page (1-1000, default 50)" }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response. Do not construct manually." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "from-seed-keywords": { "summary": "From seed keywords", "value": { "customer_id": "1234567890", "keywords": [ "running shoes", "athletic footwear" ], "reason": "Keyword research for new campaign" } }, "from-url": { "summary": "From URL", "value": { "customer_id": "1234567890", "url": "https://example.com/products/shoes", "reason": "Find keywords from competitor page" } }, "with-monthly-volumes": { "summary": "With monthly volumes", "value": { "customer_id": "1234567890", "keywords": [ "yoga mat" ], "include_monthly_volumes": true, "geo_targets": [ "US", "GB" ], "reason": "Seasonal trend analysis" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_keyword_historical_metrics": { "post": { "operationId": "google_ads_get_keyword_historical_metrics", "summary": "Get Google Ads Keyword Historical Metrics", "description": "Get historical search metrics for specific keywords — average monthly searches, competition level, and bid estimates. Unlike keyword ideas, this takes exact keywords you already have and returns their metrics. Use include_monthly_volumes=true for month-by-month search volume trends. Examples: check volume for [\"running shoes\", \"trail running shoes\"] before adding to campaigns, or validate keywords from external research.", "tags": [ "keyword-historical-metrics" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 200, "description": "Keywords to get historical metrics for (1-200 keywords)" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "ISO 639-1 language code (e.g. \"en\", \"es\"). Maps internally to languageConstants resource name." }, "geo_targets": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 country codes (e.g. [\"US\", \"GB\"]). Maps internally to geoTargetConstants." }, "network": { "type": "string", "enum": [ "GOOGLE_SEARCH", "GOOGLE_SEARCH_AND_PARTNERS" ], "default": "GOOGLE_SEARCH", "description": "Network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS" }, "include_monthly_volumes": { "type": "boolean", "default": false, "description": "When true, includes month-by-month search volume data. Default: false." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "keywords", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "basic-metrics": { "summary": "Basic metrics", "value": { "customer_id": "1234567890", "keywords": [ "running shoes", "trail running shoes" ], "reason": "Check keyword search volume" } }, "with-geo-targeting": { "summary": "With geo targeting", "value": { "customer_id": "1234567890", "keywords": [ "yoga classes" ], "geo_targets": [ "US" ], "language": "en", "reason": "Market sizing for US" } }, "monthly-trends": { "summary": "Monthly trends", "value": { "customer_id": "1234567890", "keywords": [ "winter coats" ], "include_monthly_volumes": true, "reason": "Analyze seasonal patterns" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_generate_keyword_forecast_metrics": { "post": { "operationId": "google_ads_generate_keyword_forecast_metrics", "summary": "Generate Google Ads Keyword Forecast Metrics", "description": "Forecast campaign performance for a set of keywords with budget and bidding config. Returns projected impressions, clicks, cost, CTR, conversions, and CPA. Supports MANUAL_CPC (requires default_max_cpc_bid_micros), MAXIMIZE_CLICKS, and MAXIMIZE_CONVERSIONS strategies. Budget is in micros (10000000 = $10). Examples: forecast a $50/day campaign with exact-match keywords, or compare BROAD vs EXACT match performance.", "tags": [ "generate-keyword-forecast-metrics" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "The keyword text" }, "match_type": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ], "default": "BROAD", "description": "Keyword match type (default: BROAD)" }, "max_cpc_bid_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-keyword max CPC bid in micros. Overrides the ad-group-level default." } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 200, "description": "Keywords to forecast (1-200). Each has text, optional match_type, optional max_cpc_bid_micros." }, "daily_budget_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Daily budget in micros (e.g., 10000000 = $10.00)" }, "default_max_cpc_bid_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Default max CPC bid in micros. Required for MANUAL_CPC strategy. Per-keyword bids override this." }, "bidding_strategy": { "type": "string", "enum": [ "MANUAL_CPC", "MAXIMIZE_CLICKS", "MAXIMIZE_CONVERSIONS" ], "default": "MANUAL_CPC", "description": "Bidding strategy: MANUAL_CPC (default), MAXIMIZE_CLICKS, or MAXIMIZE_CONVERSIONS" }, "max_cpc_bid_ceiling_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Max CPC bid ceiling for MAXIMIZE_CLICKS strategy (micros). Ignored for other strategies." }, "geo_targets": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "minItems": 1, "default": [ "US" ], "description": "ISO 3166-1 alpha-2 country codes (e.g., [\"US\", \"GB\"]). Default: [\"US\"]." }, "language": { "type": "string", "minLength": 2, "maxLength": 2, "default": "en", "description": "ISO 639-1 language code (e.g., \"en\", \"es\"). Default: \"en\"." }, "network": { "type": "string", "enum": [ "GOOGLE_SEARCH", "GOOGLE_SEARCH_AND_PARTNERS" ], "default": "GOOGLE_SEARCH", "description": "Ad network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS" }, "forecast_start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Forecast period start date (YYYY-MM-DD). Defaults to tomorrow." }, "forecast_end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Forecast period end date (YYYY-MM-DD). Defaults to 30 days from start." }, "negative_keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Negative keyword texts to exclude from the forecast" }, "conversion_rate": { "type": "number", "minimum": 0, "maximum": 1, "description": "Expected conversion rate (0-1, e.g., 0.05 for 5%)" }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\"). Defaults to account currency." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "keywords", "daily_budget_micros", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "manual-cpc-forecast": { "summary": "Manual CPC forecast", "value": { "customer_id": "1234567890", "keywords": [ { "text": "running shoes", "match_type": "EXACT" } ], "daily_budget_micros": 10000000, "default_max_cpc_bid_micros": 1500000, "bidding_strategy": "MANUAL_CPC", "reason": "Budget planning for new campaign" } }, "maximize-clicks": { "summary": "Maximize clicks", "value": { "customer_id": "1234567890", "keywords": [ { "text": "yoga mat" }, { "text": "yoga accessories" } ], "daily_budget_micros": 5000000, "bidding_strategy": "MAXIMIZE_CLICKS", "reason": "Estimate traffic potential" } }, "with-date-range": { "summary": "With date range", "value": { "customer_id": "1234567890", "keywords": [ { "text": "winter coats", "match_type": "BROAD" } ], "daily_budget_micros": 20000000, "default_max_cpc_bid_micros": 2000000, "forecast_start_date": "2025-11-01", "forecast_end_date": "2025-12-31", "reason": "Holiday season forecast" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_generate_ad_group_themes": { "post": { "operationId": "google_ads_generate_ad_group_themes", "summary": "Generate Google Ads Ad Group Themes", "description": "Suggest which ad group each keyword belongs to. Takes a list of keywords and existing ad group resource names, returns keyword-to-ad-group assignment suggestions with recommended match types. Also identifies unusable ad groups. Example: organize [\"running shoes\", \"trail shoes\", \"yoga mat\", \"yoga block\"] across your existing ad groups.", "tags": [ "generate-ad-group-themes" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 2000, "description": "Keywords to find ad group assignments for (1-2000 keywords)" }, "ad_groups": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Ad group resource names (e.g., \"customers/1234567890/adGroups/111222333\") to consider as placement targets" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "keywords", "ad_groups", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "assign-keywords-to-ad-groups": { "summary": "Assign keywords to ad groups", "value": { "customer_id": "1234567890", "keywords": [ "running shoes", "trail shoes", "yoga mat", "yoga block" ], "ad_groups": [ "customers/1234567890/adGroups/111", "customers/1234567890/adGroups/222" ], "reason": "Organize keywords into ad groups" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_keyword_performance": { "post": { "operationId": "google_ads_get_keyword_performance", "summary": "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. Set \\", "tags": [ "keyword-performance" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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\"." }, "include_landing_pages": { "type": "boolean", "default": false, "description": "When true, includes keyword-level Final URLs on each row: ad_group_criterion_final_urls (array), ad_group_criterion_final_mobile_urls (array), and ad_group_criterion_tracking_url_template (string). Adds response size — omit when not needed. 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 keyword metrics by channel (SEARCH vs SEARCH_PARTNERS)." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "top-keywords": { "summary": "Top keywords", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Keyword performance review" } }, "exact-match-only": { "summary": "Exact match only", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "keyword_match_type": "EXACT", "reason": "Exact match keyword analysis" } }, "top-converters": { "summary": "Top converters", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "order_by": "conversions", "status": [ "ENABLED" ], "reason": "Find top converting keywords" } }, "by-network-channel": { "summary": "By network channel", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "ad_network_type" ], "reason": "Keyword performance by ad network" } }, "with-landing-pages": { "summary": "With landing pages", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "status": [ "ENABLED" ], "include_landing_pages": true, "reason": "Export active keywords with their landing pages" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_search_terms_report": { "post": { "operationId": "google_ads_get_search_terms_report", "summary": "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 (keyed by search term) and landing page lookups are opt-in to control response size. Passing conversion_action_name in segments auto-enables conversion breakdown. For Performance Max campaigns, set pmax_search_categories=true to get search category insights (grouped themes) instead of individual search terms.", "tags": [ "search-terms-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 search term and conversion action (keyed by search term text). 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). If conversion_action or conversion_action_name is included, it is automatically stripped from the main query and a parallel conversion breakdown query runs instead. Ignored when pmax_search_categories is true." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "top-search-terms": { "summary": "Top search terms", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Search term analysis" } }, "new-terms-only": { "summary": "New terms only", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "search_term_status": [ "NONE" ], "order_by": "conversions", "reason": "Find new converting search terms" } }, "with-landing-pages": { "summary": "With landing pages", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "include_landing_pages": true, "reason": "Find which landing pages top search terms go to" } }, "pmax-search-categories": { "summary": "PMax search categories", "value": { "customer_id": "1234567890", "campaign_id": "5555555555", "date_preset": "LAST_30_DAYS", "pmax_search_categories": true, "reason": "PMax search category analysis" } }, "by-network-channel": { "summary": "By network channel", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "ad_network_type" ], "reason": "Search terms by ad network" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_landing_page_report": { "post": { "operationId": "google_ads_get_landing_page_report", "summary": "Get Landing Page Performance Report", "description": "Landing page performance report from the landing_page_view resource. Preferred tool for all landing page analysis — do not use google_ads_get_insights or google_ads_list_ads for landing page data. Returns clicks, impressions, cost, conversions, speed_score, and mobile_friendly_clicks_percentage grouped by landing page URL, with per-conversion-action breakdowns included automatically. Use url_contains to filter by URL pattern. Note: Performance Max campaigns do not appear in landing_page_view data.", "tags": [ "landing-page-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "segments": { "type": "array", "items": { "type": "string", "enum": [ "date", "device", "ad_network_type" ] }, "description": "Additional segments: date, device, ad_network_type. Conversion 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" }, "url_contains": { "type": "string", "description": "Filter landing pages where URL contains this string (case-sensitive)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Maximum number of landing pages to return (default: 100, max: 1000)" }, "order_by": { "type": "string", "enum": [ "impressions", "clicks", "cost", "conversions", "ctr" ], "default": "clicks", "description": "Sort results by this metric (default: clicks, descending)" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (all_conversions, all_conversions_value) segmented by conversion_action_name." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "top-landing-pages-by-clicks": { "summary": "Top landing pages by clicks", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "reason": "Landing page analysis" } }, "daily-landing-page-trend": { "summary": "Daily landing page trend", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "segments": [ "date" ], "reason": "Daily landing page trend" } }, "landing-pages-for-a-campaign": { "summary": "Landing pages for a campaign", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "campaign_id": "9876543210", "reason": "Campaign landing page review" } }, "filter-by-url-pattern": { "summary": "Filter by URL pattern", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "url_contains": "/products/", "reason": "Product page performance" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_negative_keyword_lists": { "post": { "operationId": "google_ads_list_negative_keyword_lists", "summary": "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.", "tags": [ "negative-keyword-lists" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "all-lists": { "summary": "All lists", "value": { "customer_id": "1234567890", "reason": "Audit shared negative keyword lists" } }, "with-keywords": { "summary": "With keywords", "value": { "customer_id": "1234567890", "include_keywords": true, "reason": "View all negative keyword list contents" } }, "single-list-detail": { "summary": "Single list detail", "value": { "customer_id": "1234567890", "list_id": "5555555555", "include_keywords": true, "include_campaign_associations": true, "reason": "Full audit of a specific list" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_negative_keywords": { "post": { "operationId": "google_ads_list_negative_keywords", "summary": "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.", "tags": [ "negative-keywords" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "all-negatives": { "summary": "All negatives", "value": { "customer_id": "1234567890", "reason": "Audit negative keywords" } }, "campaign-level": { "summary": "Campaign level", "value": { "customer_id": "1234567890", "campaign_id": "5555555555", "level": "CAMPAIGN", "reason": "Cross-check campaign negatives during search term audit" } }, "filter-by-match-type": { "summary": "Filter by match type", "value": { "customer_id": "1234567890", "match_type": [ "BROAD" ], "reason": "Find broad match negatives that may be too aggressive" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_performance_report": { "post": { "operationId": "google_ads_get_performance_report", "summary": "Get Google Ads Performance Report", "description": "Comprehensive performance report with funnel metrics and per-conversion-action breakdowns. Supports segments for device breakdown (DESKTOP, MOBILE, TABLET), daily trends, and network type analysis. Preferred over google_ads_get_insights for standard analysis. Runs parallel queries for top-level funnel and conversion action breakdown. Supported levels automatically include the Demand Gen Platform Comparable conversion family (platform_comparable_conversions, cost/value/rate variants); row-level reports return null for non-Demand Gen rows. 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.", "tags": [ "reporting" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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. CAMPAIGN, AD_GROUP, and AD reports automatically include platform_comparable_conversions for Demand Gen rows (null for non-Demand Gen)." }, "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)." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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#" }, "examples": { "campaign-overview": { "summary": "Campaign overview", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "reason": "Monthly performance review" } }, "daily-trend": { "summary": "Daily trend", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "segments": [ "date" ], "reason": "Daily performance trend" } }, "account-summary": { "summary": "Account summary", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "ACCOUNT", "reason": "Account-level overview" } }, "device-breakdown": { "summary": "Device breakdown", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "device" ], "reason": "Device analysis" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_ping": { "post": { "operationId": "google_ads_ping", "summary": "Ping Google Ads MCP Server", "description": "Health check for the Google Ads MCP server.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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#" }, "examples": { "health-check": { "summary": "Health check", "value": { "reason": "Verify server is running" } }, "with-message": { "summary": "With message", "value": { "message": "hello", "reason": "Test connectivity" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase JWT or hpk_live_... API key" } }, "schemas": { "McpToolResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "resource_link" ] }, "text": { "type": "string" } } } }, "structuredContent": { "type": "object", "additionalProperties": true }, "isError": { "type": "boolean" } } }, "McpError": { "type": "object", "properties": { "isError": { "type": "boolean", "const": true }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } }, "RestError": { "type": "object", "description": "Error response from REST tool endpoints (mapped from JSON-RPC error codes)", "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "integer", "description": "JSON-RPC error code" }, "data": { "description": "Additional error context" } }, "required": [ "error", "code" ] }, "ToolList": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true } } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "discovery", "description": "Tool discovery and introspection" }, { "name": "account-summary", "description": "Account-summary tools" }, { "name": "accounts", "description": "Accounts tools" }, { "name": "activities", "description": "Activities tools" }, { "name": "ad-groups", "description": "Ad-groups tools" }, { "name": "ads", "description": "Ads tools" }, { "name": "audiences", "description": "Audiences tools" }, { "name": "auth", "description": "Auth tools" }, { "name": "auto-applied-recommendations", "description": "Auto-applied-recommendations tools" }, { "name": "campaigns", "description": "Campaigns tools" }, { "name": "chart", "description": "Chart tools" }, { "name": "connections", "description": "Connections tools" }, { "name": "conversion-actions", "description": "Conversion-actions tools" }, { "name": "feedback", "description": "Feedback tools" }, { "name": "generate-ad-group-themes", "description": "Generate-ad-group-themes tools" }, { "name": "generate-keyword-forecast-metrics", "description": "Generate-keyword-forecast-metrics tools" }, { "name": "generate-keyword-ideas", "description": "Generate-keyword-ideas tools" }, { "name": "geo-performance", "description": "Geo-performance tools" }, { "name": "insights", "description": "Insights tools" }, { "name": "keyword-historical-metrics", "description": "Keyword-historical-metrics tools" }, { "name": "keyword-performance", "description": "Keyword-performance tools" }, { "name": "landing-page-report", "description": "Landing-page-report tools" }, { "name": "mcc-child-accounts", "description": "Mcc-child-accounts tools" }, { "name": "negative-keyword-lists", "description": "Negative-keyword-lists tools" }, { "name": "negative-keywords", "description": "Negative-keywords tools" }, { "name": "rename-connection", "description": "Rename-connection tools" }, { "name": "reporting", "description": "Reporting tools" }, { "name": "revoke-connection", "description": "Revoke-connection tools" }, { "name": "search-terms-report", "description": "Search-terms-report tools" }, { "name": "set-default-connection", "description": "Set-default-connection tools" }, { "name": "share-connection", "description": "Share-connection tools" }, { "name": "unshare-connection", "description": "Unshare-connection tools" } ] }