> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PPC Depth Tools

> The full-depth ad-platform toolset the AI agent works with: Google Ads targeting, conversion actions, assets and Performance Max, the Microsoft Advertising family, Meta and LinkedIn depth, disapproval reads on every platform, and the budget guardrail

Beyond the campaign dashboard, the AI agent (and the MCP tool surface) can operate your ad accounts at full depth. Every tool below rides an existing ad connection — get the connection id from `ppc_connection_list` first. If a platform isn't linked yet, start at [Connecting Ad Accounts](/advertising/connecting-accounts).

## Two conventions to know first

**Two-step confirm.** Any tool that spends money, changes live delivery, or does something irreversible follows the same pattern: the first call executes nothing — it returns a preview with `requires_confirm: true`. Repeat the identical call with `confirm: true` to execute. You'll meet it on customer-list uploads (`ppc_customer_match_upload`, `ppc_offline_conversion_upload`), live-audience edits (`ppc_meta_ad_set_audiences_update`, LinkedIn segment updates and ABM uploads), archiving (`ppc_meta_archive`, LinkedIn campaign and creative archive), and the Tag Manager publish step on the [SEO side](/marketing/seo-delivery-tools).

**Nothing new serves by itself.** Creations land inert: Google Performance Max asset groups and Meta ad sets/ads are created **paused**, Microsoft Advertising campaign shells are created **paused**, and LinkedIn campaigns and creatives are created as **drafts** that no tool can activate — a person launches those in Campaign Manager. Enabling is always a separate, explicit step.

## Google Ads: the extended lane

Seven tools extend the core `ppc_*` set. Each takes a `connection_id`, an `operation`, and operation-specific `params`.

| Tool                            | What it covers                                                                                                                                                                                                                                                                                                       |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ppc_google_targeting`          | Geo, proximity, and language targeting: search place names to geo target ids, list/add/remove campaign geo targets (including exclusions and bid modifiers), radius targeting for service-area businesses, language targets, and location settings (`PRESENCE` stops local budgets leaking to out-of-area searchers) |
| `ppc_google_conversion_actions` | Create, inspect, and update conversion actions — categories, webpage vs upload vs call types, count type, lookback windows, whether the action feeds Smart Bidding — and fetch the tag snippets to install. Removing a conversion action is deliberately refused here; retire with status `HIDDEN` instead           |
| `ppc_google_asset_upload`       | Image assets (from an https URL, 5 MB cap, with the ad slots each image legally fills), YouTube video assets, and a read-only asset list                                                                                                                                                                             |
| `ppc_google_user_lists`         | Rule-based website-visitor remarketing lists (URL rules, membership window, optional 30-day backfill) and the list read that surfaces the `user_list_id` that `ppc_customer_match_upload` requires                                                                                                                   |
| `ppc_google_shared_negatives`   | Shared negative keyword lists: create, add keywords (immediate effect on every attached campaign), attach, detach, and list with member counts                                                                                                                                                                       |
| `ppc_google_pmax`               | Performance Max asset groups: one atomic create that refuses to build a group missing anything Google requires, per-slot asset repair, search-theme and audience signals, a servability diagnostic per group, and price assets                                                                                       |
| `ppc_google_pmax_performance`   | Read-only PMax performance: per-asset-group metrics plus Google's per-channel split of where delivery actually went (Search, Display, YouTube, Gmail, Discover, Maps, and more)                                                                                                                                      |

<Note>
  A Performance Max campaign created on its own can never serve — it needs at least one asset group. Build the group with `ppc_google_pmax`, upload images first through `ppc_google_asset_upload` (the response names which slot each image fits), and enable the group and the campaign as two separate approvals.
</Note>

## Microsoft Advertising (the `ppc_bing_*` family)

The Microsoft lane mirrors the Google depth: campaign build-out, the full targeting-criterion surface, audiences, conversion tracking, ad extensions, shared negatives, and three account-wide reports. Writes that need entity ownership checks require a prior `ppc_sync` (and `ppc_bing_pull_ad_groups` / `ppc_bing_pull_ads` on large accounts).

**Build-out**: `ppc_bing_push_campaign` creates a paused Search campaign shell; ad groups, keywords, ads, budgets, bids, and status flips ride the cross-platform `ppc_platform_*` lane (`ppc_platform_ad_group_create`, `ppc_platform_keyword_add`, `ppc_platform_responsive_search_ad_create`, `ppc_platform_budget_update`, `ppc_platform_pause_resource` / `ppc_platform_enable_resource`, and more).

**Targeting criteria**: `ppc_bing_location_search` resolves places to location ids for `ppc_bing_location_criterion_add`; `ppc_bing_radius_criterion_add` covers "20 miles around the shop"; `ppc_bing_location_intent_set` fixes Microsoft's leaky default (people searching *about* an area also see the ads); `ppc_bing_ad_schedule_add` dayparts (adding any schedule stops serving in unlisted hours); `ppc_bing_device_criterion_set` and `ppc_bing_demographic_criterion_add` adjust bids by device, age, and gender; `ppc_bing_criterions_list` reads everything and feeds `ppc_bing_criterion_delete`.

**Audiences**: `ppc_bing_audience_list` reads what exists (audience creation and uploads are deliberately not exposed), `ppc_bing_audience_criterion_add` / `ppc_bing_audience_criterion_remove` attach and detach, `ppc_bing_audience_associations_list` shows targeted vs excluded, and `ppc_bing_audience_target_setting_set` switches between bid-only and target-and-bid (the only mode where reach collapses to the audience).

**Conversion tracking**: `ppc_bing_uet_tag_list` / `ppc_bing_uet_tag_create` manage the UET measurement snippet (a tag not recording is the top reason a Microsoft account reports zero conversions), `ppc_bing_conversion_goal_list` / `ppc_bing_conversion_goal_create` manage goals, and `ppc_bing_conversion_tracking_status` gives a plain-language readiness verdict — run it before switching any campaign to a conversion-based bid strategy.

**Extensions and negatives**: `ppc_bing_sitelink_extension_create` and `ppc_bing_callout_extension_create` create extensions that show nothing until `ppc_bing_ad_extension_associate` attaches them (`ppc_bing_ad_extension_list` reads them); `ppc_bing_shared_negative_list_create` / `ppc_bing_shared_negative_list_items_add` / `ppc_bing_shared_negative_list_associate` / `ppc_bing_shared_negative_list_list` are the shared blocklist, with additions taking effect immediately on every associated campaign.

### The three Microsoft reports

| Report                             | What it answers                                                                                                                                                               |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ppc_bing_search_terms_report`     | Per-query spend and conversions plus a `wasted_spend` summary — queries with spend and zero conversions, the negatives-mining feed                                            |
| `ppc_bing_quality_score_report`    | Per-keyword quality score with component scores and a `low_quality` summary naming the weak components and the spend at risk                                                  |
| `ppc_bing_impression_share_report` | Impression share with lost-to-budget vs lost-to-rank per campaign, plus a `scaling_headroom` summary splitting raise-budget candidates from raise-bids/fix-quality candidates |

All three take `connection_id` with optional `days` (default 30) and `limit`; summaries are always computed over the full report even when returned rows are capped.

## Meta depth

Reads: `ppc_meta_insights_breakdown` (Meta's most flexible report — combine up to three breakdowns like age, placement, or publisher platform at account, campaign, ad set, or ad level), `ppc_meta_creative_list`, `ppc_meta_pages_pixels`, `ppc_meta_targeting` (search and browse targeting options, plus delivery estimates for a targeting spec), `ppc_meta_leadgen` (pull instant-form leads into the CRM), `ppc_meta_audiences_list` (custom and lookalike audiences, the account-wide audience map, and one ad set's include/exclude lists), and `ppc_meta_advantage_status`.

Writes: `ppc_meta_media_upload` and `ppc_meta_adcreative_create` (link, video, and carousel formats — a creative alone spends nothing), `ppc_meta_ad_set_create` and `ppc_meta_ad_create` (always created paused), `ppc_meta_advantage_create` (both halves of an Advantage+ buy, also paused), `ppc_meta_audience_create` (rule-based and lookalike audiences), `ppc_meta_custom_audience_upload` (pre-hashed identifiers into an existing custom audience, confirm-gated, with consent requirements), `ppc_meta_campaign_update` and `ppc_meta_ad_set_update` (targeting replaces the whole spec — read it first, edit, send it back whole), `ppc_meta_ad_set_audiences_update` (confirm-gated, re-enters learning), `ppc_meta_campaign_push` (push a local draft to Meta, paused), and `ppc_meta_archive` (irreversible, confirm-gated — pause instead to stop delivery temporarily).

<Warning>
  Meta write paths are newer than the reads and not yet validated against every live account shape. Status flips and budget changes deliberately stay on the audited `ppc_platform_*` lane rather than the update tools.
</Warning>

## LinkedIn depth

`ppc_linkedin_demographics_report` is LinkedIn's signature read: performance pivoted by job title, industry, seniority, function, company size, company, or geo — the "which job titles converted?" diagnostic. Around it: `ppc_linkedin_campaign_groups_list` / `ppc_linkedin_campaign_group_create` / `ppc_linkedin_campaign_group_update` (group budgets live only here), `ppc_linkedin_campaign_update`, `ppc_linkedin_campaign_push` (drafts only — LinkedIn hard-requires a budget and at least one location facet at create time), `ppc_linkedin_creatives` (list, detail, pause/enable with confirm on enable, archive), `ppc_linkedin_creative_create` (single-image Sponsored Content end to end, as a dark post), `ppc_linkedin_boost_post`, `ppc_linkedin_media_image_upload`, `ppc_linkedin_targeting` (facets, entity search, audience counts), `ppc_linkedin_leadgen`, `ppc_linkedin_conversions` (rules plus Conversions-API events with pre-hashed emails), `ppc_linkedin_audience_segments`, `ppc_linkedin_matched_audience_upload` (pre-hashed member lists), and `ppc_linkedin_abm_segment` (company segments — business identifiers, never person-level data).

## Disapproval reads on every platform

A disapproved ad spends nothing and silently starves its campaign, so these are the first reads to run when traffic drops:

| Platform   | Tool                                 |
| ---------- | ------------------------------------ |
| Google Ads | `ppc_disapprovals_list`              |
| Meta       | `ppc_meta_disapprovals_list`         |
| LinkedIn   | `ppc_linkedin_creative_disapprovals` |
| TikTok     | `ppc_tiktok_disapprovals`            |

All four return the same shape — a `disapproved_count` plus items with policy reasons where the platform provides them (LinkedIn and TikTok sometimes return status-only rows, flagged with `reasons_available: false`, with the detail living in the native ads manager). The daily guardrail sweep also watches for new disapprovals and can trigger the [Ad Disapproval Triage playbook](/marketing/standing-playbooks#ad-disapproval-triage-event).

## The budget guardrail

Each ad connection can carry a monthly budget target that a daily sweep enforces. Configure it through `ppc_connection_update` on the connection's `settings` object:

| Settings key                           | Effect                                                                                                                                  |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `settings.monthly_budget_target_cents` | The monthly spend target, in integer cents — setting it arms budget monitoring                                                          |
| `settings.guardrail.alert_at_pct`      | Files an alert to the [agent inbox](/marketing/client-reporting#the-agent-inbox) when spend crosses this percent of target (default 85) |
| `settings.guardrail.pause_at_pct`      | Opt-in hard line: automatically pauses the connection's live campaigns at this percent of target                                        |

<Warning>
  Updating `settings` replaces the whole settings object. Read the connection first with `ppc_connection_get` and merge your change in, or unrelated keys are lost.
</Warning>

## Related pages

* [SEO Delivery Tools](/marketing/seo-delivery-tools) — the rank tracker, GSC, and the Tag Manager publish flow that closes the conversion-tracking loop
* [Client Reporting & Approvals](/marketing/client-reporting) — where guardrail alerts land and how staged actions get approved
* [Standing Playbooks](/marketing/standing-playbooks) — the scheduled loops that run these tools every week
* [AI Advertising Strategist](/advertising/ai-strategist) — the docked chat surface over the same campaigns