# Hopkin

> Hopkin provides MCP servers that let AI agents manage advertising campaigns across Meta, Google, LinkedIn, Reddit, and TikTok. Connect via OAuth and give Claude, GPT, or any MCP-compatible assistant the ability to read campaign data, pull performance reports, and manage ads through natural language.

---

# Getting Started
Source: https://hopkin.ai/docs/getting-started

# Getting Started with Hopkin

## What is Hopkin?

Hopkin gives AI assistants the ability to manage your advertising campaigns. Connect your ad accounts from Meta, Google, LinkedIn, Reddit, and TikTok, then use natural language to pull performance reports, analyze audiences, audit creatives, and monitor spend — all through conversation.

### What you can do

- "Show me last week's performance across all my Meta campaigns"
- "Which Google Ads keywords are wasting budget?"
- "Break down my LinkedIn ads by job seniority and industry"
- "Compare creative performance on TikTok — which videos have the best completion rates?"
- "Pull a subreddit-level breakdown of my Reddit campaign spend"

Hopkin works with Claude Desktop, Notion, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

## Choose Your Client

Pick the installation guide for the tool you use:

- **[Claude Desktop](getting-started/claude-desktop.html)** — Add via Settings or config file. Best for non-technical users.
- **[Notion](getting-started/notion.html)** — Add as an MCP connection in Notion custom agents.
- **[OpenClaw](getting-started/openclaw.html)** — Install the Hopkin skill from ClawHub.
- **[Claude Code](getting-started/claude.html)** — Full MCP + plugin integration with pre-built skills.
- **[Cursor](getting-started/cursor.html)** — Add to `.cursor/mcp.json`.
- **[Windsurf](getting-started/windsurf.html)** — Add to your Windsurf MCP config.
- **[VS Code](getting-started/vscode.html)** — Add to `.vscode/mcp.json`.
- **[Other Clients](getting-started/other-clients.html)** — Direct server endpoints for any MCP-compatible client.

## Your First Query

Once connected, try these three steps to verify everything works.

### Step 1: Check Authentication

Ask your AI assistant: "Check my Hopkin auth status for Meta Ads"

This calls `meta_ads_check_auth_status` and confirms your account is connected.

### Step 2: List Ad Accounts

Ask: "Show me my Meta ad accounts"

This calls `meta_ads_list_ad_accounts` and returns your account IDs, names, and statuses.

### Step 3: Pull a Performance Report

Ask: "Give me last week's performance report for my Meta ads"

This calls `meta_ads_get_performance_report` with `date_preset: "last_7d"` and returns spend, impressions, clicks, conversions, and cost metrics.

The same pattern works across all platforms — just swap "Meta" for "Google", "LinkedIn", "Reddit", or "TikTok".

## Available Servers

| Server | Endpoint | Tools | Platforms |
|--------|----------|-------|-----------|
| **Meta Ads** | `/meta-ads/mcp` | 16 | Facebook, Instagram |
| **Google Ads** | `/google-ads/mcp` | 22 | Search, Display, YouTube, Shopping |
| **LinkedIn Ads** | `/linkedin-ads/mcp` | 15 | Sponsored Content, InMail |
| **Reddit Ads** | `/reddit-ads/mcp` | 13 | Promoted Posts, Community Targeting |
| **TikTok Ads** | `/tiktok-ads/mcp` | 17 | In-Feed, TopView, Spark Ads |

All servers share the same authentication model. One API key works across all platforms.

## Authentication

For details on API keys, OAuth, and security, see the [Authentication](authentication.html) page.

## Troubleshooting

**"Authentication error" on first call**: Your ad platform account may not be connected yet. Visit [app.hopkin.ai](https://app.hopkin.ai) to link your Meta, Google, LinkedIn, Reddit, or TikTok ad account via OAuth.

**"Permission error" from platform API**: The connected account may lack access to the requested ad account. Run `check_auth_status` to see which accounts are accessible.

**Empty results from list tools**: Try passing `refresh: true` to bypass the cache and fetch directly from the platform API.

**MCP server not responding**: Verify your API key is correct and hasn't expired. Generate a new key at [app.hopkin.ai/api-keys](https://app.hopkin.ai/api-keys) if needed.


---

Source: https://hopkin.ai/docs/authentication

# Authentication

## Overview

Hopkin supports two authentication methods. Both produce the same internal auth context — your tools work identically regardless of which method you choose.

## API Keys (Recommended)

API keys are the simplest way to authenticate. They work with all MCP clients and require no browser interaction.

### Getting an API Key

- Go to [app.hopkin.ai/api-keys](https://app.hopkin.ai/api-keys)
- Click **Generate New Key**
- Copy the key (starts with `hpk_live_...`)

### Using Your API Key

Pass the key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer hpk_live_your_key_here
```

In Claude Code:

```bash
claude mcp add --transport http -H "Authorization:Bearer hpk_live_..." hopkin-meta-ads https://mcp.hopkin.ai/meta-ads/mcp
```

In a config file:

```json
{
  "mcpServers": {
    "hopkin-meta-ads": {
      "url": "https://mcp.hopkin.ai/meta-ads/mcp",
      "headers": {
        "Authorization": "Bearer hpk_live_..."
      }
    }
  }
}
```

### Key Security

- Keys are hashed (SHA-256) before storage — Hopkin never stores your raw key
- One key works across all MCP servers (Meta, Google, LinkedIn, Reddit, TikTok)
- Revoke keys immediately at [app.hopkin.ai/api-keys](https://app.hopkin.ai/api-keys) if compromised
- Do not commit keys to version control — use environment variables or secrets managers

## OAuth (JWT)

OAuth is used for browser-based flows and the Hopkin web app. When a user authenticates through [app.hopkin.ai](https://app.hopkin.ai), Hopkin issues a JWT that the MCP servers accept.

### When to Use OAuth

- Building a web integration that authenticates users through a browser
- Using the Hopkin web app directly
- Need per-user token refresh without managing API keys

### How It Works

- User signs in at [app.hopkin.ai](https://app.hopkin.ai) via OAuth (Google, GitHub, or email)
- User connects their ad platform accounts (Meta, Google, LinkedIn, Reddit, TikTok) through the OAuth flow
- Hopkin issues a JWT
- The JWT is passed as a Bearer token, same as an API key: `Authorization: Bearer <jwt>`
- Platform-specific OAuth tokens are stored securely in the `provider_tokens` table and refreshed automatically

## Connecting Ad Platform Accounts

Regardless of your authentication method, you need to connect your ad platform accounts before using the tools.

### First-Time Setup

- Visit [app.hopkin.ai](https://app.hopkin.ai)
- Click **Connect** next to each platform you want to use
- Complete the OAuth flow for that platform (Meta, Google, LinkedIn, Reddit, or TikTok)
- Your platform tokens are stored securely and refreshed automatically

### Verifying Your Connection

Use the `check_auth_status` tool for any platform to verify your account is connected:

```json
{
  "tool": "meta_ads_check_auth_status",
  "params": {
    "reason": "Verify my Meta Ads connection"
  }
}
```

This returns your user profile, connected accounts, and token status.

## Authentication Errors

**"Authentication failed"**: Your API key or JWT may be invalid or expired. Generate a new API key at [app.hopkin.ai/api-keys](https://app.hopkin.ai/api-keys).

**"No provider token found"**: You've authenticated with Hopkin but haven't connected the specific ad platform yet. Visit [app.hopkin.ai](https://app.hopkin.ai) to complete the platform OAuth flow.

**"Token expired" from platform API**: Platform tokens are refreshed automatically, but if a refresh fails, re-connect the platform at [app.hopkin.ai](https://app.hopkin.ai).

**"Permission denied" for a specific ad account**: Your connected platform account may not have access to the requested ad account. Run `check_auth_status` to see which accounts are accessible, or check your permissions in the platform's native ads manager.


---

# Meta Ads — Tool Reference
Source: https://hopkin.ai/docs/meta-ads

## meta_ads_get_account_summary

Standardized account-level performance summary for cross-platform comparison. Normalized format identical to google_ads_get_account_summary. Includes conversion_detail breakdown from both Meta actions and conversions arrays. Preferred over get_insights or get_performance_report for quick account-level overviews. Always fetches fresh data.

Annotations: read-only, idempotent

Parameters:
- account_id (string, required): Meta ad account ID
- date_preset (string, optional): Predefined date range (e.g., last_7d, last_30d, this_month). Values: today, yesterday, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, lifetime, maximum
- time_range (object, optional): Custom date range {since, until} in YYYY-MM-DD
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"act_123","reason":"Quick performance overview"}

CLI: hopkin meta account-summary get

Response: markdown

## meta_ads_get_activities

Retrieve activity/change history for a Meta ad account or specific entity. Cached with 1-hour TTL; use refresh=true for fresh data. Meta's API only returns the last 7 days per call, but cached data accumulates for historical lookups.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): The ad account ID (with or without act_ prefix)
- entity_id (string, optional): Filter activities to a specific entity (campaign, ad set, or ad ID). If omitted, returns account-level activities.
- entity_type (string, optional): Type of entity: ACCOUNT, CAMPAIGN, AD_SET, AD. Used with entity_id for filtering.. Values: ACCOUNT, CAMPAIGN, AD_SET, AD
- start_date (string, optional): Start date for activity range (ISO 8601, e.g. 2024-01-01)
- end_date (string, optional): End date for activity range (ISO 8601, e.g. 2024-01-31)
- limit (integer, optional): Number of activities per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh activity data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"View recent account changes"}

CLI: hopkin meta activities get

Response: markdown

## meta_ads_list_ad_accounts

List Meta ad accounts with search, status filtering, single/multi-account lookup by ID, and pagination. Cached by default; pass refresh=true for latest data. Entities may include _stored_preferences and optionally recent activities.

Annotations: read-only, open-world

Parameters:
- refresh (boolean, optional): Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- cursor (string, optional): Pagination cursor from previous response
- search (string, optional): Search ad accounts by name (case-insensitive partial match)
- account_id (string, optional): Filter by exact account ID (without act_ prefix)
- account_ids (array, optional): Get multiple accounts by ID. Mutually exclusive with account_id. When provided, ignores other filters/pagination.
- status (integer, optional): Account status code (1=Active, 2=Disabled, etc.)
- limit (integer, optional): Number of accounts per page (default: 20, max: 100)
- include_activities (boolean, optional): Include recent activity log (last 7 days of changes) for each entity
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"List all ad accounts"}

CLI: hopkin meta ad-accounts list

Response: markdown

## meta_ads_get_ad_creative_report

Ad-level performance report with full funnel metrics. All conversion types shown individually. Supports two grouping modes: ad_name (default, aggregates ads sharing the same name with a representative ad_id for preview) and ad_id (one row per ad). The representative ad_id can be passed to meta_ads_preview_ads. Always fetches fresh data.

Annotations: read-only, idempotent

Parameters:
- account_id (string, required): Meta ad account ID
- time_range (object, required): Required date range {since, until} in YYYY-MM-DD
- level (string, optional): Grouping level: ad_name (default, aggregate ads sharing the same name, providing a representative ad_id that can be passed to meta_ads_preview_ads) or ad_id (one row per ad). Values: ad_id, ad_name
- time_increment (unknown, optional): Time grouping: 1=daily, 7=weekly, or "monthly"
- breakdowns (array, optional): Segment by dimension. Pass multiple values for cross-tabulated rows (e.g. ["age","gender"] → one row per "35-44 / female" segment). Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma
- filtering (array, optional): Filters as [{field, operator, value}]
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"act_123","time_range":{"since":"2024-01-01","until":"2024-01-31"},"reason":"Review individual ad performance"}

CLI: hopkin meta ad-creative-report get

Response: json

## meta_ads_list_ads

List ads for a Meta ad account with ad set filtering, status, name search, single/multi-ad lookup by ID, and pagination. Each ad includes a Landing URL when available (extracted from object_story_spec, link_url, or asset_feed_spec depending on ad format). A "Landing Page URLs" summary section at the end of the response lists all unique destination URLs found — use this to quickly answer landing page questions without reading every ad. Set include_assets=true to include resolved creative media URLs (adds latency for cache misses). Entities may include _stored_preferences and optionally recent activities.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): The ad account ID (with or without act_ prefix)
- ad_id (string, optional): Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.
- ad_ids (array, optional): Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination.
- adset_id (string, optional): Filter by ad set ID
- search (string, optional): Search ads by name (case-insensitive partial match)
- status (array, optional): Filter by ad status: ACTIVE, PAUSED, DELETED, ARCHIVED
- limit (integer, optional): Number of ads per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- include_activities (boolean, optional): Include recent activity log (last 7 days of changes) for each entity
- include_assets (boolean, optional): Include resolved creative asset URLs (asset_url, thumbnail_url, asset_type) for each ad. Uses cached GCS URLs when available.
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"List ads"}

CLI: hopkin meta ads list

Response: markdown

## meta_ads_list_adsets

List ad sets for a Meta ad account with campaign filtering, status, name search, single/multi-adset lookup by ID, and pagination. Entities may include _stored_preferences and optionally recent activities.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): The ad account ID (with or without act_ prefix)
- adset_id (string, optional): Get a specific ad set by ID. When provided, returns only that ad set and ignores other filters/pagination.
- adset_ids (array, optional): Get multiple ad sets by ID. Mutually exclusive with adset_id. When provided, ignores other filters/pagination.
- campaign_id (string, optional): Filter by campaign ID
- search (string, optional): Search ad sets by name (case-insensitive partial match)
- status (array, optional): Filter by ad set status: ACTIVE, PAUSED, DELETED, ARCHIVED
- limit (integer, optional): Number of ad sets per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- include_activities (boolean, optional): Include recent activity log (last 7 days of changes) for each entity
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"List ad sets"}

CLI: hopkin meta adsets list

Response: markdown

## meta_ads_check_auth_status

Troubleshoot authentication issues and get user profile info. Only use this tool when another tool fails with a permission or authentication error — do NOT call proactively.

Annotations: read-only, idempotent

Parameters:
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Another tool returned an auth error, checking account connection status"}

CLI: hopkin meta auth check

Response: markdown

## meta_ads_list_campaigns

List campaigns for a Meta ad account with status filtering, name search, single/multi-campaign lookup by ID, and pagination. Entities may include _stored_preferences and optionally recent activities.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): The ad account ID (with or without act_ prefix)
- status (array, optional): Filter by campaign status: ACTIVE, PAUSED, DELETED, ARCHIVED
- limit (integer, optional): Number of campaigns per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- campaign_id (string, optional): Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination.
- campaign_ids (array, optional): Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination.
- search (string, optional): Search campaigns by name (case-insensitive partial match)
- include_activities (boolean, optional): Include recent activity log (last 7 days of changes) for each entity
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"List campaigns"}

CLI: hopkin meta campaigns list

Response: markdown

## meta_ads_developer_feedback

Submit feedback about missing tools, improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues like auth or API errors.

Annotations: idempotent, open-world

Parameters:
- feedback_type (string, required): Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow). Values: new_tool, improvement, bug, workflow_gap
- title (string, required): Concise title summarizing the feedback
- description (string, required): What is needed and why
- current_workaround (string, optional): Current workaround, if any
- priority (string, optional): Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue). Values: low, medium, high
- interface (string, optional): Interface the feedback originated from: MCP (default) or CLI. Values: MCP, CLI
- reason (string, required): Why this tool call is needed

Example:
  {"feedback_type":"new_tool","title":"Bulk campaign status toggle","description":"Need to pause/enable multiple campaigns at once","priority":"high","reason":"User asked to pause 12 campaigns individually"}

CLI: hopkin meta developer-feedback send

Response: markdown

## meta_ads_get_insights

Retrieve performance metrics from Meta Ads with date presets/custom ranges, time grouping, entity-level aggregation, dimensional breakdowns, and filtering. Always fetches fresh data. Provide date_preset or time_range. For standard full-funnel analysis, prefer meta_ads_get_performance_report; use this for custom fields, hourly/creative-asset breakdowns, or video metrics.

Annotations: read-only, idempotent

Parameters:
- account_id (string, required): Meta ad account ID
- date_preset (string, optional): Predefined date range: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_quarter, last_quarter, this_year, last_year, lifetime, maximum. Values: today, yesterday, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, lifetime, maximum
- time_range (object, optional): Custom date range {since, until} in YYYY-MM-DD
- time_increment (unknown, optional): Time grouping: 1=daily, 7=weekly, or "monthly"
- level (string, optional): Aggregation level: account, campaign, adset, ad. Values: account, campaign, adset, ad
- fields (array, optional): Metrics to retrieve (defaults to standard set)
- breakdowns (array, optional): Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. ["age","gender"] → one row per "35-44 / female" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, dma, device_platform, publisher_platform, platform_position, impression_device, frequency_value, place_page_id, product_id, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset
- action_breakdowns (array, optional): Action breakdown dimensions: action_type, action_target_id, action_destination, action_reaction, action_video_sound, action_video_type, action_carousel_card_id, action_carousel_card_name
- filtering (array, optional): Filters as [{field, operator, value}]
- action_attribution_windows (array, optional): Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: ["7d_click"] for 7-day click only. Default (when omitted): ["7d_click","1d_view"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"act_123456789","date_preset":"last_7d","action_attribution_windows":["7d_click"],"reason":"Isolate 7-day click attribution conversions for accurate ROAS measurement"}

CLI: hopkin meta insights get

Response: json

## meta_ads_get_performance_report

Full impression-to-conversion funnel report with delivery, engagement, actions, conversions, ROAS, and quality rankings. Preferred over meta_ads_get_insights for standard analysis. Use get_insights only for custom fields, hourly/creative-asset breakdowns, or video metrics. Always fetches fresh data.

Annotations: read-only, idempotent

Parameters:
- account_id (string, required): Meta ad account ID
- time_range (object, required): Required date range {since, until} in YYYY-MM-DD
- time_increment (unknown, optional): Time grouping: 1=daily, 7=weekly, or "monthly"
- level (string, optional): Aggregation level (default: account): account, campaign, adset, ad. Values: account, campaign, adset, ad
- breakdowns (array, optional): Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. ["age","gender"] → one row per "35-44 / female" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma
- filtering (array, optional): Filters as [{field, operator, value}]
- action_attribution_windows (array, optional): Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: ["7d_click"] for 7-day click only. Default (when omitted): ["7d_click","1d_view"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"act_123","time_range":{"since":"2024-01-01","until":"2024-01-31"},"reason":"Monthly performance review"}

CLI: hopkin meta performance-report get

Response: json

## meta_ads_ping

Health check for the Meta Ads MCP server.

Annotations: read-only, idempotent

Parameters:
- message (string, optional): Optional message to echo back
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Verify server is running"}

CLI: hopkin meta ping

Response: markdown

## meta_ads_get_pixel_health

Comprehensive pixel health check: metadata, CAPI connection status, event volume stats, automatic matching config, and diagnostic checks (including event match quality indicators). Use this to diagnose tracking issues before analyzing ad performance — low ROAS could be a tracking problem, not a campaign problem.

Annotations: read-only, idempotent

Parameters:
- account_id (string, required): The ad account ID (with or without act_ prefix)
- pixel_id (string, optional): Specific pixel ID to check. If omitted, checks all pixels on the account.
- event_names (array, optional): Filter event stats to these event names (e.g. ["Purchase", "Lead"])
- days_back (integer, optional): Number of days of event stats to include (default: 28, max: 90)
- limit (integer, optional): Max pixels per page (default: 5, max: 20)
- cursor (string, optional): Pagination cursor from previous response
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"act_123","reason":"Audit tracking setup"}

CLI: hopkin meta pixel-health get

Response: markdown

## meta_ads_store_preference

Store a persistent preference for a Meta ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.

Annotations: idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID (e.g. act_123456, 23842453456789)
- key (string, required): Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)
- value (unknown, optional): Preference value — string, number, boolean, or JSON object
- source (string, optional): Who set this preference: agent (default), user, or system. Values: agent, user, system
- note (string, optional): Optional context about why this preference was set
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"act_123","key":"preferred_conversion_metric","value":"ROAS","reason":"User wants ROAS as default metric"}

CLI: hopkin meta preferences store

Response: markdown

## meta_ads_get_preferences

Get all stored preferences for a Meta ad entity. Preferences are also auto-attached to list tool responses as _stored_preferences.

Annotations: read-only, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"act_123","reason":"Check stored preferences"}

CLI: hopkin meta preferences get

Response: markdown

## meta_ads_delete_preference

Delete a stored preference by key. No-op if it doesn't exist.

Annotations: destructive, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- key (string, required): The preference key to delete
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"campaign","entity_id":"456","key":"budget_alert_threshold","reason":"User no longer wants budget alerts"}

CLI: hopkin meta preference delete

Response: markdown

---

# Google Ads — Tool Reference
Source: https://hopkin.ai/docs/google-ads

## google_ads_get_account_summary

Standardized account-level performance summary for cross-platform comparison. Returns normalized metrics identical to meta_ads_get_account_summary, with per-conversion-action breakdown. Preferred over insights or performance report for quick account overviews. Always fetches fresh data.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- date_preset (string, optional): Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. Values: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
- date_range (object, optional): Custom date range {start_date, end_date} in YYYY-MM-DD
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"Quick performance overview"}

CLI: hopkin google account-summary get

Response: markdown

## google_ads_get_activities

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.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- start_date (string, optional): Start date in YYYY-MM-DD format. Defaults to 7 days ago. Must be within the past 30 days.
- end_date (string, optional): End date in YYYY-MM-DD format. Defaults to today.
- resource_type (string, optional): Filter to a specific resource type: AD, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, CAMPAIGN, CAMPAIGN_BUDGET, CAMPAIGN_CRITERION, ASSET, ASSET_SET. Values: AD, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, CAMPAIGN, CAMPAIGN_BUDGET, CAMPAIGN_CRITERION, ASSET, ASSET_SET
- asset_ids (array, optional): Filter to specific asset IDs (numeric). Automatically sets resource_type to ASSET.
- limit (integer, optional): Maximum number of activities to return (1-1000, default 50)
- cursor (string, optional): Opaque pagination cursor from a previous response
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"Review recent account changes"}

CLI: hopkin google activities get

Response: markdown

## google_ads_list_accounts

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.

Annotations: read-only, open-world

Parameters:
- customer_id (string, optional): Get a specific account by Customer ID. When provided, returns only that account and ignores other filters/pagination.
- customer_ids (array, optional): Get multiple accounts by Customer ID. Mutually exclusive with customer_id. When provided, ignores other filters/pagination.
- refresh (boolean, optional): 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 (string, optional): Pagination cursor from previous response
- search (string, optional): Search accounts by name (case-insensitive partial match)
- limit (integer, optional): Number of accounts per page (default: 20, max: 100)
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"List all ad accounts"}

CLI: hopkin google accounts list

Response: markdown

## google_ads_list_mcc_child_accounts

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.

Annotations: read-only, idempotent, open-world

Parameters:
- mcc_id (string, required): The MCC (Manager) Customer ID whose child accounts to list (10 digits, dashes accepted)
- search (string, optional): Search child accounts by name or customer ID (case-insensitive partial match)
- limit (integer, optional): Number of accounts per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- reason (string, required): Why this tool call is needed

Example:
  {"mcc_id":"1234567890","reason":"List MCC child accounts"}

CLI: hopkin google mcc-child-accounts list

Response: markdown

## google_ads_list_ad_groups

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.

Annotations: read-only, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- campaign_id (string, optional): Filter by campaign ID (optional)
- ad_group_id (string, optional): Get a specific ad group by ID. When provided, returns only that ad group and ignores other filters/pagination.
- ad_group_ids (array, optional): Get multiple ad groups by ID. Mutually exclusive with ad_group_id. When provided, ignores other filters/pagination.
- search (string, optional): Search ad groups by name (case-insensitive partial match)
- status (array, optional): Filter by ad group status: ENABLED, PAUSED, REMOVED
- limit (integer, optional): Number of ad groups per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"List ad groups"}

CLI: hopkin google ad-groups list

Response: markdown

## google_ads_list_ads

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.

Annotations: read-only, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- ad_group_id (string, optional): Filter by ad group ID (optional)
- ad_id (string, optional): Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.
- ad_ids (array, optional): Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination.
- search (string, optional): Search ads by name (case-insensitive partial match)
- status (array, optional): Filter by ad status: ENABLED, PAUSED, REMOVED
- limit (integer, optional): Number of ads per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"List ads"}

CLI: hopkin google ads list

Response: markdown

## google_ads_check_auth_status

Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.

Annotations: read-only, idempotent

Parameters:
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Another tool returned an auth error, checking account connection status"}

CLI: hopkin google auth check

Response: markdown

## google_ads_get_auto_applied_recommendations

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.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"Audit auto-applied recommendation settings"}

CLI: hopkin google auto-applied-recommendations get

Response: markdown

## google_ads_list_campaigns

List campaigns for a Google Ads account. Supports status filtering, search, and pagination. Results are cached; pass refresh=true for latest data.

Annotations: read-only, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- campaign_id (string, optional): Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination.
- campaign_ids (array, optional): Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination.
- search (string, optional): Search campaigns by name (case-insensitive partial match)
- status (array, optional): Filter by campaign status: ENABLED, PAUSED, REMOVED
- limit (integer, optional): Number of campaigns per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- refresh (boolean, optional): Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"List campaigns"}

CLI: hopkin google campaigns list

Response: markdown

## google_ads_get_conversion_actions

List conversion actions configured for a Google Ads account. Use this to understand which conversions are tracked before querying performance reports or insights with conversion segments.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- status (string, optional): Filter by status (default: returns all non-REMOVED). ENABLED, REMOVED, HIDDEN. Values: ENABLED, REMOVED, HIDDEN
- limit (number, optional): Maximum number of conversion actions to return (default: 100, max: 500)
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"See configured conversion actions"}

CLI: hopkin google conversion-actions get

Response: markdown

## google_ads_developer_feedback

Submit feedback about missing tools, needed improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues (auth errors, API errors).

Annotations: idempotent, open-world

Parameters:
- feedback_type (string, required): Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow). Values: new_tool, improvement, bug, workflow_gap
- title (string, required): Concise title summarizing the feedback
- description (string, required): What is needed and why
- current_workaround (string, optional): Current workaround, if any
- priority (string, optional): Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue). Values: low, medium, high
- interface (string, optional): Interface the feedback originated from: MCP (default) or CLI. Values: MCP, CLI
- reason (string, required): Why this tool call is needed

Example:
  {"feedback_type":"new_tool","title":"Bulk campaign status toggle","description":"Need to pause/enable multiple campaigns at once","priority":"high","reason":"User asked to pause 12 campaigns individually"}

CLI: hopkin google developer-feedback send

Response: markdown

## google_ads_get_geo_performance

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.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- date_preset (string, optional): Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. Values: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
- date_range (object, optional): Custom date range {start_date, end_date} in YYYY-MM-DD
- geo_level (string, optional): Geographic granularity. "country" uses geographic_view.country_criterion_id; others add a segments.geo_target_* drill-down. Only one geo level per query.. Values: country, geo_target_city, geo_target_region, geo_target_state, geo_target_metro, geo_target_province, geo_target_county, geo_target_district, geo_target_most_specific_location, geo_target_postal_code, geo_target_airport, geo_target_canton
- level (string, optional): Entity breakdown level. Values: ACCOUNT, CAMPAIGN, AD_GROUP
- segments (array, optional): Additional non-geo segments: date, device, ad_network_type
- campaign_id (string, optional): Filter to a specific campaign ID
- ad_group_id (string, optional): Filter to a specific ad group ID
- limit (number, optional): Max rows returned (default 50, max 200)
- include_all_conversions (boolean, optional): When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked "Include in Conversions".
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","date_preset":"LAST_7_DAYS","geo_level":"country","reason":"Compare spend by country"}

CLI: hopkin google geo-performance get

Response: markdown

## google_ads_get_insights

Retrieve performance metrics using GAQL with full control over metrics, segments, levels, and date ranges. Always fetches fresh data. Use segments=['ad_network_type'] to break down Performance Max campaigns by channel (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.). For standard analysis, prefer google_ads_get_performance_report; use this only for custom metric selection, search impression share diagnostics, ad_network_type channel breakdowns, or segment combinations not available in the performance report. For geographic data, use google_ads_get_geo_performance instead. Conversion action segments automatically remove incompatible cost-based metrics. Budget-lost impression share variants are campaign-level only.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- date_preset (string, optional): Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. Values: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
- date_range (object, optional): Custom date range {start_date, end_date} in YYYY-MM-DD
- level (string, optional): Report level (default: ACCOUNT): ACCOUNT, CAMPAIGN, AD_GROUP, AD. Values: ACCOUNT, CAMPAIGN, AD_GROUP, AD
- metrics (array, optional): Metrics to retrieve (defaults to standard set)
- segments (array, optional): 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 (string, optional): Filter to a specific campaign ID
- ad_group_id (string, optional): Filter to a specific ad group ID
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","date_preset":"LAST_30_DAYS","metrics":["all_conversions","all_conversions_value","value_per_all_conversions"],"segments":["conversion_action_name"],"reason":"All conversions breakdown by action"}

CLI: hopkin google insights get

Response: json

## google_ads_get_keyword_performance

Get keyword-level performance metrics including quality score, match type, status, and search impression share. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per keyword. Includes a parallel conversion breakdown by ad group. Always fetches fresh data.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- date_preset (string, optional): Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. Values: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
- date_range (object, optional): Custom date range {start_date, end_date} in YYYY-MM-DD
- campaign_id (string, optional): Filter to a specific campaign ID
- ad_group_id (string, optional): Filter to a specific ad group ID
- keyword_match_type (string, optional): Filter by match type: EXACT, PHRASE, BROAD. Values: EXACT, PHRASE, BROAD
- status (array, optional): Filter by keyword status: ENABLED, PAUSED, REMOVED
- limit (integer, optional): Maximum number of rows to return (1-1000, default 100)
- order_by (string, optional): Sort by metric (descending): impressions, clicks, cost, conversions, ctr. Values: impressions, clicks, cost, conversions, ctr
- include_all_conversions (boolean, optional): When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked "Include in Conversions".
- segments (array, optional): Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split keyword metrics by channel (SEARCH vs SEARCH_PARTNERS).
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","date_preset":"LAST_7_DAYS","reason":"Keyword performance review"}

CLI: hopkin google keyword-performance get

Response: markdown

## google_ads_get_search_terms_report

Get actual search queries that triggered ads, with performance metrics and keyword match status. Google may not disclose all terms for privacy. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per search term. Always fetches fresh data. Conversion breakdown and landing page lookups are opt-in to control response size. For Performance Max campaigns, set pmax_search_categories=true to get search category insights (grouped themes) instead of individual search terms.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- date_preset (string, optional): Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. Values: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
- date_range (object, optional): Custom date range {start_date, end_date} in YYYY-MM-DD
- campaign_id (string, optional): Filter to a specific campaign ID
- ad_group_id (string, optional): Filter to a specific ad group ID
- search_term_status (array, optional): Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE
- limit (integer, optional): Maximum number of rows to return (1-1000, default 100)
- order_by (string, optional): Sort by metric (descending): impressions, clicks, cost, conversions, ctr. Values: impressions, clicks, cost, conversions, ctr
- include_all_conversions (boolean, optional): 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 (boolean, optional): When true, runs a parallel query to include conversion breakdown by ad group and conversion action. Adds significant response size — omit when response size is a concern. Default: false.
- include_landing_pages (boolean, optional): 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 (boolean, optional): 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 (array, optional): Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). Ignored when pmax_search_categories is true.
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","date_preset":"LAST_7_DAYS","reason":"Search term analysis"}

CLI: hopkin google search-terms-report get

Response: markdown

## google_ads_list_negative_keyword_lists

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.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- list_id (string, optional): Filter to a specific shared set ID to see its keywords and campaign associations
- include_keywords (boolean, optional): Include the keywords in each list. Defaults to false for overview.
- include_campaign_associations (boolean, optional): Include which campaigns each list is attached to. Defaults to false.
- limit (integer, optional): Number of lists per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"Audit shared negative keyword lists"}

CLI: hopkin google negative-keyword-lists list

Response: markdown

## google_ads_list_negative_keywords

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.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- campaign_id (string, optional): Filter to a specific campaign ID
- ad_group_id (string, optional): Filter to a specific ad group ID
- level (string, optional): Which level of negative keywords to return. Defaults to ALL.. Values: CAMPAIGN, AD_GROUP, ALL
- match_type (array, optional): Filter by match type: EXACT, PHRASE, BROAD
- limit (integer, optional): Number of negative keywords per page (default: 20, max: 100)
- cursor (string, optional): Pagination cursor from previous response
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","reason":"Audit negative keywords"}

CLI: hopkin google negative-keywords list

Response: markdown

## google_ads_get_performance_report

Comprehensive performance report with funnel metrics and per-conversion-action breakdowns. Preferred over google_ads_get_insights for standard analysis. Runs parallel queries for top-level funnel and conversion action breakdown. Search impression share is included at CAMPAIGN and AD_GROUP levels (budget-lost variants campaign-level only). Use google_ads_get_insights for custom metric selection. For geographic data, use google_ads_get_geo_performance instead.

Annotations: read-only, idempotent, open-world

Parameters:
- customer_id (string, required): The Google Ads Customer ID (10 digits, with or without dashes)
- login_customer_id (string, optional): MCC (Manager) Customer ID; required for managed accounts
- date_preset (string, optional): Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. Values: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
- date_range (object, optional): Custom date range {start_date, end_date} in YYYY-MM-DD
- level (string, optional): Report level (default: CAMPAIGN): ACCOUNT, CAMPAIGN, AD_GROUP, AD. Values: ACCOUNT, CAMPAIGN, AD_GROUP, AD
- segments (array, optional): Additional segments for the main metrics: date, device, ad_network_type. Conversion action breakdowns are always included automatically via a separate query.
- campaign_id (string, optional): Filter to a specific campaign ID
- ad_group_id (string, optional): Filter to a specific ad group ID
- include_all_conversions (boolean, optional): When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked "Include in Conversions" (e.g., view-through, cross-device, store visits).
- reason (string, required): Why this tool call is needed

Example:
  {"customer_id":"1234567890","date_preset":"LAST_30_DAYS","reason":"Monthly performance review"}

CLI: hopkin google performance-report get

Response: json

## google_ads_ping

Health check for the Google Ads MCP server.

Annotations: read-only, idempotent

Parameters:
- message (string, optional): Optional message to echo back
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Verify server is running"}

CLI: hopkin google ping

Response: markdown

## google_ads_store_preference

Store a persistent preference for a Google Ads entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.

Annotations: idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID (e.g. act_123456, 23842453456789)
- key (string, required): Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)
- value (unknown, optional): Preference value — string, number, boolean, or JSON object
- source (string, optional): Who set this preference: agent (default), user, or system. Values: agent, user, system
- note (string, optional): Optional context about why this preference was set
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"1234567890","key":"preferred_conversion_metric","value":"conversions","reason":"User wants conversions as default metric"}

CLI: hopkin google preferences store

Response: markdown

## google_ads_get_preferences

Get all stored preferences for a Google Ads entity. Preferences are also automatically attached to entity-listing tool responses as _stored_preferences, so you often don't need to call this explicitly.

Annotations: read-only, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"1234567890","reason":"Check stored preferences"}

CLI: hopkin google preferences get

Response: markdown

## google_ads_delete_preference

Delete a stored preference for a Google Ads entity by key. No-op if the preference doesn't exist.

Annotations: destructive, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- key (string, required): The preference key to delete
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"campaign","entity_id":"456","key":"budget_alert_threshold","reason":"User no longer wants budget alerts"}

CLI: hopkin google preference delete

Response: markdown

---

# LinkedIn Ads — Tool Reference
Source: https://hopkin.ai/docs/linkedin-ads

## linkedin_ads_get_account_summary

Get a high-level performance summary for a LinkedIn Ads account including spend, impressions, clicks, conversions, leads, and conversion breakdown. Conversion data may be delayed 24-72 hours.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- date_preset (string, optional): . Values: LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_90_DAYS
- start_date (string, optional): 
- end_date (string, optional): 
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","date_preset":"LAST_30_DAYS","reason":"User wants an account overview"}

CLI: hopkin linkedin account-summary get

Response: markdown

## linkedin_ads_list_ad_accounts

List LinkedIn Sponsored Ad Accounts accessible to the authenticated user.

Annotations: read-only, idempotent, open-world

Parameters:
- status (array, optional): Filter by account status. Defaults to [ACTIVE].
- type (string, optional): Filter by account type.. Values: BUSINESS, ENTERPRISE
- include_test_accounts (boolean, optional): Include test accounts. Defaults to false.
- limit (integer, optional): 
- cursor (string, optional): Opaque pagination cursor.
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"User wants to see their LinkedIn ad accounts"}

CLI: hopkin linkedin ad-accounts list

Response: markdown

## linkedin_ads_check_auth_status

Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.

Annotations: read-only, idempotent

Parameters:
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Another tool returned an auth error, checking LinkedIn account connection status"}

CLI: hopkin linkedin auth check

Response: markdown

## linkedin_ads_get_budget_pricing

Get bid ranges and daily budget limits for a LinkedIn campaign type and audience. Call this before creating a campaign to understand recommended bids. DYNAMIC campaign type is not supported by this endpoint.

Annotations: read-only, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- campaign_type (string, required): Campaign type. DYNAMIC is not supported by this endpoint.. Values: TEXT_AD, SPONSORED_UPDATES, SPONSORED_INMAILS
- bid_type (string, required): Bid type. CPV is only valid for SPONSORED_UPDATES video campaigns.. Values: CPM, CPC, CPV
- match_type (string, required): . Values: EXACT, AUDIENCE_EXPANDED
- currency (string, required): ISO-4217 currency code (e.g. USD, GBP).
- location_urns (array, required): Target location URNs (e.g. urn:li:geo:103644278 for USA).
- seniority_urns (array, optional): Target seniority URNs (e.g. urn:li:seniority:4 for Senior).
- job_function_urns (array, optional): Target job function URNs.
- industry_urns (array, optional): Target industry URNs.
- company_size_urns (array, optional): Target company size range URNs (e.g. urn:li:staffCountRange:(51,200)).
- objective_type (string, optional): Affects suggested bid.
- daily_budget_amount (number, optional): Current or target daily budget (influences suggested bid calculation).
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","campaign_type":"SPONSORED_UPDATES","bid_type":"CPM","match_type":"EXACT","currency":"USD","location_urns":["urn:li:geo:103644278"],"reason":"User wants to know bid ranges before creating a campaign"}

CLI: hopkin linkedin budget-pricing get

Response: markdown

## linkedin_ads_list_campaign_groups

List LinkedIn Campaign Groups for an ad account. Campaign groups are the top-level organizational unit containing campaigns.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- status (array, optional): Filter by status. Defaults to [ACTIVE, PAUSED].
- campaign_group_id (string, optional): Fetch a single campaign group by numeric ID.
- campaign_group_ids (array, optional): Fetch specific campaign groups by numeric IDs (batch GET).
- limit (integer, optional): 
- cursor (string, optional): 
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"User wants to see campaign groups"}

CLI: hopkin linkedin campaign-groups list

Response: markdown

## linkedin_ads_list_campaigns

List LinkedIn Campaigns for an ad account. Campaigns define targeting, bidding, and budget within a campaign group.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- status (array, optional): Filter by status. Defaults to [ACTIVE, PAUSED].
- campaign_group_id (string, optional): Filter by campaign group (numeric ID).
- type (array, optional): Filter by campaign type.
- campaign_id (string, optional): Fetch a single campaign by numeric ID.
- campaign_ids (array, optional): Fetch specific campaigns by numeric IDs (batch filter).
- limit (integer, optional): 
- cursor (string, optional): 
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"User wants to see campaigns"}

CLI: hopkin linkedin campaigns list

Response: markdown

## linkedin_ads_list_creatives

List LinkedIn Creatives (ads) for an ad account. IMPORTANT: Always explicitly pass resolve_content=true when the user asks about ad copy, headlines, body text, URLs, or creative details — do not omit it and rely on the default. Only set resolve_content=false when the user needs metadata-only and has NOT asked about content.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- campaign_ids (array, optional): Filter by campaign IDs (numeric).
- status (array, optional): Filter by intended status. Defaults to [ACTIVE, PAUSED, DRAFT].
- resolve_content (boolean, optional): Resolve ad copy (headline, body text, destination URL) from linked posts/shares. Default: true. Set to false only when you need metadata-only (IDs, status, content type) and explicitly do NOT need ad copy.
- creative_id (string, optional): Fetch a single creative by URN or numeric ID.
- creative_ids (array, optional): Fetch specific creatives by numeric IDs (batch filter).
- limit (integer, optional): 
- cursor (string, optional): 
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"User wants to see ads"}

CLI: hopkin linkedin creatives list

Response: markdown

## linkedin_ads_developer_feedback

Submit feedback about missing tools, improvements, or workflow gaps in the LinkedIn Ads MCP toolset. Not for user-facing issues like auth or API errors.

Annotations: idempotent, open-world

Parameters:
- feedback_type (string, required): Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow). Values: new_tool, improvement, bug, workflow_gap
- title (string, required): Concise title summarizing the feedback
- description (string, required): What is needed and why
- current_workaround (string, optional): Current workaround, if any
- priority (string, optional): Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue). Values: low, medium, high
- interface (string, optional): Interface the feedback originated from: MCP (default) or CLI. Values: MCP, CLI
- reason (string, required): Why this tool call is needed

Example:
  {"feedback_type":"new_tool","title":"Bulk campaign status toggle","description":"Need to pause/enable multiple LinkedIn campaigns at once rather than one by one","priority":"high","reason":"User asked to pause 8 campaigns individually"}

CLI: hopkin linkedin developer-feedback send

Response: markdown

## linkedin_ads_get_insights

Get LinkedIn Ads analytics with a single pivot dimension. For standard analysis, prefer linkedin_ads_get_performance_report; use this only for MEMBER_* demographic pivots (unique to LinkedIn) or custom metric queries not available in the performance report. MEMBER_* pivots have a 3-event minimum threshold and 12-24 hour data delay, so totals may not match account-level numbers. Max 18 metrics per query.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- pivot (string, required): Analytics pivot dimension. MEMBER_* pivots provide demographic breakdowns unique to LinkedIn.. Values: ACCOUNT, CAMPAIGN_GROUP, CAMPAIGN, CREATIVE, SHARE, COMPANY, CONVERSION, CONVERSATION_NODE, SERVING_LOCATION, PLACEMENT_NAME, IMPRESSION_DEVICE_TYPE, CARD_INDEX, MEMBER_COMPANY_SIZE, MEMBER_INDUSTRY, MEMBER_SENIORITY, MEMBER_JOB_TITLE, MEMBER_JOB_FUNCTION, MEMBER_COUNTRY_V2, MEMBER_REGION_V2, MEMBER_COUNTY, MEMBER_COMPANY
- date_preset (string, optional): . Values: LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_90_DAYS
- start_date (string, optional): ISO date YYYY-MM-DD. Use with end_date to override date_preset.
- end_date (string, optional): 
- time_granularity (string, optional): . Values: ALL, DAILY, MONTHLY
- campaign_ids (array, optional): Filter to specific campaigns (numeric IDs).
- campaign_group_ids (array, optional): Filter to specific campaign groups (numeric IDs).
- metrics (array, optional): LinkedIn adAnalytics metric field names (camelCase, exact names required). Core: impressions, clicks, costInLocalCurrency, costInUsd. Conversions: externalWebsiteConversions, externalWebsitePostClickConversions, externalWebsitePostViewConversions, conversionValueInLocalCurrency. Leads: oneClickLeads, oneClickLeadFormOpens, qualifiedLeads. Video: videoViews, videoCompletions. Engagement: totalEngagements, shares, follows, reactions, comments, landingPageClicks, textUrlClicks, companyPageClicks. Card: cardImpressions, cardClicks, viralCardImpressions, viralCardClicks. Reach: approximateMemberReach (only with ACCOUNT/CAMPAIGN_GROUP/CAMPAIGN pivot, ≤92 day range). IMPORTANT: Do NOT use aliases like "conversions", "leads", "spend", or "reach" — use the exact camelCase field names listed above. Max 18 (pivotValues + dateRange count toward the 20-field API limit). Defaults to: impressions, clicks, costInLocalCurrency, costInUsd, externalWebsiteConversions, oneClickLeads, videoViews, totalEngagements.
- include_conversion_breakdown (boolean, optional): When true (and pivot is not CONVERSION), runs a second query to break down conversions per action with names.
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","pivot":"MEMBER_JOB_FUNCTION","date_preset":"LAST_30_DAYS","reason":"Demographic breakdown by job function"}

CLI: hopkin linkedin insights get

Response: json

## linkedin_ads_get_partner_conversions

List partner conversions (conversion actions) configured for a LinkedIn Ads account. Use this to understand what conversion tracking is set up before analyzing performance data.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","reason":"User wants to see what partner conversions are configured"}

CLI: hopkin linkedin partner-conversions get

Response: markdown

## linkedin_ads_get_performance_report

Get a full-funnel performance report with up to 3 pivot dimensions and optional per-conversion-action breakdown. MEMBER_* demographic pivots are not supported here — use linkedin_ads_get_insights instead.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Ad account ID (numeric, without URN prefix).
- pivots (array, optional): Up to 3 pivot dimensions. OBJECTIVE_TYPE is only available in q=statistics.
- date_preset (string, optional): . Values: LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_90_DAYS
- start_date (string, optional): 
- end_date (string, optional): 
- time_granularity (string, optional): . Values: ALL, DAILY, MONTHLY
- campaign_ids (array, optional): 
- campaign_group_ids (array, optional): 
- include_conversion_breakdown (boolean, optional): Run a second query for per-conversion-action breakdown. Adds one extra API call.
- reason (string, required): Why this tool call is needed

Example:
  {"account_id":"123456789","pivots":["CAMPAIGN"],"date_preset":"LAST_30_DAYS","reason":"User wants full campaign performance report"}

CLI: hopkin linkedin performance-report get

Response: json

## linkedin_ads_ping

Health check for the LinkedIn Ads MCP server. Does not call the LinkedIn API.

Annotations: read-only, idempotent

Parameters:
- message (string, optional): Optional message to echo back
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Verify server is running"}

CLI: hopkin linkedin ping

Response: markdown

## linkedin_ads_store_preference

Store a persistent preference for a LinkedIn ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys. Entity type "ad_set" maps to LinkedIn campaigns; "ad" maps to creatives.

Annotations: idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID (e.g. act_123456, 23842453456789)
- key (string, required): Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)
- value (unknown, optional): Preference value — string, number, boolean, or JSON object
- source (string, optional): Who set this preference: agent (default), user, or system. Values: agent, user, system
- note (string, optional): Optional context about why this preference was set
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"123456789","key":"preferred_conversion_metric","value":"oneClickLeads","reason":"User wants lead conversions as default metric"}

CLI: hopkin linkedin preferences store

Response: markdown

## linkedin_ads_get_preferences

Get all stored preferences for a LinkedIn Ads entity. Preferences are also automatically attached to entity-listing responses, so you often don't need to call this explicitly.

Annotations: read-only, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"123456789","reason":"Check stored preferences before running report"}

CLI: hopkin linkedin preferences get

Response: markdown

## linkedin_ads_delete_preference

Delete a stored preference for a LinkedIn Ads entity by key. No-op if the preference doesn't exist.

Annotations: destructive, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- key (string, required): The preference key to delete
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"campaign","entity_id":"987654321","key":"budget_alert_threshold","reason":"User no longer wants budget alerts for this campaign"}

CLI: hopkin linkedin preference delete

Response: markdown

---

# Reddit Ads — Tool Reference
Source: https://hopkin.ai/docs/reddit-ads

## reddit_ads_get_account_summary

Get a high-level performance summary for a Reddit ad account over a date range.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Reddit ad account ID.
- date_start (string, required): Start date in YYYY-MM-DD format.
- date_end (string, required): End date in YYYY-MM-DD format.
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit account-summary get

Response: markdown

## reddit_ads_list_ad_accounts

List Reddit ad accounts accessible to the authenticated user.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, optional): Fetch a single ad account by ID.
- account_ids (array, optional): Fetch specific accounts by IDs.
- limit (integer, optional): 
- cursor (string, optional): Opaque pagination cursor.
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit ad-accounts list

Response: markdown

## reddit_ads_list_ad_groups

List Reddit ad groups for an ad account. Shows targeting, bid strategy, and campaign association.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Reddit ad account ID.
- ad_group_id (string, optional): Fetch a single ad group by ID.
- ad_group_ids (array, optional): Fetch specific ad groups by IDs.
- campaign_id (string, optional): Filter by parent campaign ID.
- status (array, optional): Filter by status.
- limit (integer, optional): 
- cursor (string, optional): Opaque pagination cursor.
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit ad-groups list

Response: markdown

## reddit_ads_list_ads

List Reddit ads for an ad account. Shows creative type, headline, click URL, and status.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Reddit ad account ID.
- ad_id (string, optional): Fetch a single ad by ID.
- ad_ids (array, optional): Fetch specific ads by IDs.
- ad_group_id (string, optional): Filter by parent ad group ID.
- status (array, optional): Filter by status.
- limit (integer, optional): 
- cursor (string, optional): Opaque pagination cursor.
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit ads list

Response: markdown

## reddit_ads_check_auth_status

Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.

Annotations: read-only, idempotent, open-world

Parameters:
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit auth check

Response: markdown

## reddit_ads_list_campaigns

List Reddit ad campaigns for an ad account. Shows name, status, objective, and budget information.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Reddit ad account ID.
- campaign_id (string, optional): Fetch a single campaign by ID.
- campaign_ids (array, optional): Fetch specific campaigns by IDs.
- status (array, optional): Filter by status.
- search (string, optional): Search by campaign name (case-insensitive).
- limit (integer, optional): 
- cursor (string, optional): Opaque pagination cursor.
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit campaigns list

Response: markdown

## reddit_ads_list_custom_audiences

List Reddit custom audiences for an ad account. Shows name, type, size, and status.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Reddit ad account ID.
- audience_id (string, optional): Fetch a single custom audience by ID.
- audience_ids (array, optional): Fetch specific audiences by IDs.
- limit (integer, optional): 
- cursor (string, optional): Opaque pagination cursor.
- refresh (boolean, optional): 
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit custom-audiences list

Response: markdown

## reddit_ads_developer_feedback

Submit feedback about missing tools, improvements, bugs, or workflow gaps in the Reddit Ads MCP toolset. Not for user-facing issues like auth or API errors.

Annotations: idempotent, open-world

Parameters:
- feedback_type (string, required): Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow). Values: new_tool, improvement, bug, workflow_gap
- title (string, required): Concise title summarizing the feedback
- description (string, required): What is needed and why
- current_workaround (string, optional): Current workaround, if any
- priority (string, optional): Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue). Values: low, medium, high
- interface (string, optional): Interface the feedback originated from: MCP (default) or CLI. Values: MCP, CLI
- reason (string, required): Why this tool call is needed

Example:
  {"feedback_type":"new_tool","title":"Bulk ad group status toggle","description":"Need to pause/enable multiple ad groups at once rather than one by one","priority":"high","reason":"User asked to pause 10 ad groups individually"}

CLI: hopkin reddit developer-feedback send

Response: markdown

## reddit_ads_ping

Health check for the Reddit Ads MCP server.

Annotations: read-only, idempotent

Parameters:
- message (string, optional): Optional message to echo back
- reason (string, required): Why this tool call is needed

Example:
  {"reason":"Verify server is running"}

CLI: hopkin reddit ping

Response: markdown

## reddit_ads_store_preference

Store a persistent preference for a Reddit ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.

Annotations: idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID (e.g. act_123456, 23842453456789)
- key (string, required): Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)
- value (unknown, optional): Preference value — string, number, boolean, or JSON object
- source (string, optional): Who set this preference: agent (default), user, or system. Values: agent, user, system
- note (string, optional): Optional context about why this preference was set
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"t2_123","key":"preferred_conversion_metric","value":"ROAS","reason":"User wants ROAS as default metric"}

CLI: hopkin reddit preferences store

Response: markdown

## reddit_ads_get_preferences

Get all stored preferences for a Reddit ad entity. Preferences are also auto-attached to list tool responses as _stored_preferences.

Annotations: read-only, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"ad_account","entity_id":"t2_123","reason":"Check stored preferences"}

CLI: hopkin reddit preferences get

Response: markdown

## reddit_ads_delete_preference

Delete a stored preference by key. No-op if it doesn't exist.

Annotations: destructive, idempotent

Parameters:
- entity_type (string, required): Type of ad entity: ad_account, campaign, ad_set, or ad. Values: ad_account, campaign, ad_set, ad
- entity_id (string, required): The platform entity ID
- key (string, required): The preference key to delete
- reason (string, required): Why this tool call is needed

Example:
  {"entity_type":"campaign","entity_id":"456","key":"budget_alert_threshold","reason":"User no longer wants budget alerts"}

CLI: hopkin reddit preference delete

Response: markdown

## reddit_ads_get_performance_report

Get a performance report for a Reddit ad account over a date range, with optional breakdowns and entity filters.

Annotations: read-only, idempotent, open-world

Parameters:
- account_id (string, required): Reddit ad account ID.
- campaign_ids (array, optional): Filter to specific campaign IDs.
- ad_group_ids (array, optional): Filter to specific ad group IDs.
- ad_ids (array, optional): Filter to specific ad IDs.
- date_start (string, required): Start date in YYYY-MM-DD format.
- date_end (string, required): End date in YYYY-MM-DD format.
- breakdown (array, optional): Up to 3 breakdown dimensions. "community" shows subreddit-level data.
- reason (string, required): Why this tool call is needed

CLI: hopkin reddit performance-report get

Response: json

---

# TikTok Ads — Tool Reference
Source: https://hopkin.ai/docs/tiktok-ads

## tiktok_ads_list_ad_groups

List TikTok ad groups for an advertiser. Shows name, status, targeting, and budget.

Annotations: read-only, idempotent, open-world

Parameters:
- limit (integer, optional): Maximum number of results to return (1–100). Default: 20.
- cursor (string, optional): Opaque pagination cursor from a previous response.
- refresh (boolean, optional): Force a fresh fetch bypassing the cache.
- advertiser_id (string, required): TikTok advertiser ID.
- adgroup_id (string, optional): Fetch a single ad group by ID.
- adgroup_ids (array, optional): Fetch specific ad groups by IDs.
- campaign_ids (array, optional): Filter by parent campaign IDs.
- status (array, optional): Filter by primary status.
- search (string, optional): Search ad groups by name (case-insensitive).
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok ad-groups list

Response: markdown

## tiktok_ads_get_ad_group

Get details for a single TikTok ad group by ID.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- adgroup_id (string, required): Ad group ID.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok ad-group get

Response: markdown

## tiktok_ads_list_ads

List TikTok ads for an advertiser. Shows name, status, creative, and ad group association.

Annotations: read-only, idempotent, open-world

Parameters:
- limit (integer, optional): Maximum number of results to return (1–100). Default: 20.
- cursor (string, optional): Opaque pagination cursor from a previous response.
- refresh (boolean, optional): Force a fresh fetch bypassing the cache.
- advertiser_id (string, required): TikTok advertiser ID.
- ad_id (string, optional): Fetch a single ad by ID.
- ad_ids (array, optional): Fetch specific ads by IDs.
- campaign_ids (array, optional): Filter by parent campaign IDs.
- adgroup_ids (array, optional): Filter by parent ad group IDs.
- status (array, optional): Filter by primary status.
- search (string, optional): Search ads by name (case-insensitive).
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok ads list

Response: markdown

## tiktok_ads_get_ad

Get details for a single TikTok ad by ID.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- ad_id (string, required): Ad ID.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok ad get

Response: markdown

## tiktok_ads_list_advertisers

List TikTok advertiser accounts accessible to the authenticated user. Shows name, ID, status, currency, and timezone.

Annotations: read-only, idempotent, open-world

Parameters:
- limit (integer, optional): Maximum number of results to return (1–100). Default: 20.
- cursor (string, optional): Opaque pagination cursor from a previous response.
- refresh (boolean, optional): Force a fresh fetch bypassing the cache.
- advertiser_id (string, optional): Fetch a single advertiser by ID.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok advertisers list

Response: markdown

## tiktok_ads_get_advertiser

Get details for a single TikTok advertiser by ID.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok advertiser get

Response: markdown

## tiktok_ads_list_audiences

List custom and lookalike audiences for a TikTok advertiser.

Annotations: read-only, idempotent, open-world

Parameters:
- limit (integer, optional): Maximum number of results to return (1–100). Default: 20.
- cursor (string, optional): Opaque pagination cursor from a previous response.
- refresh (boolean, optional): Force a fresh fetch bypassing the cache.
- advertiser_id (string, required): TikTok advertiser ID.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok audiences list

Response: markdown

## tiktok_ads_check_auth_status

Check whether the user's TikTok Ads account is authenticated. Returns auth method and email. Use ONLY when the user asks about auth status or connectivity — to get advertiser accounts, use tiktok_ads_list_advertisers instead.

Annotations: read-only, idempotent, open-world

Parameters:
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok auth check

Response: markdown

## tiktok_ads_get_login_url

Get the URL to connect a TikTok Ads account via OAuth.

Annotations: read-only, idempotent

Parameters:
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok login-url get

Response: markdown

## tiktok_ads_get_user_info

Get detailed profile information about the authenticated TikTok Ads user (email, display name, role). Use this for user profile details — for checking auth status or listing advertiser IDs, use tiktok_ads_check_auth_status instead.

Annotations: read-only, idempotent, open-world

Parameters:
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok user-info get

Response: markdown

## tiktok_ads_list_campaigns

List TikTok ad campaigns for an advertiser. Shows name, status, objective, and budget.

Annotations: read-only, idempotent, open-world

Parameters:
- limit (integer, optional): Maximum number of results to return (1–100). Default: 20.
- cursor (string, optional): Opaque pagination cursor from a previous response.
- refresh (boolean, optional): Force a fresh fetch bypassing the cache.
- advertiser_id (string, required): TikTok advertiser ID.
- campaign_id (string, optional): Fetch a single campaign by ID.
- campaign_ids (array, optional): Fetch specific campaigns by IDs.
- status (array, optional): Filter by primary status.
- search (string, optional): Search campaigns by name (case-insensitive).
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok campaigns list

Response: markdown

## tiktok_ads_get_campaign

Get details for a single TikTok campaign by ID.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- campaign_id (string, required): Campaign ID.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok campaign get

Response: markdown

## tiktok_ads_developer_feedback

Submit feedback about missing tools, improvements, bugs, or workflow gaps in the TikTok Ads MCP toolset. Not for user-facing issues like auth or API errors.

Annotations: idempotent, open-world

Parameters:
- feedback_type (string, required): Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow). Values: new_tool, improvement, bug, workflow_gap
- title (string, required): Concise title summarizing the feedback
- description (string, required): What is needed and why
- current_workaround (string, optional): Current workaround, if any
- priority (string, optional): Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue). Values: low, medium, high
- interface (string, optional): Interface the feedback originated from: MCP (default) or CLI. Values: MCP, CLI
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok developer-feedback send

Response: markdown

## tiktok_ads_ping

Health check for the TikTok Ads MCP server.

Annotations: read-only, idempotent

Parameters:
- message (string, optional): Optional message to echo back
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok ping

Response: markdown

## tiktok_ads_get_performance_report

Get a performance report for a TikTok advertiser over a date range, with optional breakdowns and entity filters.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- level (string, required): Reporting level — mapped to data_level internally.. Values: campaign, adgroup, ad
- date_preset (string, optional): Shortcut date range. Overridden by explicit start_date/end_date.. Values: last_7d, last_14d, last_30d
- start_date (string, optional): Start date in YYYY-MM-DD format.
- end_date (string, optional): End date in YYYY-MM-DD format.
- campaign_id (string, optional): Filter to a specific campaign.
- adgroup_id (string, optional): Filter to a specific ad group.
- page (integer, optional): Page number (1-indexed). Default: 1.
- page_size (integer, optional): Results per page. Default: 20.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok performance-report get

Response: json

## tiktok_ads_get_insights

Get aggregated insights and analytics for TikTok ad entities with custom dimensions (age, gender, country, placement). Use this for audience demographic breakdowns and flexible dimension-based analysis — for video/creative metrics, use tiktok_ads_get_creative_report instead.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- report_type (string, optional): Type of report. AUDIENCE for demographic breakdowns (age, gender, country). Default: BASIC.. Values: BASIC, AUDIENCE
- data_level (string, required): Granularity level for the report.. Values: AUCTION_ADVERTISER, AUCTION_CAMPAIGN, AUCTION_ADGROUP, AUCTION_AD
- dimensions (array, required): Grouping dimensions, e.g. ["campaign_id", "stat_time_day"].
- metrics (array, optional): Metrics to retrieve. Defaults to standard funnel metrics if omitted.
- start_date (string, optional): Start date in YYYY-MM-DD format.
- end_date (string, optional): End date in YYYY-MM-DD format.
- lifetime (boolean, optional): If true, return lifetime metrics instead of date-ranged.
- page (integer, optional): Page number (1-indexed). Default: 1.
- page_size (integer, optional): Results per page. Default: 20.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok insights get

Response: json

## tiktok_ads_get_creative_report

Get video creative performance metrics for TikTok ads — video views, watch time, completion rates (p25/p50/p75/p100), engagement, and per-creative breakdowns. Supports filtering by campaign_id or adgroup_id to narrow results. Use this tool for video-specific metrics and creative-level analysis.

Annotations: read-only, idempotent, open-world

Parameters:
- advertiser_id (string, required): TikTok advertiser ID.
- campaign_id (string, optional): Filter to a specific campaign.
- adgroup_id (string, optional): Filter to a specific ad group.
- start_date (string, optional): Start date in YYYY-MM-DD format.
- end_date (string, optional): End date in YYYY-MM-DD format.
- page (integer, optional): Page number (1-indexed). Default: 1.
- page_size (integer, optional): Results per page. Default: 20.
- reason (string, required): Why this tool call is needed

CLI: hopkin tiktok creative-report get

Response: markdown

---