# Google Ads OAuth Authentication in HireOtto
Source: https://docs.hireotto.com/authentication-1
Learn how HireOtto connects to Google Ads with OAuth, handles MCC access, supports multiple Google logins, and resolves account permissions.
***
## First-time setup
Ask your AI client:
```text theme={null}
Connect my Google Ads account to HireOtto.
```
HireOtto will return an authorization URL.
* Open it, sign in with the Google account that has access to your Google Ads, and complete the consent screen.
* After consent, you'll see a list of all accessible accounts — you can select all of them or pick specific ones, then **SAVE**.
* This step is important: if you skip saving, HireOtto won't have any accounts to work with even though the OAuth itself completed successfully.
* Once saved, come back to your client — you're connected.
If you have not added HireOtto to your AI client yet, start with [Connect Google Ads MCP](/quickstart). If you are setting up Claude, ChatGPT, or Make specifically, use [Connect HireOtto to Claude, ChatGPT, and Make](/setup/connect-ai-tool).
***
## How HireOtto resolves accounts
When you connect a Google login, HireOtto looks one level down from each account it can see:
* Direct Google Ads accounts are included as-is
* If any of those accounts is a Manager account (MCC), HireOtto also includes all the child accounts directly under it
So a single connected login can give you access to your own accounts plus all client accounts under a Manager — without any extra setup.
**Where this stops:** if your MCC contains another MCC (a nested Manager hierarchy), HireOtto won't automatically traverse further. To access accounts at that deeper level, you need to connect a separate Google login that has direct access to the inner MCC. See [Connecting multiple Google logins](#connecting-multiple-google-logins) below.
***
## Connecting multiple Google logins
There are two common reasons to connect more than one Google login:
1. **Deep MCC hierarchies** — you have an MCC inside an MCC, and the outer login can't reach the inner accounts directly
2. **Access spread across multiple Gmails** — you or your team have client account access granted to different Google logins, and you want all of them available through one HireOtto connector
In both cases, the setup is the same: connect each Google login as a separate profile with a nickname.
```text theme={null}
Connect another Google account. Call it "client_mcc".
```
HireOtto will generate a second authorization URL. Complete the OAuth flow with that Google login, select the accounts you want to save, and you're done. Repeat for as many logins as you need.
**Example: three-level MCC hierarchy**
Say you have this structure:
* Level 0: Your agency MCC — accessible via your primary Gmail
* Level 1: A client's MCC — accessible via a separate Gmail
* Level 2: The client's individual accounts under their MCC
Your primary Gmail gets you to Level 0 and everything directly under it. But to reach Level 2, you need to connect the Gmail that has direct access to the Level 1 MCC:
```text theme={null}
Connect another Google account. Call it "client_level1_mcc".
```
Sign in with that Gmail during OAuth, save the accounts — HireOtto will now see the Level 2 accounts under that MCC.
One important note: connecting the same Gmail twice under different profile names won't help — you'll get the same account access either way. The key is using a different Google login that actually has direct access to the deeper MCC.
**Profile name tips**
* Keep it short and memorable: `agency_mcc`, `client_ops`, `jane_gmail`
* Avoid colons (`:`) — they're used internally
* Multiple profiles require the Agency plan
***
## Refreshing accounts after adding new ones
If you've been granted access to a new Google Ads account after your initial setup, HireOtto won't see it automatically. Tell your client:
```text theme={null}
Refresh my Google Ads accounts.
```
To refresh accounts for a specific connected login:
```text theme={null}
Refresh accounts for myemail@gmail.com.
```
***
## When auth breaks
Common signs something's off:
* You see an error like `Google Ads isn't connected`
* `list_accessible_accounts` returns an empty list
* Requests fail with a permissions or authentication error
The most common cause: completing OAuth but not saving any accounts during the flow. Re-run auth and make sure you select and save accounts before finishing:
```text theme={null}
Re-authenticate my Google Ads account.
```
If a specific connected login is failing:
```text theme={null}
Re-authenticate myemail@gmail.com.
```
Go to [Troubleshooting](/troubleshooting) for common fixes around missing accounts, OAuth errors, connector issues, and Google Ads permissions.
***
## Google Search Console authentication
Google Search Console uses a separate Google permission flow from Google Ads.
Even if you have already connected Google Ads, you still need to connect Search Console before asking for organic search reports.
Ask your AI client:
```text theme={null}
Connect my Google Search Console account.
```
HireOtto will return an authorization URL.
* Open it and sign in with the Google account that has access to your Search Console properties.
* Complete the Google consent screen.
* When the auth page says Search Console is connected, close the window and return to your AI client.
Then verify access:
```text theme={null}
Show me the Search Console sites I have access to.
```
Unlike Google Ads, there is no account selection step after Search Console authentication. HireOtto saves the accessible Search Console properties automatically.
### Connecting multiple Search Console logins
If Search Console access is spread across multiple Google accounts, you can connect another Google login by asking to connect another Search Console profile.
Example:
```text theme={null}
Connect another Google Search Console account.
```
Use this when a different Gmail has access to different Search Console properties.
***
## Frequently asked questions
**Does HireOtto store my Google credentials?**
No. HireOtto uses OAuth tokens — not your Google password. You can revoke access at any time from your [Google account security settings](https://myaccount.google.com/permissions).
**Can I connect a Google Ads Manager account (MCC)?**
Yes. Connect the Google login that has access to the MCC. HireOtto will include the MCC itself plus all accounts directly under it. For accounts nested under a second-level MCC, connect a separate Google login that has direct access to that inner MCC.
**I completed OAuth but my accounts still aren't showing up.**
You likely didn't select and save any accounts during the OAuth flow. Re-authenticate, and when you reach the account selection screen, make sure to select the accounts you want and confirm the save before returning to your client.
# HireOtto product changelog
Source: https://docs.hireotto.com/changelog
Follow the latest HireOtto updates for advertising, measurement, organic search, audits, reporting, exports, and MCP reliability.
# 20-08-2026
## Google Analytics 4 reporting beta
Added a read-only Google Analytics 4 MCP server for bringing acquisition and on-site outcomes into the same AI workflow as Google Ads, Tag Manager, and Search Console. The beta supports account and property discovery, property configuration, reporting metadata, dimension-and-metric compatibility checks, standard reports, comparisons, cohorts, and realtime reports.
Standard reports return a concise inline result plus CSV by default. Realtime reports return an inline summary by default and cover the most recent 30 minutes, or 60 minutes for eligible Google Analytics 360 properties. The server cannot create or change GA4 properties, events, audiences, or settings. GA4 is included in the core product plans but remains beta.
## Weekly Google Ads optimization audit
Added a read-only weekly audit for mature optimization decisions. It compares enabled-campaign performance with the previous equal-length period, reviews Search visibility, and finds search-term, keyword, and responsive-search-ad candidates that deserve practitioner review.
The default performance window is the last 7 days. Search terms use a 30-day lookback and exclude the most recent 3 days for conversion lag. The audit returns severity-ranked findings and CSV exports; export links expire after 30 minutes by default. It never adds negatives, changes bids, or edits ads. Audit access is limited to the Agency plan.
## Google Ads account health audit
Added a read-only account health audit for monthly or quarterly structural reviews. It checks tracking and campaign settings, current versus comparison-period performance, keyword and match-type distributions, Quality Score components, negative-keyword coverage, geographic and device performance, and Search impression share lost to budget or rank.
The default window is the last 90 days compared with the preceding 90 days. Responsive-search-ad structure review and checklist output are optional and off by default. The audit returns prioritized findings, coverage notes, and CSV exports without changing the account. Audit access is limited to the Agency plan.
## Expanded daily operations audit
Reworked the daily audit around delivery and pacing exceptions. It now compares campaign delivery with a preceding baseline, evaluates shared-budget groups together, and flags stopped delivery, spend spikes or drops, and over- or underspending against current daily budgets.
The default audit period is yesterday with a 14-day baseline. It reviews enabled campaigns by default, returns up to 25 findings inline, and provides fuller CSV exports with 30-minute links. Search-term and creative optimization remain in the weekly audit. The daily audit is read-only and available on the Agency plan.
## Tag Manager inventory and website tracking scans
Expanded the read-only Tag Manager server with a joined container inventory that connects tags to firing triggers, trigger conditions, and blocking triggers. Inventory can use the live workspace or a published version and can return an inline summary, CSV export, or both.
Added a public website tracking scan that discovers likely high-value pages from a sitemap or homepage links and checks the available server-rendered HTML for common tracking signals. It scans up to 6 pages by default and 10 at most, with a 10-second timeout per page. It cannot prove that a tag fired and may miss tags loaded only after JavaScript, consent, login, or interaction. Tag Manager remains read-only.
## Search Console is now available
Moved Google Search Console out of beta. The read-only server can list properties and sitemaps, inspect URL indexing, and report organic performance by query, page, country, device, date, hour, and supported search-appearance dimensions. It can also include fresh or hourly data when requested and export larger result sets to CSV.
Search Console uses a separate Google permission from Google Ads. Recent data may be incomplete, and Google may return top rows rather than every possible row. Use finalized data and end at yesterday or earlier when a stable comparison matters.
## Google Ads reliability and date handling
Improved recent change-history date handling and validation for future campaign start dates. Tool responses now carry clearer server, operation, and requested-resource context, making it easier to confirm that a result belongs to the intended account and workflow when several servers or chats are active.
Google Ads remains the only current HireOtto server that can make platform changes. Actions run only when the connected client requests them. Review account IDs, budgets, dates, targeting, and bulk changes before approval, then verify significant changes in Google Ads.
## Try the new workflows
* Run the weekly optimization audit for the last 7 days, compare it with the preceding 7 days, and show every high- or medium-severity finding before suggesting any changes.
* Run the account health audit for the last 90 days with responsive-search-ad review enabled. Separate configuration issues from performance interpretation and list every CSV export.
* For this GA4 property, check which dimensions and metrics are compatible, then compare paid-search sessions and conversions with the previous 28 days.
* Inspect this Tag Manager container's live workspace, export the tag wiring, and scan the public site for tracking signals that need manual verification.
* In Search Console, find high-impression organic queries that are not covered by the current Google Ads keywords, then inspect the strongest landing pages for index status.
## Access, limits, and failure cases
* Agency audits are read-only. Their recommendations are review candidates, not automatic account changes.
* If one audit section fails or reaches a row limit, treat the result as partial. Use the coverage notes and CSV exports before calling the audit complete.
* GA4 beta requests can fail when a metric and dimension are incompatible. Check reporting metadata and compatibility before running a complex report.
* Tag Manager and Search Console require separate Google permissions. A missing container, property, or site usually means the connected Google login does not have access.
* Temporary CSV links expire. Download an export while the link is active or rerun the report to generate a new one.
* API quotas, account permissions, product restrictions, and incomplete recent data can still limit a valid request. Read the returned error before retrying.
***
* **\[19-07-2026] Negative Keyword Lists**: Added support for removing individual keywords from shared negative keyword lists. Keywords can be selected using their exact resource names or identified by keyword text and match type.
* **\[14-07-2026] Conversion Actions and GA4 Imports**: Added support for reviewing conversion tracking setup, creating native Google Ads conversion actions, importing eligible GA4 key events, and updating conversion-window settings.
* **\[11-07-2026] Google Tag Manager MCP**: Added read-only support for listing GTM accounts, containers, workspaces, tags, triggers, variables, built-in variables, and folders, plus tag-to-trigger wiring inspection and CSV export.
* **\[26-06-2026] Google Search Console MCP support**: Added beta support for organic query reports, page performance, country/device breakdowns, CSV exports, sitemaps, and URL indexing checks.
* **\[05-06-2026] Demand Gen Campaigns**: Added support for non-product-feed Demand Gen campaigns.
* Create campaign shells with goals (Conversions, Clicks, Conversion Value, YouTube Engagements) and optional bid targets.
* Add ad groups with channel controls — select individual channels (YouTube in-stream, in-feed, Shorts, Discover, Gmail, Display, Maps) or use a preset `ALL_CHANNELS`, `ALL_OWNED_AND_OPERATED_CHANNELS`).
* Create reusable assets (image, video, text, CTA) and ads (single image, multi-asset, carousel, video/video responsive).
* Inspect Demand Gen structure with three new listing actions: campaign settings, ad group channel controls, and ad creatives. Update campaigns and ad groups, and replace ad creative safely via the update tool.
* **\[18-05-2026] Campaign Budgets**: Added tools to create standalone/shared budgets, inspect budget usage, move campaigns between budgets, create-and-attach dedicated budgets, and safely remove unused budgets.
* **\[17-05-2026] Bidding Strategies**: Added portfolio bidding strategy management including create/list/attach/remove, moving campaigns back to standard campaign-level bidding, shared-budget alignment support, and atomic workflows for aligned shared-budget + portfolio setups.
* **\[16-05-2026] Conversion Actions**: Added a basic conversion action update tool for existing conversion actions, including default value, always-use-default-value, counting type, primary-for-goal status, status, category, and attribution model updates.
* **\[06-05-2026] Extension Assets**: Added support for managing Google Ads extensions including sitelinks, callouts, structured snippets, call assets, and price assets. You can list existing assets, create new reusable assets, link them at the account/campaign/ad group level, reuse the same asset across supported levels, unlink asset associations, and pull extension asset performance reports.
* **\[18-04-2026] Performance Max**: Added support for creating standard PMax campaigns, adding asset groups, managing asset group assets, managing audience signals and search themes, and listing current asset group signals and available audiences.
* **\[15-04-2026] Change History**: Added Google Ads change history support with change status and detailed change events, including CSV export for larger timelines.
* **\[14-04-2026] Custom GAQL**: Added `run_gaql` for Agency users for flexible read-only custom reporting.
* **\[14-04-2026] Performance Max Reporting**: Added reports for campaign performance, placements, feed types, asset groups, asset strength, asset performance, top asset combinations, and PMax search terms.
* **\[12-04-2026] Reporting**: Added demographic performance reports for age and gender.
* **\[11-04-2026] App Campaigns**: Added App campaign creation support (campaigns, ad groups, ads) plus App-compatible campaign/ad group updates.
* **\[24-03-2026] Daily Ops Audit**: A simple tool that flags under/over pacing campaigns and wasteful search terms (conversions \< 1, sorted by cost).
* **\[12-03-2026] Reporting**: Daily segment support added to the reporting tool for day-by-day analysis.
* **\[22-02-2026] CSV support**: Extended CSV support: export modes (summary / summary+csv / csv\_only) to other relevant tools.
* **\[30-12-2025] Reporting**: Added CSV export modes (summary / summary+csv / csv\_only) to prevent context-window overload on large reports.
* **\[29-12-2025] Keyword Planner:** CSV export support for `keyword_planner` - keep context lengths short and allow LLMs to analyze data programmatically.
* **\[25-12-2025] Keyword Planner:** Added `keyword_planner` tool for keyword ideas + historical metrics (with location\_mode, sorting, filtering).
* **\[21-11-2025] Server Updates** to work more smoothly with Claude web
* **\[03-10-2025] Google Ads API Updates**: Updated tools to work with the latest ads API.
* **\[09-08-2025] Preview** - Remote MCP, Google Ads auth, core reporting, Search build/edit tools, helpful defaults.
**Roadmap (as of 06-06-2026):**
* More extension asset types and deeper field coverage based on user feedback
* One shot account audit tools
* Support for campaign types beyond Search (Display, YouTube) — phased
* *Shaped by your feedback - tell me what you need most.*
# Connect Google Ads to Claude - Video Walkthrough
Source: https://docs.hireotto.com/connect-google-ads-to-claude
Authorize your Google Ads account through HireOtto, choose the accounts Claude can access, and test the connection with a simple Google Ads query.
This walkthrough covers the Google Ads authorization step after HireOtto has been added to Claude: opening the auth link, granting permissions, selecting accounts, and testing that Claude can access your Google Ads data.
## What this walkthrough covers
* Starting Google Ads authentication from Claude
* Completing the Google OAuth consent flow
* Selecting the Google Ads accounts HireOtto can access
* Accepting the required terms and privacy policy
* Confirming the connection in Claude with account and campaign checks
After this step, you can start using Claude to inspect Google Ads accounts, campaigns, budgets, and performance through HireOtto.
# Add the HireOtto MCP Server to Claude Web – Video Walkthrough
Source: https://docs.hireotto.com/connect-hireotto-to-claude-web
A short walkthrough for adding the HireOtto MCP server to Claude Web and checking that the connection is active.
This walkthrough covers the Claude Web setup step: adding the server URL, approving the connection, and confirming that HireOtto is available inside Claude.
### What this video covers
* [**0:00**](https://youtu.be/bCsF42LPxAs) – Opening the connectors page on Claude Web
* [**0:07**](https://www.youtube.com/watch?v=bCsF42LPxAs\&t=7s) – Adding the HireOtto server URL
* [**0:38**](https://www.youtube.com/watch?v=bCsF42LPxAs\&t=38s) – Completing the initial connection handshake
* [**0:46**](https://www.youtube.com/watch?v=bCsF42LPxAs\&t=46s) – Confirming available tools (read-only and write/delete)
### Next step
This video covers the server connection only. To start running Google Ads workflows, you'll need to authenticate your Google Ads account.
# HireOtto credits, billing, and plans
Source: https://docs.hireotto.com/credits-and-billing
Understand Free, Starter, Pro, and Agency pricing, credits, server access, audits, seats, upgrades, cancellations, and refunds.
***
A single HireOtto plan covers the currently supported product stack. Free, Starter, and Pro use credits. Agency includes unlimited credits and unlocks audits, multiple connected Google profiles, team billing, and two seats.
* Free: \$0. Use up to 200 credits or 14 days, whichever comes first.
* Starter: \$25 per month with 2,000 credits.
* Pro: \$49 per month with 5,000 credits.
* Agency: \$99 per month with unlimited credits and two seats. Additional seats are \$25 per month each.
All prices are in USD. Taxes may be added by Paddle based on your location. Paid subscriptions renew automatically until you cancel.
***
# Choose a plan
## Free
Use the free trial to connect your accounts and test supported core workflows before paying. The trial ends when you use 200 credits or reach 14 days, whichever happens first.
## Starter
Choose Starter for lighter individual or in-house usage. It includes 2,000 credits per month and access to supported core tools across Google Ads, Tag Manager, Search Console, and the Google Analytics beta.
## Pro
Choose Pro when you need the same core access with more room for reporting, planning, exports, and account work. It includes 5,000 credits per month.
## Agency
Choose Agency when you need formal audits, multiple connected Google profiles, team billing, or more than one user. Agency includes unlimited credits, two seats, and priority async support. Additional seats cost \$25 per month each.
Monthly and yearly billing are available on the pricing page. Yearly billing is priced at the equivalent of two months free.
***
# What your plan covers
Core access is available on the free trial, Starter, Pro, and Agency. The scope differs by server:
* Google Ads: read performance data, export reports, and use supported account actions. HireOtto acts only when your connected AI client calls a tool; review important or bulk changes before applying them.
* Google Tag Manager: inspect accounts, containers, workspaces, tags, triggers, variables, folders, and tag wiring. The current server is read-only and does not publish container changes.
* Google Search Console: analyze query and page performance, inspect properties, sitemaps, and URL indexing, and export supported reports. Connect a Google account that can access the property you need.
* Google Analytics: run property discovery, standard reports, date comparisons, and basic realtime reporting. Google Analytics access is currently in beta and requires the relevant Google permission.
Audit workflows and multiple connected Google profiles require Agency. Starter and Pro do not include audits. LinkedIn Ads is not included in the current plans and remains on the roadmap.
***
# How credits work
Credits measure usage across HireOtto tools. Simple discovery and listing work uses fewer credits; deeper reports, planning, exports, and complex account actions use more.
* Free starts with 200 one-time trial credits.
* Starter includes 2,000 credits per monthly billing period.
* Pro includes 5,000 credits per monthly billing period.
* Agency has unlimited credits.
* Starter and Pro balances reset at the start of each billing period. Unused credits do not roll over.
When a limited plan reaches its credit allowance, credit-consuming actions stop until the next billing period or until you upgrade. Free utility actions, such as checking billing status, remain available so you can see the reason and next step.
## How to check your balance
Ask your AI client:
```text theme={null}
What's my HireOtto credit balance?
```
The response shows your current plan, billing or trial status, credits used and remaining, the current period dates, and the features available to your workspace.
***
# Upgrade or change your plan
### Start a paid subscription
If you are on Free or do not yet have a paid subscription, use checkout to start one.
* Open a plan link returned by a HireOtto server when a subscription is required, or go to the [HireOtto pricing page](https://hireotto.com/pricing) and choose monthly or yearly billing.
* Select Starter, Pro, or Agency. For Agency, choose the number of seats you need.
* Complete checkout.
Your account will be upgraded, usually within a few hours. Return to your AI client and check your HireOtto billing status before resuming work.
## Upgrade an existing paid subscription
Subscribing and upgrading are different. If you already have an active Starter or Pro subscription, do not use another checkout link; that can create a second subscription.
* Email [suyash@hireotto.com](mailto:suyash@hireotto.com) and include the email registered with HireOtto.
* State your current plan, the plan you want, and the number of Agency seats if relevant.
HireOtto will update your existing subscription and confirm once the new plan access is active.
## Other plan changes
For downgrades, changes between monthly and yearly billing, or Agency seat changes, email [suyash@hireotto.com](mailto:suyash@hireotto.com). HireOtto will confirm when the change will take effect and any billing adjustment before applying it.
If the new plan does not appear, refresh or reconnect your HireOtto server and check again. If it is still incorrect, contact HireOtto with the email used at checkout and the Paddle receipt or subscription details.
***
## Plan features explained
**Audit tools (Agency only)** Structured account hygiene checks — auto-tagging status, auto-apply review, disapproved ads, and negative keyword coverage. Designed for practitioners doing formal account reviews or onboarding a new client account.
**Multi-profile support (Agency only)** Connect and switch between multiple Google logins inside the same AI client session. Essential for agencies managing accounts across different Google accounts. See the [authentication guide](/authentication-1) for how multi-profile OAuth works.
**Async support** Email-based support from the HireOtto team. Pro users get standard async support; Agency users get priority response.
**Seats (Agency)** The Agency plan includes 2 seats — meaning two separate HireOtto accounts on the same billing. Additional seats are \$25/month each. Useful for agencies where multiple team members each connect their own AI client. Email [suyash@hireotto.com](mailto:suyash@hireotto.com) to add seats.
***
## Tips for getting more out of your credits
**Use** `summary `**mode for quick checks,** `csv_only `**for bulk exports.** Performance reports let you choose how results come back. `summary` is the default and works well for scanning a handful of campaigns. If you're pulling data across 50+ campaigns for a spreadsheet, use `csv_only` — same credit cost, cleaner output.
**Filter before you pull.** Most report actions accept a `campaign_id` or `adgroup_id` filter. If you only need one campaign's keyword data, pass the campaign ID — it limits what gets fetched and keeps responses manageable.
**Listing is cheap; reporting isn't.** `list_campaigns` costs 1 credit. `get_campaign_performance` costs 5. If you just need to see which campaigns exist (not their metrics), use the listing action.
***
# Billing, taxes, cancellation, and refunds
* Merchant of record: Paddle may handle payment processing, taxes, invoices, cancellations, and refunds.
* Currency and tax: prices are listed in USD. Paddle may add tax based on your location.
* Renewal: subscriptions renew automatically until cancelled.
* Cancellation: cancel before the next renewal to stop future charges. Use the management or support link in your Paddle receipt, or contact HireOtto for help.
* Refunds: Use the refund or support link in your Paddle receipt, or email [suyash@hireotto.com](mailto:suyash@hireotto.com).
***
# Common billing and access errors
## The free trial has ended
The trial stops when you reach 200 credits or 14 days. Choose a paid plan from the pricing page, then check billing status again.
## You have used all credits for the period
Wait for the next monthly reset or upgrade to a plan with a larger allowance. Agency removes the credit limit.
## This workflow requires Agency
Audits, multiple connected Google profiles, and team billing are Agency features. Upgrade to Agency, or use the available core tools individually on Starter or Pro.
## Billing is inactive or the billing period cannot be verified
Check that the subscription is active in Paddle, then refresh or reconnect HireOtto and retry the billing check. If the status remains wrong, contact HireOtto with the checkout email and receipt.
## The right plan is active, but a Google account or property is missing
Billing access and platform permissions are separate. Reconnect the relevant Google service and confirm that the signed-in Google account can access the ad account, Tag Manager container, Search Console property, or Analytics property you need.
***
# Related pages
Pricing: [https://hireotto.com/pricing](https://hireotto.com/pricing)
Refund policy: [https://hireotto.com/refund-policy](https://hireotto.com/refund-policy)
Connect a HireOtto server: [https://docs.hireotto.com/setup/connect-ai-tool](https://docs.hireotto.com/setup/connect-ai-tool)
# HireOtto FAQ
Source: https://docs.hireotto.com/faq
Answers about supported servers, setup, permissions, plans, privacy, limits, and troubleshooting.
HireOtto connects supported AI clients to Google Ads, Google Tag Manager, Google Search Console, Google Analytics 4, and LinkedIn Ads through remote MCP servers. Google Ads supports reporting and user-directed account changes. Tag Manager and Search Console are read-only. GA4 is a read-only beta. LinkedIn Ads beta supports selected read and draft-first write workflows where access is enabled. HireOtto does not make changes on its own.
## About HireOtto
HireOtto is a suite of remote MCP servers for marketers. It lets an AI client work with live Google Ads, Tag Manager, Search Console, GA4, and LinkedIn Ads data after you connect the relevant server and authorize an identity that already has access to the resource.
Google Ads, Google Tag Manager, and Google Search Console are available now. Google Analytics 4 and LinkedIn Ads are available in beta. LinkedIn Ads must be enabled for the HireOtto account before that server can be used. Reddit and Microsoft Ads remain on the roadmap.
HireOtto works with MCP-compatible clients including ChatGPT, Claude, Cursor, VS Code, and Make. Setup differs by client. Google and LinkedIn use separate authorization flows, and each platform continues to enforce its own account permissions.
No. HireOtto is hosted remotely. Add the server URL to your AI client, sign in to HireOtto, accept the terms, and authorize the relevant Google or LinkedIn product when prompted.
Yes. Each server is connected separately, so you can use only the products you need or combine several in one client. Each Google or LinkedIn product also has its own authorization step.
## Setup and permissions
No. Google or LinkedIn handles sign-in and consent. HireOtto receives OAuth tokens for the permissions you approve; it never receives your Google password.
Google Ads requests access that can support both reporting and the user-directed changes available in HireOtto. Tag Manager, Search Console, and GA4 use read-only access. LinkedIn Ads supports reporting and selected draft-first actions where access is enabled, subject to the connected ad-account role and LinkedIn Page permissions. A read-only server or role cannot create, edit, delete, or publish resources.
Google Ads, Tag Manager, Search Console, GA4, and LinkedIn Ads are separate services with separate permissions. Connecting one does not automatically grant access to the others.
Yes. Remove HireOtto from the third-party access section of the connected Google or LinkedIn account. You can reconnect later if needed. Revoking one product may require you to reauthorize that server before it can run again.
The connected Google or LinkedIn identity must already have access to that resource. Confirm you used the right identity, check the permission in the relevant platform, and reconnect the server if access changed after authorization. For Search Console, use the exact property returned by the site list; domain and URL-prefix properties are different resources. For LinkedIn Ads, confirm the same identity can open the ad account in Campaign Manager.
## Google Ads
It can report on campaigns and performance, run GAQL queries, export data, research keywords, inspect change history, and work with supported campaign settings, budgets, bidding, targeting, negatives, conversions, assets, ads, and account structure. It also supports workflows for Search, App, Performance Max, and Demand Gen campaigns. Exact actions depend on campaign type and your Google Ads permissions.
No. HireOtto acts only when you or your AI workflow requests an action. Review proposed changes, account IDs, budgets, dates, and targeting before approval, especially for bulk or high-impact operations.
Read-only access is generally enough for reporting. Creating or changing campaigns normally requires Standard or Admin access in Google Ads. Google can still reject an operation when the account, campaign type, policy state, or selected setting does not permit it.
Yes. Connect a Google login with access to the manager account, then select from the accounts HireOtto can discover for that login. If a client account is only available through a deeper manager hierarchy and does not appear, connect a Google login with more direct access to the relevant manager or account. Multiple connected Google logins are an Agency-plan feature.
No. Coverage varies by campaign type and by what the Google Ads API exposes. Search, App, Performance Max, and Demand Gen have supported creation or management workflows. HireOtto does not currently provide dedicated Smart, Display, or Video campaign creation. Existing campaigns may still be available for reporting when Google exposes the data.
Some changes can be corrected with a new operation, but not every action is directly reversible. Use Google Ads change history to confirm what changed. For destructive or financially significant actions, review the request before it runs and verify the result in Google Ads afterward.
Audits are guided review workflows that analyze supported account areas and return findings and recommendations. They are available on the Agency plan. An audit does not apply campaign changes automatically.
## Google Search Console
No. The Search Console server is available now and is read-only.
It can list accessible properties and sitemaps, inspect a URL's index status, and query organic search performance by dimensions such as query, page, country, device, date, hour, and search appearance. Performance results can be returned inline and, when requested, exported to CSV.
Not always. Google may return top rows rather than every possible row, and recent data can be incomplete. Finalized reporting is the default. For stable analysis, end the date range at yesterday or earlier unless you explicitly need fresher data.
## Google Tag Manager
Yes. It can inspect configuration but cannot create, edit, delete, or publish containers, workspaces, tags, triggers, variables, or versions.
It can list accessible accounts, containers, and workspaces; inspect tags, triggers, variables, folders, and versions; summarize an inventory; trace tag wiring; and export supported findings. It can also scan a public website for common tracking signals and compare those signals with the container configuration.
A website scan checks public, server-rendered HTML. The default is up to 6 pages and the maximum is 10 pages per run, with a 10-second timeout per page. It may miss tags injected only after browser interaction, consent, login, or client-side execution. Treat the scan as evidence for review, not proof that a tag fired correctly.
## Google Analytics 4
The GA4 server can list accessible accounts and properties, inspect property configuration and metadata, check report compatibility, run standard reports, and run realtime reports. Access is read-only, so it cannot create or modify GA4 properties, events, audiences, or settings.
Realtime reports cover the most recent 30 minutes by default. Google Analytics 360 properties can support a 60-minute realtime window.
The connected Google login must have permission to the property. Reconnect GA4 after permissions change, then list properties again before running a report.
## LinkedIn Ads
Where access is enabled, it can verify the connected identity, list accessible ad accounts and roles, inspect campaign groups, ad sets and creatives, run performance and professional-demographic reports, resolve valid targeting entities, estimate audience size, work with supported image assets, create supported campaign objects as drafts, and apply selected updates after approval.
Viewer access supports read-only work. Creating or changing ads requires a sufficient ad-account role. Direct Sponsored Content and some creative workflows can also require permission for the associated LinkedIn Page.
Draft-first creation keeps validation, account creation, targeting review, creative preview, tracking checks, and activation separate. Review the returned IDs and inspect the result in Campaign Manager before any explicit activation request.
Campaign Manager remains the final place for preview, billing warnings, Page permissions, and activation review. HireOtto does not currently create Lead Gen Forms, and the current image workflow should not be assumed to cover video or document-ad uploads. Creating an ad does not install or validate the LinkedIn Insight Tag, Google Tag Manager, or destination-page tracking.
## Plans, billing, and credits
The Free trial, Starter, Pro, and Agency plans include the core Google Ads, Tag Manager, Search Console, and GA4 tools. GA4 remains beta. Agency adds audits, multiple connected Google profiles, team billing, two included seats, and unlimited credits. LinkedIn Ads beta is available separately where access is enabled; core-server access alone does not imply LinkedIn Ads access.
The Free trial includes 200 credits or 14 days, whichever comes first. Starter includes 2,000 credits per month. Pro includes 5,000 credits per month. Agency includes unlimited credits under the fair-use terms shown on the pricing page.
Credit-metered tools are blocked until credits reset or you upgrade. Billing and account-status tools remain available so you can check the current plan and usage. A failed or blocked request should not be treated as a completed marketing action.
HireOtto executes exactly what the MCP tool call specifies. Before making bulk changes, your AI assistant should confirm the action with you. If an unintended change is made (e.g., a campaign is paused accidentally), you can ask the AI to reverse it immediately — for example: "Re-enable the 'Summer Sale' campaign."
Plans renew automatically through Paddle. Cancel before the next renewal to prevent a new charge. HireOtto offers a 14-day refund period for eligible purchases; see the billing guide and terms for the current details.
## Privacy and security
HireOtto stores the OAuth tokens and minimal identifiers needed to maintain your connections. Reporting and configuration data is processed to answer your request and is not intended to become a permanent copy of your Google account. Temporary exports expire.
No. HireOtto does not sell Google user data or use it for advertising or retargeting.
Email [suyash@hireotto.com](mailto:suyash@hireotto.com) from the address associated with your account. HireOtto states that deletion requests are completed within 30 days unless limited retention is required for legal or billing-dispute reasons.
## Limits and troubleshooting
Read the returned error first. Check the selected resource ID, date range, required parameters, connected Google login, product permission, plan entitlement, and remaining credits. If authorization expired, reconnect the relevant server. If Google rejects a write, correct the specific field or permission rather than repeating the same request unchanged.
Start with a read or preview, narrow the scope, and split large changes into reviewable batches. Confirm customer IDs, campaign IDs, budgets, dates, and targeting before a write. API quotas and product-specific limits can vary, so a smaller batch is easier to review and retry safely.
Email [suyash@hireotto.com](mailto:suyash@hireotto.com) with the server name, AI client, approximate time of the issue, and the non-sensitive portion of the error. Do not send OAuth tokens, passwords, or other secrets.
# HireOtto feature and entitlement matrix
Source: https://docs.hireotto.com/feature-entitlement-matrix
See which servers and capabilities are available on Free, Starter, Pro, and Agency – and whether each workflow can read or change platform data.
Every current HireOtto plan includes core access to Google Ads, Google Tag Manager, Google Search Console, and Google Analytics. Google Analytics is in beta. LinkedIn Ads is also available in beta where access is enabled. Google Ads and LinkedIn Ads support selected read and write workflows; Tag Manager, Search Console, and Analytics are read-only. Agency adds unlimited credits, audits, multiple connected Google profiles, team billing, and two seats.
# Plan entitlements
Use this matrix to choose the lowest plan that includes the access model you need.
| **Capability** | **Free** | **Starter** | **Pro** | **Agency** |
| :---------------- | :------------- | :------------ | :------------ | :----------------- |
| Credits | 200 or 14 days | 2,000 / month | 5,000 / month | Unlimited |
| Core servers | Included | Included | Included | Included |
| Google Ads audits | Not included | Not included | Not included | Included |
| Multiple profiles | Not included | Not included | Not included | Included |
| Team billing | Not included | Not included | Not included | Included |
| Seats and support | Individual | Individual | Individual | 2 seats + priority |
Core servers means Google Ads, Tag Manager, Search Console, and Google Analytics. LinkedIn Ads is a separately enabled beta server and is not implied by core-server access. Free access ends after 200 credits or 14 days, whichever comes first. Additional Agency seats cost \$25 per month each.
# Server capability and access
The access type is determined by the server, not by choosing a higher individual plan.
| **Server** | **Status** | **Read** | **Write** | **Key access note** |
| :--------------- | :--------- | :------- | :-------- | :------------------------------------ |
| Google Ads | Live | Yes | Yes | Audits/profiles: Agency |
| Tag Manager | Live | Yes | No | Profiles: Agency |
| Search Console | Live | Yes | No | Separate Google permission |
| Google Analytics | Beta | Yes | No | Beta; profiles: Agency |
| LinkedIn Ads | Beta | Yes | Yes | Access enabled; role/Page permissions |
# Server details
## Google Ads
Google Ads is live and supports both read and write workflows. You can report, investigate, export, plan, create, and update supported account entities from the same AI conversation.
* Core Google Ads tools are available on every plan, subject to credits on Free, Starter, and Pro.
* Daily, weekly, and account-health audits require Agency.
* Connecting more than one Google profile requires Agency.
* HireOtto makes changes only when the connected AI client calls a write action. Review important and bulk changes before applying them.
## Google Tag Manager
Tag Manager is live and read-only. It can inspect accounts, containers, workspaces, tags, triggers, variables, folders, container versions, and tag wiring, but it cannot create, edit, delete, or publish GTM changes.
Container inventory uses the live container by default. The default response includes a summary plus CSV, shows up to 50 tag-wiring rows inline, exports up to 5,000 rows, and keeps the signed export link available for 30 minutes.
The website tracking scan starts from a base URL, checks up to six pages by default, and caps discovery at 10 pages. It uses a 10-second request timeout by default and inspects static HTML; JavaScript-rendered tags may not be visible. Add specific URLs when discovery may miss an unlinked page.
## Google Search Console
Search Console is live and read-only. It can list properties and submitted sitemaps, inspect URL indexing, analyze search performance, and export supported results.
Performance reports default to query-level web search data, finalized data, a summary plus CSV, 50 inline rows, up to 25,000 exported rows per request, and a 30-minute export link. Search Console interprets report dates in Pacific Time; end stable reports at yesterday or earlier.
Search Console returns top rows within API limits rather than guaranteeing every possible row. Connect the Google account that has permission to the property you need.
## Google Analytics
Google Analytics is available in beta and is read-only. It supports account and property discovery, property configuration, metadata, compatibility checks, standard reports, comparisons, and basic realtime reporting.
Standard reports default to a 10,000-row fetch limit, summary plus CSV output, 200 inline rows, up to 50,000 exported rows, and a 30-minute export link.
Realtime reports cover the latest 30 minutes, or 60 minutes for Google Analytics 360. Realtime requests do not accept ordinary date ranges and default to a summary response.
## LinkedIn Ads
LinkedIn Ads is available in beta where access is enabled. It supports account discovery, hierarchy reads, account-to-creative reporting, professional-demographic pivots, targeting discovery, audience sizing, supported image workflows, draft-first campaign creation, and selected updates.
* Viewer access supports read-only work. Write workflows require a sufficient ad-account role, and some sponsored-content actions also require access to the associated LinkedIn Page.
* New campaign groups, ad sets, and supported creatives should be created in DRAFT, reviewed in Campaign Manager, and activated only after explicit approval.
* Current boundaries include no Lead Gen Form creation, no assumed video or document-ad upload workflow, and no installation or validation of the LinkedIn Insight Tag or destination-page tracking.
# Feature gates that apply across servers
* Free ends after 200 credits or 14 days, whichever comes first.
* Starter includes 2,000 credits per month.
* Pro includes 5,000 credits per month.
* Agency includes unlimited credits, Google Ads audits, multiple connected Google profiles, team billing, two seats, and priority async support.
* Starter, Pro, and Agency do not impose plan-based limits on supported platforms, ad accounts, or managed ad spend. More accounts and servers use more credits on Starter and Pro.
* Additional Agency seats cost \$25 per month each.
* LinkedIn Ads beta must be enabled for the HireOtto account. The connected LinkedIn identity and Page permissions still determine what the server can read or change.
# What is not currently included
* Enabling LinkedIn Ads does not add Lead Gen Form creation, video or document-ad uploads, LinkedIn Insight Tag validation, or CRM lead-quality analysis.
* A higher plan does not turn Tag Manager, Search Console, or Google Analytics into write-capable servers.
* Agency unlocks Google Ads audits and multi-profile access; it does not bypass the permissions granted to the connected Google account.
# Common access and entitlement failures
## The trial or billing period has ended
Check HireOtto billing status. Renew or upgrade if the trial or paid period is no longer active.
## The workspace has used all available credits
Wait for the next monthly reset or upgrade. Agency removes the credit limit.
## An audit or additional Google profile is blocked
These workflows require Agency. Core server access remains available on Starter and Pro.
## A server is connected, but an account, property, or container is missing
HireOtto access and platform permissions are separate. Reconnect the relevant Google or LinkedIn service with an identity that can access the resource.
## A write request fails on Tag Manager, Search Console, or Google Analytics
Those servers are read-only. Make the change in the platform UI, or use a supported Google Ads write workflow when the task belongs in Google Ads.
## A LinkedIn Ads write request is blocked
Inspect the role and write capability returned for the ad account. Viewer access is read-only. Draft creation or updates may also require LinkedIn Page permissions, a valid account lifecycle state, and supported campaign or creative settings.
## A GA4 workflow is unavailable
Google Analytics is in beta. Confirm beta access is enabled, reconnect the GA4 server, and verify that the connected Google account can access the property.
# Related pages
Pricing: [https://hireotto.com/pricing](https://hireotto.com/pricing)
Credits and billing: [https://docs.hireotto.com/credits-and-billing](https://docs.hireotto.com/credits-and-billing)
Connect a server: [https://docs.hireotto.com/setup/connect-ai-tool](https://docs.hireotto.com/setup/connect-ai-tool)
# Google Ads MCP Tools Reference | HireOtto
Source: https://docs.hireotto.com/google-ads-mcp-tools
Browse HireOtto’s Google Ads MCP tools for reporting, keyword research, audits, campaign creation, Performance Max, and account management.
## What HireOtto can do in Google Ads
HireOtto connects your AI client to the Google Ads accounts you authorize. Use the tools reference to check which tasks are read-only, which can change an account, and which defaults apply before you run a prompt.
* Read and report: discover accessible accounts, inspect campaign structure and settings, analyze performance, run audits, review change history, research keywords, and retrieve supported Search Console data.
* Create and update: manage supported campaigns, ad groups, ads, keywords, negative keyword lists, budgets, bidding settings, assets, conversion actions, Performance Max campaigns, and Demand Gen campaigns.
* Audit safely: daily operations, weekly optimization, and account health audits are read-only and available on the Agency plan.
* Verify every write: name the customer ID and affected entities, review the proposed values, approve the change, and read the live setting back after the tool finishes.
Your Google Ads role still controls what the connected account can read or change. Search Console uses a separate Google permission and remains read-only.
## Account discovery
List all Google Ads accounts accessible to your connected Google login(s).
**Options**
* Refresh live from Google (useful after being added to new accounts)
* Filter by a specific connected profile / email
**Example prompts**
```text theme={null}
Show me all my Google Ads accounts.
```
```text theme={null}
Refresh accounts for `xyz@gmail.com`.
```
***
## Account hygiene
Four point-in-time checks you can run on any account. Good first step whenever you take on a new account or do a quarterly review.
**What you can check**
* **Auto-tagging** — whether auto-tagging is enabled. HireOtto can also turn it on if it's off.
* **Auto-apply recommendations** — which Google recommendations are set to apply automatically. HireOtto can disable them.
* **Disapproved ads** — any ads currently disapproved, with disapproval reasons.
* **Negative keywords** — negative keywords at the campaign and ad group level. Optionally filtered to a specific campaign.
**Options**
* Account to audit (required; HireOtto will ask if you have multiple)
* For auto-tagging: whether to apply the fix, or just report
* For auto-apply: whether to disable the subscriptions, or just report
* For negative keywords: optionally filter to a specific campaign
**Example prompts**
```text theme={null}
Run a full hygiene audit on account [CUSTOMER_ID].
```
```text theme={null}
Check auto-tagging for my account and turn it on if it's off.
```
```text theme={null}
Show me all disapproved ads.
```
```text theme={null}
Review negative keywords for campaign [CAMPAIGN_ID].
```
***
## Discovery & listing
Browse the structure of any account — campaigns, ad groups, keywords, ads, and negative keyword lists. These are navigation actions, not performance reports; they return IDs and status, not metrics.
**What you can list**
* Campaigns (ID, name, status)
* Ad groups (filterable by campaign)
* Keywords / positive keywords (filterable by campaign or ad group)
* Ads (filterable by campaign, ad group, or ad ID)
* Negative keyword lists (optionally include the keywords inside each list)
* Campaign settings — bidding strategy, geo targeting, networks, ad schedule, devices
* Performance Max asset groups, assets, and signals (see Performance Max section)
* Audiences available in the account (used for PMax audience signals)
* Demand Gen campaign settings — goal, bidding, devices, geo targeting
* Demand Gen ad group settings — channel controls, locations, languages, audiences
* Demand Gen ads and creative asset references
**Example prompts**
```text theme={null}
List all campaigns in account [CUSTOMER_ID].
```
```text theme={null}
Show me the ad groups in campaign [CAMPAIGN_ID].
```
```text theme={null}
List all keywords in ad group [ADGROUP_ID].
```
```text theme={null}
Show me my negative keyword lists (include the keywords in each list).
```
```text theme={null}
What are the current campaign settings for campaign [CAMPAIGN_ID]?
```
```text theme={null}
Show me all Demand Gen campaigns in account [CUSTOMER_ID].
```
```text theme={null}
Get the channel settings for all Demand Gen ad groups in campaign [CAMPAIGN_ID].
```
```text theme={null}
Show me all ads in Demand Gen ad group [ADGROUP_ID].
```
***
## Performance reporting
Pull metrics for any level of your account across any date range. All reports support filtering, sorting, and CSV export.
**Available reports**
*Common reports*
* Campaign performance
* Ad group performance
* Ad performance
* Keyword performance
* Search terms report
* Geographic performance
* Device performance
* Impression share (competitive visibility)
* Conversion actions
* Age range performance
* Gender performance
* Extension asset performance
*Performance Max*
* PMax campaign performance
* PMax campaign placements
* PMax campaign feed types
* PMax asset group performance
* PMax asset group strength (ad strength + action items)
* PMax asset-level performance
* Top asset combinations
* PMax search terms report
*Custom (Agency plan only)*
* Custom GAQL query — write any read-only SELECT query against the Google Ads API
**Options**
* Date range: predefined (`LAST_7_DAYS`, `LAST_30_DAYS`, `LAST_MONTH`, `THIS_MONTH`, etc.) or a custom start/end date
* Filter by campaign or ad group
* Sort by: cost, clicks, impressions, conversions, CTR, average CPC, cost per conversion
* Segment by day
* Output mode: `summary` (default), `summary_and_csv`, `csv_only`
* Inline row limit (default 50)
**Example prompts**
```text theme={null}
Show campaign performance for the last 30 days.
```
```text theme={null}
Pull keyword performance for campaign [CAMPAIGN_ID] from April 1 to April 30, sorted by cost.
```
```text theme={null}
Get the search terms report for last month and export to CSV.
```
```text theme={null}
Show device performance for account [CUSTOMER_ID] — last 7 days.
```
```text theme={null}
Pull impression share data for last month.
```
```text theme={null}
Get PMax asset group strength for all asset groups.
```
```text theme={null}
Show extension asset performance for account [CUSTOMER_ID] over the last 30 days.
```
```text theme={null}
Show campaign-level sitelink performance for campaign [CAMPAIGN_ID] over the last 30 days.
```
```text theme={null}
Show customer-level call asset performance for account [CUSTOMER_ID] this month.
```
→ For a practical workflow, see [Analyze Google Ads performance reports with AI](/guides/reporting).
***
## Keyword research
Generate keyword ideas or get historical metrics for a list of known keywords. Uses the same underlying Google Keyword Planner API.
**What you can do**
* **Keyword ideas** — generate new keyword suggestions from seed keywords or a URL
* **Historical metrics** — get search volume, competition, and bid ranges for keywords you already have
**Options**
* Seed keywords or a page URL (for ideas)
* Locations (country, region, or city — one or multiple)
* Location mode: aggregated across all locations, or separate results per location
* Language
* Network: Google Search only, or Google Search + partners
* Date range for historical data (default: last 12 complete months)
* Sort by: average monthly searches, competition, bid ranges
* Filter by minimum search volume or competition level (Low / Medium / High)
**Example prompts**
```text theme={null}
Generate keyword ideas for "project management software" targeting the US.
```
```text theme={null}
Keyword ideas based on this URL: [YOUR_URL] — target UK and Australia separately.
```
```text theme={null}
Get historical metrics for these keywords: [KEYWORD_1], [KEYWORD_2], [KEYWORD_3] — US, last 12 months.
```
```text theme={null}
Find low-competition keywords related to "accounting software" with at least 500 monthly searches.
```
→ For a practical workflow, see [Google Ads keyword research with AI](/guides/keyword-research-ai).
***
## Campaign creation
### Search campaigns
Create a new Search campaign, paused by default so you can review before launching.
**What gets set at creation**
* Campaign name and daily budget
* Location and language targeting
* Bidding strategy
* UTM tracking template (applied automatically)
* EU political advertising: doesn't contain
* Status: paused
* Network targeting: Google search only (no display or partners)
* Location presence targeting: 'Presence' not 'Presence or Interest'
**Bidding strategies**
* Maximise clicks (with optional max CPC cap)
* Maximise conversions (with optional target CPA)
* Maximise conversion value (with optional target ROAS)
* Target impression share (requires: location preference, share target, max CPC cap)
* Manual CPC
**Example prompt**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]" with a $[BUDGET]/day budget, targeting [LOCATION], with Maximise Conversions bidding and a target CPA of $[TARGET_CPA].
```
#### Ad & keyword management
**Responsive Search Ads**
Create new RSAs or update existing ones.
**Create**
* Requires: ad group, headlines (3–15, max 30 chars each), descriptions (2–4, max 90 chars each), final URL, and optional display URL paths
* Supports headline and description pinning
**Update**
* Change headlines, descriptions, or display URL paths on an existing ad
* Change ad status (enable, pause, remove)
**Example prompts**
```text theme={null}
Create a responsive search ad in ad group [ADGROUP_ID] with these headlines: [H1], [H2], [H3] and descriptions: [D1], [D2]. Final URL: [URL].
```
```text theme={null}
Pause ad [AD_ID].
```
```text theme={null}
Update the headlines on ad [AD_ID] — replace "[OLD_HEADLINE]" with "[NEW_HEADLINE]".
```
#### Keywords
Add positive (targeted) keywords to an ad group, or manage negative keywords at the campaign level.
**Match types:** Broad, Phrase, Exact
**Example prompts**
```text theme={null}
Add these keywords to ad group [ADGROUP_ID] as exact match: [KW1], [KW2], [KW3].
```
```text theme={null}
Add "[KEYWORD]" as a phrase match negative keyword to campaign [CAMPAIGN_ID].
```
#### Negative keyword lists
HireOtto can add keywords to a shared negative list, attach or detach a list from campaigns, and remove individual negative keywords. To remove one item, use its exact resource identifier when available. Otherwise provide the exact keyword text and match type, review the resolved match, and then approve the removal.
**Example prompts**
```text theme={null}
Create a negative keyword list called "[LIST_NAME]" with these keywords: [KW1], [KW2].
```
```text theme={null}
Assign negative list [LIST_ID] to campaign [CAMPAIGN_ID].
```
```text theme={null}
Add "[KEYWORD]" to negative list [LIST_ID].
```
→ For a practical workflow, see [Manage Google Ads negative keywords with AI](/guides/manage-negative-keywords-in-google-ads-with-ai).
#### Ad groups
Create ad groups or update their name and status.
**Example prompts**
```text theme={null}
Create an ad group called "[ADGROUP_NAME]" in campaign [CAMPAIGN_ID].
```
```text theme={null}
Pause ad group [ADGROUP_ID].
```
***
### Performance Max campaigns
Create a full PMax campaign with budget, asset group, and initial assets in one step.
See the [Performance Max section](#performance-max) for the full breakdown.
***
### App campaigns
Create campaigns to drive app installs, in-app actions, or pre-registrations.
**Goals**
* `installs` — drive app downloads
* `in_app_actions` — drive specific in-app events
* `in_app_action_value` — optimize for conversion value
* `engagement_in_app_actions` — re-engage existing users
* `pre_registration` — pre-launch registrations
**Example prompt**
```text theme={null}
Create an App Installs campaign called "[CAMPAIGN_NAME]" for app ID [APP_ID] on Google Play, $[BUDGET]/day budget, targeting [LOCATION].
```
→ For a practical workflow, see [Google Ads campaign management with AI](/guides/create-a-google-ads-campaign-with-ai).
***
### Demand Gen campaigns
Create and manage Demand Gen campaigns — Google's cross-inventory campaign type that runs across YouTube (in-stream, in-feed, Shorts), Discover, Gmail, and Display.
Demand Gen has more moving parts than Search: campaign shell, ad group channel controls, assets, and ads are all separate layers. HireOtto handles each step in plain English.
#### Campaign shell
**What gets set at creation**
* Campaign name
* Budget: new daily budget (by amount) or an existing non-shared budget ID
* Campaign goal: Conversions, Clicks, Conversion Value, or YouTube Engagements
* Optional bid targets: target CPA, target ROAS, or target CPC
* Device targeting (all devices eligible by default)
* Geo target type (Presence or Presence or Interest)
* Ad schedule
* Status: Paused by default — review before enabling
**Example prompts**
```text theme={null}
Create a Demand Gen campaign called "[CAMPAIGN_NAME]" with a $100/day budget, Maximize Conversions goal, target CPA of $15.
```
```text theme={null}
Create a Demand Gen campaign with a $50/day budget targeting mobile and tablet only.
```
#### Ad groups
**What you can control**
* Channel strategy: `ALL_CHANNELS` (all supported Demand Gen inventory) or `ALL_OWNED_AND_OPERATED_CHANNELS` (YouTube, Discover, Gmail — no Display)
* Explicit channel selection: YouTube in-stream, in-feed, Shorts, Discover, Gmail, Display, Maps
* Location targeting (human-readable names: "India", "Mumbai")
* Language targeting
* Audience targeting (audience resource names — use *List Audiences* to get these)
* Status: Paused by default
Use channel strategy for broad presets. Use explicit channel selection when you want to include or exclude specific inventory.
**Example prompts**
```text theme={null}
Add a Demand Gen ad group to campaign [CAMPAIGN_ID] — all channels, targeting India, English.
```
```text theme={null}
Create a Demand Gen ad group for YouTube Shorts and Discover only — US, English.
```
#### Assets
Create reusable assets before or during ad creation.
**Supported asset types**
* `MARKETING_IMAGE` — standard landscape image
* `SQUARE_MARKETING_IMAGE` — square image
* `LOGO_IMAGE` — brand logo
* `YOUTUBE_VIDEO` — YouTube video by video ID
* `TEXT` — standalone text asset
* `CALL_TO_ACTION` / `CTA` — supported values include: Apply now, Book now, Contact us, Download, Get quote, Learn more, Shop now, Sign up, Subscribe, Visit site
**Example prompts**
```text theme={null}
Create a marketing image asset from [IMAGE_URL] — name it "[ASSET_NAME]".
```
```text theme={null}
Create a CTA asset: "Learn more".
```
#### Ads
**Supported ad types**
* Single image / Multi-asset
* Carousel image
* Video / Video responsive
**What you can set**
* Final URLs
* Business name
* Headlines, descriptions, long headlines
* Call to action text
* Image assets: marketing, square, portrait, tall portrait, logo, classic display (by resource name or inline URL)
* Video assets (by resource name or YouTube video ID)
* Carousel cards (inline or by existing card asset resource names)
* Breadcrumbs (carousel)
For one-off ads, inline image URLs and YouTube video IDs are usually easiest. For reusable creative libraries, create assets first and pass their resource names.
**Example prompts**
```text theme={null}
Create a single image ad in ad group [ADGROUP_ID] — marketing image: [IMAGE_URL], headline: "[HEADLINE]", description: "[DESCRIPTION]", CTA: "Learn more", final URL: [URL].
```
```text theme={null}
Create a video ad using YouTube video [VIDEO_ID] — business name: "[BUSINESS_NAME]", headline: "[HEADLINE]", CTA: "Sign up", final URL: [URL].
```
```text theme={null}
Create a carousel ad with these cards: [CARD_1_IMAGE_URL] / [CARD_2_IMAGE_URL] — headline: "[HEADLINE]", final URL: [URL].
```
#### Inspect and update
**Inspect**
Three listing actions are available under *Discovery & listing*:
* `get_demand_gen_campaign_settings` — campaign goal, bidding, devices, geo settings
* `get_demand_gen_ad_group_settings` — channel controls, locations, languages, audiences
* `get_demand_gen_ads` — ads and their creative asset references (optionally include removed ads)
**Update campaigns**
* Campaign name, status, goal, bidding targets
* Budget assignment
* Device targeting, geo target type, ad schedule
* Start and end dates
**Update ad groups**
* Channel strategy or explicit channel selection
* Ad group name and status
**Update ads**
* Direct update: change top-level final URLs or supported tracking fields while preserving the ad ID.
* Creative replacement: change images, videos, headlines, descriptions, logos, call-to-action text, or carousel creative. HireOtto creates a replacement ad and pauses the previous ad.
Before a creative replacement, inspect the live ad, prepare the complete replacement creative, and confirm the destination campaign and ad group. After the operation, read back both ads and verify that the replacement is in the intended state and the prior ad is paused.
**Example prompts**
```text theme={null}
Show me the channel settings for all Demand Gen ad groups in account [CUSTOMER_ID].
```
```text theme={null}
Switch ad group [ADGROUP_ID] to YouTube Shorts and Gmail only.
```
```text theme={null}
Show me all ads in Demand Gen campaign [CAMPAIGN_ID], including removed ones.
```
```text theme={null}
Pause Demand Gen campaign [CAMPAIGN_ID].
```
→ For a step-by-step workflow, see [Demand Gen campaigns with AI](/guides/demand-gen).
***
## Extension assets
Manage Google Ads extension-style assets such as sitelinks, callouts, structured snippets, call assets, and price assets.
These are reusable Google Ads assets. You can create an asset once, link it at the account, campaign, or ad group level where supported, and reuse the same asset across multiple eligible levels without recreating it.
### What you can do
* List existing extension assets and see their `asset_resource_name`
* Create new sitelinks, callouts, structured snippets, call assets, and price assets
* Link an existing asset at the account, campaign, or ad group level
* Reuse the same asset across supported levels
* Unlink an asset association without deleting the underlying reusable asset
* Pull extension asset performance from the reporting tool
### Supported asset types
* `SITELINK`
* `CALLOUT`
* `STRUCTURED_SNIPPET`
* `CALL`
* `PRICE`
Create and link are separate operations. If you ask HireOtto to add a new sitelink or callout to a campaign, your AI assistant may first create the asset and then link it to the campaign.
Unlinking removes the association only. The underlying asset remains available by `asset_resource_name`, though Google Ads may show the removed association under removed asset filters in the UI.
### Example prompts
```text theme={null}
List all extension assets in account [CUSTOMER_ID]. Include sitelinks, callouts, structured snippets, call assets, and price assets.
```
```text theme={null}
Create a sitelink asset in account [CUSTOMER_ID]:
Name: Pricing Sitelink
Link text: View Pricing
Description 1: Compare plans
Description 2: Choose your fit
Final URL: https://example.com/pricing
```
```text theme={null}
Link this sitelink asset to campaign [CAMPAIGN_ID]:
customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
```text theme={null}
Reuse this same sitelink asset and link it to ad group [ADGROUP_ID]:
customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
```text theme={null}
Create these callouts in account [CUSTOMER_ID]:
Free setup
No long-term contract
24/7 support
Then link them at the account level.
```
```text theme={null}
Unlink this campaign-level sitelink association:
customers/[CUSTOMER_ID]/campaignAssets/[CAMPAIGN_ID]~[ASSET_ID]~SITELINK
```
***
## Campaign settings
Update settings on existing Search campaigns.
**What you can change**
* Campaign status (enable / pause)
* Daily budget
* Bidding strategy
* Location and language targeting
* Network settings (Search Partners, Display Network)
* Ad serving optimization
* Campaign start and end dates
* Device and location bid modifiers
* EU political advertising declaration
**Example prompts**
```text theme={null}
Pause campaign [CAMPAIGN_ID].
```
```text theme={null}
Change the budget for campaign [CAMPAIGN_ID] to $[AMOUNT]/day.
```
```text theme={null}
Switch campaign [CAMPAIGN_ID] to Maximise Conversions with a $[TARGET_CPA] target CPA.
```
```text theme={null}
Turn off Search Partners for campaign [CAMPAIGN_ID].
```
```text theme={null}
Increase mobile bid modifier by 20% for campaign [CAMPAIGN_ID].
```
### URL tracking fields
HireOtto can read and update supported URL-tracking settings at account, campaign, ad-group, and ad level.
Account level
* Tracking template.
* Final URL suffix.
* Account-level custom parameters are not supported.
Campaign and ad-group level
* Tracking template.
* Final URL suffix.
* Custom parameters.
Ad level
Supported Search and Demand Gen ads can update the final URL, mobile final URL, tracking template, final URL suffix, and custom parameters.
How updates behave
* Omit a field to leave it unchanged.
* Use an empty string to clear a tracking template or final URL suffix.
* Use an empty object or list to clear custom parameters.
* A custom-parameter update replaces the complete existing set, so include every parameter you want to keep.
* Campaign custom parameters support up to 8 alphanumeric keys.
Demand Gen URL updates
A direct update to a Demand Gen ad’s top-level final URL or tracking fields preserves the ad ID. It does not update URLs stored inside carousel cards. Changing creative fields uses the creative-replacement workflow instead: HireOtto creates a replacement ad and pauses the previous ad.
Example
Common failures
* The tracking template is invalid or contains unsupported ValueTrack syntax.
* A custom-parameter key contains punctuation or exceeds platform limits.
* An update unintentionally removes parameters because the complete existing set was not included.
* The final URL belongs to a Demand Gen carousel card rather than the ad’s top-level URL.
* The connected user can read the campaign but does not have permission to edit it.
***
## Campaign budgets, bidding strategies, and conversion actions
Manage advanced optimization settings for existing Google Ads campaigns.
These tools are useful when you want to split campaigns out of shared budgets, move campaigns between portfolio and standard bidding, clean up unused portfolio strategies, or update conversion action values for value-based bidding.
### Campaign budgets
What you can do
* List campaign budgets and see which campaigns use each budget
* Create standalone/non-shared budgets
* Create shared budgets
* Move a campaign to an existing budget
* Create a new dedicated budget and attach it to an existing campaign
* Update budget amount and shareability where Google Ads allows it
* Remove unused budgets safely
Important notes
* Campaigns cannot have no budget.
* “Detaching” a budget means replacing it with another budget.
* Replacing a campaign’s budget can affect spend/overdelivery behavior. If the goal is only to change spend, update the current budget amount instead.
* Otto does not remove old or unused budgets automatically.
**Example prompts**
```text theme={null}
List all campaign budgets in account [CUSTOMER_ID] and show which campaigns use each one.
```
```text theme={null}
Create a new standalone daily budget of $25 called "[BUDGET_NAME]" in account [CUSTOMER_ID].
```
```text theme={null}
Move campaign [CAMPAIGN_ID] to budget [BUDGET_ID].
```
```text theme={null}
Create a new dedicated $50/day budget and attach it to campaign [CAMPAIGN_ID].
```
```text theme={null}
Remove unused budget [BUDGET_ID].
```
### Bidding strategies
What you can do
* List portfolio bidding strategies
* Create portfolio bidding strategies
* Attach a campaign to an existing portfolio bidding strategy
* Move a campaign back to standard campaign-level bidding
* Remove unused portfolio bidding strategies safely
* Link an existing portfolio bidding strategy to an existing shared budget
* Attach a campaign to an aligned shared budget + portfolio strategy in one update
* Move a campaign out of an aligned shared-budget + portfolio setup into a new dedicated budget and standard bidding
Supported examples
* Standard bidding: Manual CPC, Target Spend, Maximize Conversions, Maximize Conversion Value, Target Impression Share
* Portfolio bidding: Target Spend, Target CPA, Target ROAS, Maximize Conversions, Maximize Conversion Value, Target Impression Share
Important notes
* Standard bidding belongs to one campaign and is set directly on the campaign.
* Portfolio bidding is an account-level bidding strategy that can be shared across campaigns.
* Shared budgets and portfolio strategies can be explicitly aligned in Google Ads.
* When alignment exists, budget and bidding changes often need to happen together.
* Otto includes atomic workflows for these aligned shared-budget + portfolio cases.
* Otto does not remove unused portfolio strategies automatically.
**Example prompts**
```text theme={null}
List all portfolio bidding strategies in account [CUSTOMER_ID] and show which campaigns use each one.
```
```text theme={null}
Create a portfolio Maximize Conversions strategy called "[STRATEGY_NAME]".
```
```text theme={null}
Attach campaign [CAMPAIGN_ID] to portfolio bidding strategy [BIDDING_STRATEGY_ID].
```
```text theme={null}
Move campaign [CAMPAIGN_ID] to standard Maximize Conversions bidding.
```
```text theme={null}
Create a new dedicated $40/day budget for campaign [CAMPAIGN_ID] and move it from portfolio bidding to standard Maximize Conversions in one update.
```
```text theme={null}
Link shared budget [BUDGET_ID] to portfolio bidding strategy [BIDDING_STRATEGY_ID].
```
```text theme={null}
Attach campaign [CAMPAIGN_ID] to shared budget [BUDGET_ID] and portfolio strategy [BIDDING_STRATEGY_ID] together.
```
```text theme={null}
Remove unused portfolio bidding strategy [BIDDING_STRATEGY_ID].
```
### Conversion actions
HireOtto can inspect conversion actions, create supported native Google Ads conversion actions, import eligible GA4 key events, and update supported conversion settings.
#### Create a native Google Ads conversion action
Provide a name and choose the source type:
* WEBPAGE — default.
* UPLOAD\_CLICKS.
* UPLOAD\_CALLS.
You can also set the category, counting type, primary status, default value, whether to always use that value, and a supported attribution model.
Creating a WEBPAGE action creates the Google Ads object. It does not install, test, or validate the website tag. Creating an UPLOAD\_CLICKS or UPLOAD\_CALLS action does not upload offline conversions.
#### Import a GA4 key event
The event must already be marked as a key event in a Google Analytics property linked to the Google Ads account. Provide the exact event name. Include the GA4 property ID when possible; it is required when the same event name exists in more than one linked property.
#### Update an existing action
Supported settings include the name, status, category, counting type, primary status, default value, value behavior, attribution model, and eligible lookback windows. Editability depends on the action’s source, ownership, and current Google Ads eligibility.
Use primary status – not the legacy include-in-conversions field – to control whether an eligible conversion goal can influence optimization. Changing primary status or attribution can affect both reporting and automated bidding.
#### Safe sequence
* List the existing actions and check for duplicates.
* Confirm whether the business outcome belongs in Google Ads natively or should be imported from GA4.
* Prepare the exact settings.
* Create, import, or update one action.
* Validate measurement data before making it primary.
* Read the action back and confirm the live settings.
#### Examples
#### Common failures
* A conversion action with the same purpose already exists.
* The GA4 property is not linked to the Google Ads account.
* The GA4 event is not marked as a key event.
* The event name is ambiguous across linked properties and no property ID was provided.
* The requested field is not editable for that action type or origin.
* The connected Google user lacks permission to make the change.
* The tag or offline upload pipeline has not been implemented; creating the action alone does not solve measurement.
***
## Performance Max
Full management for PMax campaigns — create, update assets, manage signals.
→ See the [Performance Max guide](/guides/manage-performance-max-campaigns) for the full end-to-end walkthrough.
### Create a PMax campaign
One step: creates the budget, campaign, asset group, and uploads your initial assets.
**Required assets**
* Headlines (3–15, max 30 chars each)
* Long headline (1, max 90 chars)
* Descriptions (2–5, max 90 chars each)
* Business name
* At least 1 landscape marketing image
* At least 1 square marketing image
* At least 1 logo
**Optional**
* Audience signals and search themes
* Location and language targeting
* Target CPA / target ROAS
* Brand guidelines (locks business name and logos at campaign level, shared across all asset groups)
* EU political advertising declaration
**Example prompt**
```text theme={null}
Create a PMax campaign called "[CAMPAIGN_NAME]" with a [BUDGET]/day budget, targeting [LOCATION].
Asset group: [ASSET_GROUP_NAME]
Headlines: [H1], [H2], [H3]
Long headline: [LH1]
Descriptions: [D1], [D2]
Business name: [BUSINESS_NAME]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
```
### Add a new asset group
Add a second asset group to an existing PMax campaign.
```text theme={null}
Add a new asset group called "[ASSET_GROUP_NAME]" to PMax campaign [CAMPAIGN_ID].
```
For brand-guidelines-enabled campaigns, omit business name and logo — they're inherited from the campaign level.
### Update asset group status
Pause, enable, or remove an asset group without touching the campaign.
```text theme={null}
Pause asset group [ASSET_GROUP_ID].
```
```text theme={null}
Enable asset group [ASSET_GROUP_ID].
```
### Update assets
**Add new assets** (upload new creative by URL):
```text theme={null}
Add these headlines to asset group [ASSET_GROUP_ID]: [H1], [H2].
```
```text theme={null}
Add a new landscape image to asset group [ASSET_GROUP_ID]: [IMAGE_URL].
```
**Attach existing assets** (reuse already-uploaded assets from your library without creating duplicates):
```text theme={null}
Attach existing assets to asset group [ASSET_GROUP_ID]:
Landscape image: customers/[CUSTOMER_ID]/assets/[ASSET_ID]
Square image: customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
**Remove assets** (requires exact asset resource names — list assets first):
```text theme={null}
List assets for asset group [ASSET_GROUP_ID].
```
```text theme={null}
Remove the landscape image customers/[CUSTOMER_ID]/assets/[ASSET_ID] from asset group [ASSET_GROUP_ID].
```
### List brand assets (brand-guidelines campaigns)
Returns business name, logo, and landscape logo assets attached at the campaign level.
```text theme={null}
List brand assets for PMax campaign [CAMPAIGN_ID].
```
### Manage audience signals and search themes
```text theme={null}
Add audience [AUDIENCE_ID] as a signal to asset group [ASSET_GROUP_ID].
```
```text theme={null}
Add these search themes to asset group [ASSET_GROUP_ID]: [THEME_1], [THEME_2].
```
```text theme={null}
List current signals for asset group [ASSET_GROUP_ID].
```
***
## Change history
See what changed in an account, when it changed, and who changed it.
**Two levels of detail**
* **Quick scan** — which campaigns and ad groups were touched in a given period
* **Detailed timeline** — field-level change log with timestamps and editor info (last 30 days)
**Options**
* Date range (required)
* Filter by campaign or ad group
* Output mode: `summary`, `summary_and_csv`, `csv_only`
**Example prompts**
```text theme={null}
What changed in account [CUSTOMER_ID] in the last 7 days?
```
```text theme={null}
Show me the detailed change history for campaign [CAMPAIGN_ID] over the last 14 days, exported to CSV.
```
```text theme={null}
Did anyone make changes to this account last week?
```
***
## Daily ops audit
The daily operations audit is a read-only Agency-plan check for delivery, pacing, and sudden spend changes. It is designed for daily triage, not a full optimization review.
### What it checks
* Campaigns that stopped serving even though they are enabled.
* Spend spikes or drops against the recent baseline.
* Campaign and shared-budget pacing.
* Coverage gaps or partial results that may make a finding incomplete.
### Defaults
* Audit date: yesterday in the Google Ads account time zone.
* Campaign scope: enabled campaigns. Paused campaigns can be included; removed campaigns are excluded.
* Baseline: the previous 14 days.
* Spend spike threshold: at least 1.5 times the baseline.
* Spend drop threshold: at most 0.5 times the baseline.
* Pacing thresholds: above 1.5 times or below 0.5 times expected pacing.
* Minimum baseline activity: 1 unit of account currency in average daily cost and 10 average daily impressions.
* Inline findings: 25 by default; set 1–100.
* CSV link lifetime: 30 minutes by default; set 1–1,440 minutes.
### What it does not check
Daily operations does not review search terms, keyword opportunities, ad creative, location performance, or device performance. Use the weekly optimization audit for those questions.
### Example
```text theme={null}
Run the daily operations audit for customer 123-456-7890 for yesterday. Check enabled campaigns only. Show the most urgent delivery and pacing findings, include the comparison baseline, and do not make changes.
```
### Limits and failure cases
* The audit never writes to Google Ads.
* A shared budget is evaluated as a group, so the result may not assign all pacing pressure to one campaign.
* Newly launched or very low-volume campaigns may not have enough baseline activity to classify a spike or drop.
* If Google Ads returns only part of the requested data, treat the audit as partial and review the coverage notes.
* Download links expire. Rerun the audit if a CSV link has expired.
***
## Weekly optimization audit
The weekly optimization audit is a read-only Agency-plan review that turns recent Google Ads performance into a ranked decision queue. It covers campaign trends, search terms, keywords, and responsive search ads without changing the account.
### Default windows and thresholds
* Performance window: the last 7 days.
* Comparison: the immediately preceding period of equal length.
* Search-term lookback: 30 days, excluding the most recent 3 days to allow for reporting and conversion lag.
* Negative-keyword candidate: fewer than 1 conversion, at least 3 clicks, and no minimum-spend requirement unless you set one.
* New-keyword candidate: at least 1 conversion.
* Keyword review: at least 10 clicks.
* Target CPA: optional. If omitted, HireOtto can use the account CPA when the account has at least 5 conversions in the selected period.
* High-CPA threshold: 1.5 times the target or account CPA.
* RSA review: at least 100 impressions; low CTR is 75% or less of the ad group CTR.
* Campaign performance drop: current conversions at 50% or less of the comparison period.
* Detailed rows: 500 per detailed query by default; set 25–5,000.
* Inline findings: 50 by default; set 1–200.
* CSV link lifetime: 30 minutes by default; set 1–1,440 minutes.
### What it can surface
* Campaigns with material changes in spend, conversions, CPA, or search impression share.
* Search terms that may belong on a negative list.
* Converting search terms that may deserve their own keyword.
* Manual CPC keywords that may need a bid review.
* Disapproved or low-CTR responsive search ads.
* Findings that need more evidence before a marketer acts.
### Example
```text theme={null}
Run the weekly optimization audit for customer 123-456-7890. Compare the last 7 days with the previous 7 days. Use the default search-term lag, rank the findings by severity, and separate Act, Investigate, and Monitor items. Do not change the account.
```
### Limits and failure cases
* Candidate means review, not automatic action. Check intent, conversion lag, sample size, match type, lead quality, and business context before approving a change.
* A search-term row can be absent because of Google Ads privacy thresholds or reporting limits.
* If the account has fewer than 5 conversions and no target CPA is supplied, CPA-based classifications may be limited.
* Partial results and row limits appear in the coverage notes. Increase limits or narrow the scope when important entities are missing.
* The audit never writes to Google Ads.
***
## Account health audit
The account health audit is a read-only Agency-plan check for structural, tracking, targeting, quality, and coverage risks. Use it monthly, quarterly, or before taking over an account.
### Defaults
* Review window: the last 90 days.
* Comparison: the immediately preceding 90 days.
* RSA copy review: off by default.
* Detailed checklist: off by default.
* Keyword rows: 5,000 by default; set 100–20,000.
* Ad rows: 1,000 by default when RSA copy review is enabled; set 100–5,000.
* Inline findings: 100 by default; set 1–300.
* CSV link lifetime: 30 minutes by default; set 1–1,440 minutes.
### What it reviews
* Auto-tagging and conversion-tracking readiness visible in Google Ads.
* Search and display network settings.
* Location targeting mode and language targeting.
* Keyword count by ad group, match-type mix, Quality Score, and Quality Score components.
* Negative-keyword coverage.
* Geographic and device performance.
* Search impression share lost to budget or rank.
* Optional RSA counts, copy review, and pinning patterns.
### Example
```text theme={null}
Run an account health audit for customer 123-456-7890. Compare the last 90 days with the previous 90 days. Include the detailed checklist and RSA review. Return the highest-severity risks first and do not make changes.
```
### Limits and failure cases
* The audit can only evaluate data available through the connected Google Ads account. It does not know CRM lead quality, competitor activity, landing-page experiments, or offline business context unless you provide that context separately.
* Enabling RSA copy review increases the amount of ad data requested and can make large-account audits slower or more likely to return partial coverage.
* A missing signal is not always a broken setup. Confirm account structure, measurement design, and campaign intent before changing anything.
* Review coverage notes whenever limits, permissions, or Google Ads reporting restrictions exclude part of the account.
* The audit never writes to Google Ads.
***
## Google Search Console
Analyze organic search data and URL indexing from Google Search Console.
Before using Search Console tools, connect Search Console:
```text theme={null}
Connect my Google Search Console account.
```
### What you can do
* List Search Console properties available to your connected Google account
* Pull organic query reports
* Review page performance
* Break down results by country, device, date, hour, or search appearance
* Export Search Console data to CSV
* Check whether a URL is indexed in Google
* List submitted sitemaps
### Example prompts
```text theme={null}
Show me the Search Console sites I have access to.
```
```text theme={null}
Show me the top organic search queries for the last 28 days. Include a CSV export.
```
```text theme={null}
Show me page performance for the last 28 days split by country and device. Give me the top pages inline and export the full data.
```
```text theme={null}
Show me organic queries in the US for the last 28 days. I want clicks, impressions, CTR and average position.
```
```text theme={null}
Check if https://www.example.com/pricing is indexed in Google.
```
For setup and workflow details, see [Google Search Console MCP reporting](/guides/google-search-console).
***
## Common access, output, and safety rules
* Account access: HireOtto only sees Google Ads accounts available to the Google identity you connect. The user’s Google Ads role determines whether a write can succeed.
* Customer IDs: use the ten-digit customer ID without guessing. Manager-account access does not remove the need to target the intended client account.
* Audit access: daily operations, weekly optimization, and account health audits are Agency-plan features and are always read-only.
* Search Console: Search Console tools require separate authorization and remain read-only.
* Inline and CSV output: large results may be summarized inline and returned as a downloadable CSV. CSV links expire; rerun the request to create a fresh link.
* Partial coverage: API limits, row limits, permissions, privacy thresholds, and unavailable metrics can produce partial results. Read the coverage notes before acting.
* Validation: Google Ads can reject writes because of account state, entity state, field compatibility, date rules, policy, or permissions. Correct the request and retry only after reviewing the error.
* Verification: for consequential changes, ask HireOtto to show the current value, proposed value, customer ID, and entity IDs; wait for approval; apply one class of change; then read the live value back.
* Pricing and credits: availability and credit use depend on the active HireOtto plan. Check the current pricing page before promising access.
## Billing
Check your current HireOtto plan, credit balance, and billing period.
```text theme={null}
What's my current HireOtto plan and credit balance?
```
→ See [Credits & billing](/credits-and-billing) for the full reference.
# Build custom GA4 reports with HireOtto
Source: https://docs.hireotto.com/google-analytics/custom-reporting
Choose property-specific dimensions and metrics, check compatibility, and build review-ready GA4 reports with filters, comparisons, and exports.
Use HireOtto to turn a reporting question into a property-specific GA4 report without rebuilding it in the Analytics interface. The reliable workflow is: confirm the property, find the current API fields, check that those fields work together, run a small report, review coverage, then export the rows you need.
HireOtto's Google Analytics server is read-only. Running a report does not change the GA4 property, its events, key events, audiences, links, or data streams.
Google Analytics is currently available in beta. Core GA4 tools are available on Free, Starter, Pro, and Agency plans and consume HireOtto credits. Named connection profiles require Agency. See [HireOtto pricing](https://hireotto.com/pricing) for current plan limits.
## Before you start
You need:
* HireOtto's GA4 server connected at `https://ga4.hireotto.com/mcp`
* A Google login with access to the GA4 property
* The property ID you intend to query
* A reporting question with a date range, breakdown, measures, and output requirement
If GA4 is not connected yet, follow [Connect Google Analytics 4 to Claude, ChatGPT, and AI tools](/google-analytics/quickstart).
Start by verifying the property rather than relying on a property name alone:
## Use this reporting workflow
### 1. Write the reporting brief
Define the question before selecting fields. Include:
* **Property:** property ID and, for Agency users, the named profile
* **Period:** complete start and end dates
* **Breakdown:** the dimensions that define each row
* **Measures:** the metrics that answer the question
* **Filters:** the traffic, events, pages, countries, or campaigns to include or exclude
* **Comparison:** the previous period, previous year, or another explicit range
* **Sort and row cap:** how results should be ranked and how much detail to return
* **Output:** inline review, CSV export, or both
Prefer complete periods for performance comparisons. Ending a report at `yesterday` avoids mixing a partial current day with completed days. GA4 interprets relative dates in the property's time zone.
### 2. Find the property's current fields
Use metadata before asking for a custom report. Metadata returns the dimensions and metrics available to that property, including registered custom definitions.
The metadata search accepts:
| Parameter | Default | Accepted value | Use |
| -------------------- | --------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
| `property_id` | Required | A GA4 property ID, with or without `properties/` | Selects the property's reporting schema |
| `search` | Blank | Text matched against API name, UI name, description, or category | Narrows a large schema |
| `include_deprecated` | `false` | `true` or `false` | Includes deprecated API-name aliases in the metadata details |
| `limit` | `500` | 1–2,000 per dimension and metric list | Caps returned metadata items |
| `profile_id` | `default` | `default`, or an Agency named profile | Selects the connected Google login |
Do not guess custom dimension or custom metric names. Their API names are property-specific. Search the property's metadata and use the returned API name exactly.
### 3. Check field compatibility
Dimensions and metrics can exist in GA4 but still be incompatible in the same Core report. Check the exact set before running the report:
The compatibility check accepts:
| Parameter | Default | Accepted value | Use |
| ---------------------- | ------------ | ------------------------------------------------------------ | ---------------------------------- |
| `property_id` | Required | A GA4 property ID | Selects the property |
| `dimensions` | Empty list | GA4 dimension API names | Fields that define rows |
| `metrics` | Empty list | GA4 metric API names | Fields that measure results |
| `compatibility_filter` | `COMPATIBLE` | `COMPATIBLE`, `INCOMPATIBLE`, or the API's unspecified value | Filters the compatibility response |
| `profile_id` | `default` | `default`, or an Agency named profile | Selects the connected login |
Compatibility checks apply to Core reports. Realtime reports use a different field set and different compatibility rules.
A compatible field set is not a complete validation of the reporting decision. It does not confirm that your date range, filters, attribution interpretation, or comparison is appropriate.
### 4. Run a small review report
Ask for a modest row cap and `summary` output first. This makes it easier to verify the property, date range, field names, filters, and ordering before creating a larger export.
For standard reports, HireOtto passes a GA4 `RunReportRequest` in `request_json`. Common request fields are:
| Field | What it controls |
| -------------------- | -------------------------------------------------------- |
| `dateRanges` | One or more reporting periods |
| `dimensions` | The breakdown shown in each row |
| `metrics` | The measures returned for each row |
| `dimensionFilter` | Conditions applied to dimension values |
| `metricFilter` | Conditions applied to metric values after aggregation |
| `orderBys` | Deterministic ranking of the result |
| `metricAggregations` | Optional totals, minimums, or maximums |
| `comparisons` | GA4 comparison definitions when supported by the request |
| `currencyCode` | Display currency for currency metrics |
| `keepEmptyRows` | Whether to retain rows whose metrics are all zero |
Use camelCase field names inside `request_json`. The outer `property_id` selects the property; a `property` field inside the request is ignored.
### 5. Review coverage before interpreting the result
Check these fields in the response:
* `row_count`: rows available from GA4 for the request
* `returned_rows`: rows HireOtto collected
* `inline_row_count`: rows shown directly in the AI client
* `truncated`: whether the collection stopped before all available rows were retrieved
* `metadata`: report time zone, currency, thresholding, sampling, schema restrictions, and high-cardinality signals when GA4 returns them
* `property_quota`: remaining GA4 Data API quota information
A short inline answer is not necessarily the full report. `inline_limit` only controls how many collected rows appear in the conversation. It does not increase collection.
### 6. Export after the report is correct
When the review report is correct, rerun it with the required collection and export limits:
CSV links are temporary. Download the file before its expiry.
## Standard report parameters and defaults
| Parameter | Default | Accepted range or value | Behavior |
| -------------------- | ----------------- | ------------------------------------------ | ------------------------------------------------ |
| `property_id` | Required | GA4 property ID | Selects the property |
| `request_json` | Required | A valid GA4 Core `RunReportRequest` object | Defines fields, dates, filters, and ordering |
| `profile_id` | `default` | `default`, or an Agency named profile | Selects the connected login |
| `max_rows` | `10,000` | 1–100,000 | Maximum rows collected across paginated requests |
| `output_mode` | `summary_and_csv` | `summary`, `summary_and_csv`, `csv_only` | Controls inline rows and CSV creation |
| `inline_limit` | `200` | 1–5,000 | Maximum collected rows shown inline |
| `export_limit` | `50,000` | 1–100,000 | Maximum collected rows written to CSV |
| `export_ttl_minutes` | `30` | 1–1,440 | CSV link lifetime |
If `request_json.limit` is lower than `max_rows`, the request limit becomes the effective collection cap. Each GA4 page contains at most 10,000 rows, and HireOtto continues paging until it reaches the effective cap or the available result ends.
`export_limit` does not cause HireOtto to collect more rows. To export 50,000 rows, set `max_rows` to at least 50,000 and confirm that the response is not truncated.
No CSV is created when GA4 returns no rows. In `csv_only` mode, an empty inline row list is expected even when the CSV contains data.
## Practical report patterns
### Compare acquisition periods
Use separate, equal, complete date ranges and label them clearly:
When several date ranges are requested, GA4 can return a date-range dimension identifying the period. Keep the raw periods visible; do not describe a change without showing both values and the denominator.
### Review landing-page quality
Do not rank low-volume pages by a rate alone. A high or low percentage built from a handful of sessions is not a stable performance signal.
### Investigate an event
Use an exact event-name filter when you already know the implemented event. A contains filter is useful for discovery, but it can combine events with different meanings.
### Build a campaign export
## Filters and ordering
Use `dimensionFilter` for dimensions and `metricFilter` for metrics. Do not place a metric in a dimension filter or a dimension in a metric filter.
For a single exact dimension value, a request can use:
```json theme={null}
{
"filter": {
"fieldName": "sessionDefaultChannelGroup",
"stringFilter": {
"matchType": "EXACT",
"value": "Paid Search",
"caseSensitive": false
}
}
}
```
For repeatable reports, specify the sort explicitly. For example, order by sessions descending instead of accepting an unspecified row order.
## Read and write scope
This workflow can read:
* Reporting metadata for the selected property
* Core report rows, totals, minimums, maximums, response metadata, and quota status
* Property configuration needed to orient the report, including streams, key events, Ads links, and custom definitions
It cannot:
* Create or edit GA4 events, key events, custom definitions, audiences, data streams, links, or property settings
* Install or validate website tags
* Change attribution or data-retention settings
* Repair missing historical data
* Confirm CRM lead quality or business impact without data you provide
## Limits and interpretation guardrails
* **Collection, inline display, and export are separate limits.** Review all three before assuming you have a complete result.
* **High-cardinality dimensions can produce an `(other)` row.** Check report metadata before treating the visible rows as a complete distribution.
* **Thresholding or schema restrictions can hide detail.** Treat metadata warnings as part of the result, not as technical noise.
* **GA4 can sample some reports.** If sampling metadata is returned, disclose it with the analysis.
* **Long ranges, many columns, complex filters, and high-cardinality fields use more GA4 quota.** Start small, then expand deliberately.
* **Current-day data is incomplete.** Prefer complete periods for comparisons unless the job is explicitly intraday monitoring.
* **GA4 and ad-platform conversions are not interchangeable.** Attribution, identity, consent, processing, and import settings can produce legitimate differences.
* **Rates need denominators.** Show the underlying sessions, users, or events alongside conversion and engagement rates.
* **Do not average row-level rates to create a total.** Use report totals or recompute the rate from the relevant summed numerator and denominator.
## Failure cases
| Problem | What it usually means | What to do |
| ---------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| GA4 is not connected | The Google authorization is missing or expired | Reconnect GA4, then retry the property list |
| Property is missing | The connected Google login cannot access it | Confirm the login and GA4 property permissions |
| Invalid field name | The API name was guessed, renamed, deprecated, or belongs to another property | Search the property's metadata and copy the current API name |
| Incompatible fields | The requested dimensions and metrics cannot be combined in a Core report | Run compatibility again and remove or split incompatible fields |
| Invalid filter | The field type, expression, or value does not match the request | Check the field in metadata and keep dimension and metric filters separate |
| Empty result | The date range, filters, property, or collection state produced no rows | Broaden one constraint at a time and confirm data exists in GA4 |
| Partial configuration result | GA4 returned some property resources but not others | Review each section's status; permissions can differ by resource |
| Truncated result | More rows exist than `max_rows` allowed HireOtto to collect | Raise `max_rows`, narrow the report, or split it into smaller requests |
| No CSV link | The output mode was `summary`, or GA4 returned no rows | Use `summary_and_csv` or `csv_only` after confirming rows exist |
| Expired CSV link | The signed export passed its time-to-live | Rerun the same reviewed request to generate a new link |
| Quota error | The property or project reached a GA4 Data API limit | Reduce complexity or wait for the relevant quota window to reset |
| HireOtto access blocked | Trial, credits, billing, or entitlement checks stopped the tool | Check billing status and current plan limits |
## A reusable approval-gated prompt
This separates three decisions: whether the question is well-defined, whether GA4 can answer it with compatible fields, and whether the result is complete enough to support action.
## Related resources
* [Connect Google Analytics 4 to Claude, ChatGPT, and AI tools](/google-analytics/quickstart)
* [Google Analytics 4 MCP tools reference](/google-analytics/tools-reference)
* [Google Analytics Data API overview](https://developers.google.com/analytics/devguides/reporting/data/v1)
* [Check GA4 field compatibility](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/checkCompatibility)
* [GA4 Data API limits and quotas](https://developers.google.com/analytics/devguides/reporting/data/v1/quotas)
# Connect Google Analytics 4 to Claude, ChatGPT, and AI tools
Source: https://docs.hireotto.com/google-analytics/quickstart
Connect HireOtto’s read-only GA4 MCP server, authorize Google Analytics, verify accessible properties, and run your first report.
Connect HireOtto’s Google Analytics 4 server to analyze property configuration, acquisition, landing pages, events, comparisons, and recent activity from your AI workspace.
Use this MCP endpoint:
```text theme={null}
https://ga4.hireotto.com/mcp
```
The Google Analytics 4 integration is available in beta. It is read-only: HireOtto can discover properties, inspect configuration, and run reports, but it cannot edit GA4 properties, data streams, key events, links, custom definitions, or other Analytics settings.
## Before you start
You need:
* An AI client that supports remote MCP servers and OAuth
* A HireOtto account with GA4 access and available usage
* A Google login that can access the GA4 property you want to analyze
You do not need to create a Google Cloud project, configure Analytics APIs, download credentials, or run a local server. HireOtto hosts the MCP server and manages the connection flow.
## Connect the GA4 server
The labels differ by AI client, but the sequence is the same:
1. Open your AI client’s connectors, integrations, or MCP settings.
2. Add a custom remote MCP server.
3. Enter `https://ga4.hireotto.com/mcp`.
4. Complete the HireOtto sign-in when prompted.
5. Return to the conversation after the server connects.
A successful MCP connection only proves that your AI client can reach HireOtto. You must authorize Google Analytics separately before the server can see any accounts or properties.
## Authorize Google Analytics
Ask your AI client:
HireOtto returns a Google authorization link. Open it, then:
1. Choose the Google login that has access to the required GA4 property.
2. Review and grant the requested read-only Analytics permission.
3. Accept HireOtto’s Terms and Privacy Policy to complete the connection.
4. Return to your AI client.
The default profile is named `default`. It is the right choice for most users and is available on every plan that includes GA4 beta access.
Granting access to the wrong Google login is the most common reason a property does not appear. HireOtto can only list the Analytics accounts and properties visible to the login you authorized.
## Verify accounts and properties
Before requesting a report, list the accessible accounts and properties:
Confirm all four identifiers:
* Account name
* Account ID
* Property display name
* Property ID
Use the property ID in later requests. This prevents a similarly named development, staging, regional, or client property from being selected by mistake.
If the result is empty, check the connected Google login and its Analytics permissions. The MCP connection can be healthy even when the authorized login has no GA4 property access.
## Inspect the property before reporting
A configuration read is a useful first check:
Replace `PROPERTY_ID` with the numeric ID returned by property discovery. You may also supply the full `properties/PROPERTY_ID` resource name.
Configuration reads can reveal whether you selected the correct web or app stream and whether the measurement objects needed for analysis exist. They do not validate that a website tag fires correctly, that events contain the intended parameters, or that imported conversions are suitable for bidding.
## Run a first standard report
Start with a constrained question and an explicit date range:
HireOtto can inspect property-specific metadata and check whether the requested dimensions and metrics are compatible. Google Analytics rejects incompatible report combinations, so compatibility should be checked before a complex request.
A good reporting prompt specifies:
* The property ID
* Exact start and end dates, or an unambiguous relative window
* Dimensions
* Metrics
* Filters
* Comparison period
* Desired output
For decision-making, keep the date range and raw values visible. A percentage change without its denominator can overstate a small movement.
## Check recent activity
Use a realtime report when you need recent activity rather than a historical date range:
Realtime reports use GA4’s recent activity window and do not accept standard historical date ranges. Use a standard report for yesterday, last week, month-over-month, or other historical comparisons.
## Profile behavior
The optional `profile_id` parameter selects which saved Google connection to use.
| Parameter | Default | Behavior |
| -------------- | --------- | ---------------------------------------------------------------------------------------------- |
| `profile_id` | `default` | Uses the primary Google Analytics connection. |
| Named profile | None | Uses a separately authorized Google login. Named profiles require Agency or Enterprise access. |
| Profile naming | — | Profile IDs cannot contain a colon. |
Free, Starter, and Pro users should omit `profile_id` or use `default`. Agency and Enterprise users can authorize named profiles to keep client or business logins separate.
To connect a named profile:
Then include that same profile ID in discovery and reporting requests:
A profile separates saved authorization. It does not grant additional Google Analytics permissions. Each profile can only read the properties visible to its own Google login.
## Read and write scope
| Workflow | Access |
| ------------------------------------------------------------------------------------ | ----------------------------------- |
| Authenticate a Google login | Starts a read-only OAuth connection |
| List accounts and properties | Read |
| Inspect property details and data streams | Read |
| Inspect key events, Google Ads links, and custom definitions | Read |
| Discover property-specific dimensions and metrics | Read |
| Check dimension and metric compatibility | Read |
| Run standard and comparison reports | Read |
| Run realtime reports | Read |
| Export report rows | Read |
| Create or edit properties, streams, events, key events, links, or custom definitions | Not supported |
| Change attribution, retention, reporting identity, or other GA4 settings | Not supported |
HireOtto’s GA4 integration does not write to Analytics, even if the connected Google user has an Administrator or Editor role.
## Reporting defaults and limits
These defaults apply when the AI client does not supply an override.
### Standard reports
| Setting | Default | Accepted behavior |
| ---------------------- | ----------------- | --------------------------------------------------------------- |
| Maximum rows collected | 10,000 | Clamped to 1–100,000 rows |
| Output mode | `summary_and_csv` | Returns an inline summary and a downloadable CSV when available |
| Inline rows | 200 | Clamped to 1–5,000 rows |
| CSV export rows | 50,000 | Clamped to 1–100,000 rows |
| Export link lifetime | 30 minutes | Clamped to 1–1,440 minutes |
If the report request includes its own lower row limit, that lower limit takes precedence.
### Realtime reports
| Setting | Default | Accepted behavior |
| -------------------- | ---------- | ------------------------------------ |
| Output mode | `summary` | Returns an inline summary by default |
| Inline rows | 500 | Clamped to 1–5,000 rows |
| CSV export rows | 10,000 | Clamped to 1–10,000 rows |
| Export link lifetime | 30 minutes | Clamped to 1–1,440 minutes |
### Metadata and compatibility
* Metadata search returns up to 500 dimensions and 500 metrics by default; the limit is clamped to 1–2,000 for each group.
* Deprecated API names are excluded by default.
* Compatibility checks return compatible fields by default.
Large reports may be truncated at the requested or plan-supported limit. Download exports promptly because signed links expire.
## Plans, beta status, and usage
GA4 reporting is currently in beta.
| Plan | GA4 beta access | Usage |
| ---------- | ------------------------- | --------------------------------------------- |
| Free | Included during the trial | 14 days or 200 credits, whichever comes first |
| Starter | Included | 2,000 credits per month |
| Pro | Included | 5,000 credits per month |
| Agency | Included | Unlimited usage and multiple profiles |
| Enterprise | Contact HireOtto | Custom access and controls |
Requests can be blocked when the trial ends, monthly credits are exhausted, a feature is outside the current plan, or a named profile is used without Agency or Enterprise access. Check the current [pricing page](https://hireotto.com/pricing) before relying on an entitlement.
## Common failure cases
### The server connects, but GA4 is not authorized
The AI client-to-HireOtto connection succeeded, but the Google connection did not.
Ask to connect Google Analytics again, open the authorization link, finish consent, and then retry property discovery.
### No accounts or properties appear
The authorized Google login has no visible GA4 properties, or it is the wrong login.
Reconnect with the correct Google account or ask an Analytics administrator to grant that login access. Property discovery only returns resources accessible to the caller.
### The expected property is missing
Verify that you authorized the intended Google identity and that its access has not been removed. Search by both property display name and property ID.
### A named profile is rejected
Named profiles require Agency or Enterprise access. Use the `default` profile or change to a plan that supports multiple profiles.
### Authorization worked before but now fails
The Google token may have expired, been revoked, or lost the required scope. Reconnect the affected profile and repeat property discovery.
### A report says dimensions and metrics are incompatible
Remove or replace the incompatible fields. Ask HireOtto to search property metadata and check compatibility before rerunning the report.
### A report returns no rows
Confirm the property, date range, filters, and field names. No rows can also be a valid result when the property has no matching data. Do not broaden the request until you have verified the property and filters.
### The output is incomplete
Reduce the dimensions, narrow the date range, or request a CSV within the supported export limit. If the result reached a row cap, treat it as partial rather than as a complete account view.
### A report is blocked by quota or usage
Retry later for a temporary Google Analytics API quota response. For a HireOtto plan or credit block, review the account’s current entitlement and usage.
## Practical prompts
### Confirm the connection
### Review measurement configuration
### Review acquisition
### Review landing pages
### Use property metadata before a custom report
### Keep profiles separate
## Safe operating pattern
For consequential analysis, use this sequence:
1. Discover the live property.
2. Confirm the exact property ID.
3. Inspect relevant configuration.
4. Check reporting metadata and compatibility.
5. Run a small report with explicit dates.
6. Review raw rows and any truncation notice.
7. Expand or export only after the small report is correct.
HireOtto can collect and organize GA4 evidence. The marketer still decides whether the measurement design is trustworthy and whether the data is strong enough to support a business decision.
## Related pages
* [Connect HireOtto to Claude, ChatGPT, or another AI tool](https://docs.hireotto.com/setup/connect-ai-tool)
* [Google Analytics MCP beta](https://hireotto.com/analytics-mcp)
* [Plans and pricing](https://hireotto.com/pricing)
# Google Analytics 4 MCP tools reference
Source: https://docs.hireotto.com/google-analytics/tools-reference
Discover GA4 properties, inspect configuration, choose compatible reporting fields, and retrieve standard or realtime reports with clear output limits.
Use HireOtto’s GA4 tools to identify the right property, inspect its measurement configuration, and retrieve the rows needed to answer an acquisition, landing-page, or event question. Start with property discovery, check reporting fields, then run a small report before requesting a larger export.
GA4 is available in beta. Analytics access is read-only: none of these tools creates, edits, or deletes GA4 settings. Connecting a Google login saves an authorization in HireOtto; downloading a report creates an export, not a change in Analytics.
## Connect and confirm access
Add `https://ga4.hireotto.com/mcp` to your remote MCP-capable AI client, complete the HireOtto sign-in, then authorize Google Analytics separately. Use a Google login that can access the required property. See the [GA4 quickstart](/google-analytics/quickstart) for the complete flow.
The Free trial, Starter, Pro, and Agency plans include GA4 beta. The trial provides 200 credits or 14 days, whichever comes first; Starter includes 2,000 monthly credits and Pro 5,000. Agency includes unlimited credits and multiple connected profiles. Creating named GA4 connections requires Agency or enabled Enterprise access. Google permissions and API quotas still apply on every plan. See [current pricing](https://hireotto.com/pricing).
## Choose the right tool
| Reader job | Tool title | What it does |
| ------------------------------ | -------------------------------- | ------------------------------------------------------------------------------ |
| Connect or reconnect Google | Authenticate Google Analytics | Returns a read-only Google authorization link |
| Find the intended property | List GA4 Accounts and Properties | Lists accessible accounts and properties with names and IDs |
| Inspect measurement setup | Get GA4 Property Configuration | Reads property details, streams, key events, Ads links, and custom definitions |
| Find valid reporting fields | Get GA4 Reporting Metadata | Searches property-specific dimensions and metrics |
| Check a field combination | Check GA4 Report Compatibility | Checks Core reporting dimensions and metrics |
| Analyze historical performance | Run GA4 Report | Retrieves a standard report, including supported comparisons and filters |
| Check recent activity | Run GA4 Realtime Report | Retrieves recent activity using realtime fields and minute ranges |
| Check HireOtto access or usage | Get Billing Status | Reads the current plan, usage, and access information |
These tools do not install tags, send test events, mark key events, create Google Ads links, edit custom definitions, or change attribution, retention, or reporting identity. Inspecting configuration is not proof that tracking works in a browser or that the measurement design is suitable for bidding.
## Shared inputs
| Input | Required | Default | Meaning |
| ------------- | -------------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
| `profile_id` | No | `default` | The saved Google connection to use; available on every GA4-specific tool |
| `property_id` | Required except for authentication and account discovery | None | The numeric GA4 property ID or `properties/PROPERTY_ID` |
Omitting `profile_id`, supplying `null`, or supplying a blank value selects `default`. Surrounding whitespace is removed. Profile IDs cannot contain a colon. Use the same profile for discovery and later property requests. A profile name does not extend the permissions of its Google login.
Use a property ID returned by discovery, not the account ID or a web stream’s `G-...` measurement ID. `PROPERTY_ID` below is a placeholder to replace with your discovered property.
## Authenticate Google Analytics
**Input:** optional `profile_id`; default `default`.
Returns a Google authorization link and identifies the selected profile. Open the link, choose the intended Google login, grant read-only Analytics permission, and finish the connection steps. Return to the AI client and list accounts and properties.
For a separate Agency connection:
The authorization-link response is not evidence that Google consent has finished. If access was revoked or reconnection is requested, repeat authorization for the affected profile.
## List GA4 Accounts and Properties
**Input:** optional `profile_id`; default `default`. No property ID is needed.
Returns accounts and properties visible to the connected Google login. Accounts include a name and ID. Properties include a name, ID, type, and parent account name and resource. A property count is also returned. Discovery follows the available result pages; there is no user-supplied row-limit parameter on this tool.
An empty result means no properties were returned for that identity; it does not prove the server connection failed. Confirm that the same Google login can open the property in Analytics.
## Get GA4 Property Configuration
**Inputs:** required `property_id`; optional `profile_id`.
Reads six sections:
* Property details
* Data streams
* Key events
* Google Ads links
* Custom dimensions
* Custom metrics
Each section carries its own `status` and `data`. A section can return `status: error`, an HTTP status, a message, and `data: null` while other sections succeed. An overall successful tool response therefore does not mean every configuration section was read.
Use the successful sections as evidence and resolve the failed sections before declaring a complete measurement review. There are no output-mode or CSV parameters on this tool.
## Get GA4 Reporting Metadata
Use metadata to find the actual reporting names available to the property, including custom definitions, before asking for a custom report.
| Parameter | Required | Default | Behavior |
| -------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `property_id` | Yes | None | Property to inspect |
| `search` | No | No filter | Case-insensitive substring search across API name, display name, description, and category; blank means no filter |
| `include_deprecated` | No | `false` | Whether to retain the deprecated API-name aliases in each returned entry |
| `limit` | No | `500` | Maximum entries per list: independently up to 500 dimensions and 500 metrics by default; clamped to 1–2,000 |
| `profile_id` | No | `default` | Saved Google connection |
Setting `include_deprecated` to `false` removes deprecated-name aliases from entries. It does not discard an entire field merely because it has a deprecated alias. Prefer the current API name when building requests.
The returned dimension and metric counts describe the displayed lists. A limited or filtered metadata result is not a complete inventory of everything the property can report.
## Check GA4 Report Compatibility
| Parameter | Required | Default | Behavior |
| ---------------------- | -------- | ------------ | ------------------------------------------------------------------------------------ |
| `property_id` | Yes | None | Use the same property as the intended report |
| `dimensions` | No | Empty list | Dimension API names as strings |
| `metrics` | No | Empty list | Metric API names as strings |
| `compatibility_filter` | No | `COMPATIBLE` | `COMPATIBLE`, `INCOMPATIBLE`, or `COMPATIBILITY_UNSPECIFIED`; converted to uppercase |
| `profile_id` | No | `default` | Saved Google connection |
This checks **Core reports only**, not realtime. It returns dimension and metric compatibility information. If the supplied field combination is already incompatible, the check itself can fail; reduce the field set and retry. See Google’s [compatibility guidance](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/checkCompatibility).
This tool accepts field names, not the full reporting request. It does not expose dimension-filter or metric-filter parameters and does not validate dates, filters, business interpretation, or realtime field combinations.
## Run GA4 Report
Use this for historical acquisition, page, event, and other supported Core reports. Dates, dimensions, and metrics come from your request; HireOtto does not select a default report or date window for you.
### Parameters
| Parameter | Required | Default | Limit or behavior |
| -------------------- | -------- | ----------------- | ------------------------------------------------------------- |
| `property_id` | Yes | None | Numeric ID or property resource |
| `request_json` | Yes | None | A JSON object containing the Core report request |
| `profile_id` | No | `default` | Saved Google connection |
| `max_rows` | No | `10000` | Maximum rows collected, clamped to 1–100,000 |
| `output_mode` | No | `summary_and_csv` | `summary`, `summary_and_csv`, or `csv_only` |
| `inline_limit` | No | `200` | Maximum rows included in the conversation, clamped to 1–5,000 |
| `export_limit` | No | `50000` | Maximum collected rows included in CSV, clamped to 1–100,000 |
| `export_ttl_minutes` | No | `30` | Export-link lifetime, clamped to 1–1,440 minutes |
“Clamped” means numeric values outside the range are brought to the nearest boundary. Supply valid integers deliberately; this is not a guarantee that malformed input will be accepted.
### Request fields
Use camelCase inside `request_json` and snake\_case for the tool’s outer parameters.
| Request field | Purpose |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `dateRanges` | Date windows for the report |
| `dimensions`, `metrics` | Columns, each specified with a `name` |
| `dimensionFilter`, `metricFilter` | Narrow the data using valid filter expressions |
| `orderBys` | Order results; specify this when selecting top rows or continuing a result |
| `metricAggregations` | Request supported totals, minimums, or maximums |
| `currencyCode` | Optional reporting currency; otherwise the property’s default applies |
| `keepEmptyRows` | Whether to retain recorded rows whose metrics are all zero; false if omitted |
| `comparisons`, `cohortSpec` | Advanced requests subject to Google’s rules and compatible fields |
| `offset` | Starting row, default 0; negative values are treated as 0 |
| `limit` | Optional lower cap on rows collected; cannot raise `max_rows` |
| `returnPropertyQuota` | Defaults to true when omitted; includes quota information when returned |
Supply the property through `property_id`. A `property` value inside the JSON does not override it. See Google’s [Core report request reference](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport) for field shapes and restrictions. Support for a request object does not imply support for separate pivot, funnel, audience-export, or batch-report tools.
Dates are inclusive. Standard dates can be `YYYY-MM-DD`, `NdaysAgo`, `yesterday`, or `today`; relative dates use the property’s reporting timezone. Up to four date ranges are supported. For 28 complete days, use `28daysAgo` through `yesterday`; ending at `today` includes the current partial day. See [date-range rules](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange).
### Example: acquisition over 28 complete days
The report inputs can be expressed as:
```json theme={null}
{
"property_id": "PROPERTY_ID",
"request_json": {
"dateRanges": [{"startDate": "28daysAgo", "endDate": "yesterday"}],
"dimensions": [{"name": "sessionDefaultChannelGroup"}],
"metrics": [{"name": "sessions"}, {"name": "activeUsers"}],
"orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}]
},
"output_mode": "summary_and_csv"
}
```
To compare equal periods, use one range from `28daysAgo` to `yesterday` and another from `56daysAgo` to `29daysAgo`. Keep date-range labels in the results and calculate changes from matching rows. An absent row or zero prior value is not a reliable percentage-growth calculation.
### Collection, display, and export are separate limits
The report collects up to `max_rows`, or the lower `request_json.limit` when supplied. It then displays at most `inline_limit` and exports at most `export_limit` from those collected rows.
For example, with defaults and a 60,000-row result, HireOtto collects at most 10,000 rows, shows at most 200 inline, and can export at most those 10,000 collected rows. The 50,000-row export default does not cause an additional 40,000 rows to be collected.
To request up to 60,000 rows, set both `max_rows` and `export_limit` to 60000 and remove any lower request limit. This still does not guarantee 60,000 matching rows or an unthrottled response.
### Read coverage before interpreting the result
| Response field | Meaning |
| ------------------ | ------------------------------------------------------------- |
| `row_count` | Total matching rows reported by GA4, not the inline row count |
| `returned_rows` | Rows collected for this call before output slicing |
| `offset` | Where collection started |
| `truncated` | Whether more matching rows remain after the collected segment |
| `inline_row_count` | Rows actually included in the conversation |
| `rows` | The inline rows, or an empty list in CSV-only mode |
| `metadata` | GA4 reporting metadata, when supplied |
| `property_quota` | Returned property-quota information |
`truncated: false` does not guarantee the inline preview or CSV contains every collected row. Check those output caps separately. With a nonzero offset, earlier rows are intentionally omitted even if no later rows remain.
The CSV contains flattened dimension and metric rows, not a separate metadata or totals appendix. Keep metadata and coverage notes with the exported file. Report metric values may arrive as strings; parse them numerically before calculating ratios. Do not treat the sum of a limited preview—or a sum of users across overlapping groups—as an account-wide total. Use returned report aggregates when requested and appropriate.
## Run GA4 Realtime Report
Use realtime for a recent-activity check, not a historical report or a replacement for browser-based tracking validation.
### Parameters
| Parameter | Required | Default | Limit or behavior |
| -------------------- | -------- | --------- | ------------------------------------------- |
| `property_id` | Yes | None | Numeric ID or property resource |
| `request_json` | Yes | None | A JSON object using realtime fields |
| `profile_id` | No | `default` | Saved Google connection |
| `output_mode` | No | `summary` | `summary`, `summary_and_csv`, or `csv_only` |
| `inline_limit` | No | `500` | Clamped to 1–5,000 rows |
| `export_limit` | No | `10000` | Clamped to 1–10,000 rows |
| `export_ttl_minutes` | No | `30` | Clamped to 1–1,440 minutes |
Realtime has no `max_rows` parameter and does not automatically collect subsequent result pages. Use `request_json.limit` to control the response from Google; if omitted, Google defaults to 10,000 rows. A larger response still cannot make the CSV exceed HireOtto’s 10,000-row realtime export cap.
The JSON accepts realtime `dimensions`, `metrics`, `dimensionFilter`, `metricFilter`, `limit`, `metricAggregations`, `orderBys`, `returnPropertyQuota`, and `minuteRanges`. Quota information is requested by default. The outer property ID determines the property.
### Time window and field boundaries
Without `minuteRanges`, the report uses the last 30 minutes. Standard properties can query that 30-minute window; Analytics 360 properties can query up to 60 minutes. Google allows up to two minute ranges. A range defaults to `startMinutesAgo: 29` and `endMinutesAgo: 0`. Realtime rejects `dateRanges`; use the standard report for dates. See [Google’s realtime request reference](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport).
Realtime uses a different field set from Core reporting. Examples include `country`, `deviceCategory`, `eventName`, `minutesAgo`, and `streamId`, with metrics such as `activeUsers` or `eventCount`. Registered user-scoped custom dimensions are supported; event-scoped custom dimensions and custom metrics are not. Use the [realtime field reference](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema), not a Core compatibility result, to select realtime fields.
### Example: recent events by stream
```json theme={null}
{
"property_id": "PROPERTY_ID",
"request_json": {
"dimensions": [{"name": "eventName"}, {"name": "streamId"}],
"metrics": [{"name": "eventCount"}],
"minuteRanges": [{"startMinutesAgo": 29, "endMinutesAgo": 0}],
"limit": "1000"
},
"output_mode": "summary_and_csv"
}
```
Realtime returns `row_count`, `returned_rows`, `inline_row_count`, and a window note, but no Core-style `truncated` flag. Compare the counts yourself. A realtime snapshot changes as new activity arrives and older activity leaves the window; repeated calls are not a stable historical export.
## Output modes and export failures
| Mode | Inline rows | CSV |
| ----------------- | ---------------------- | ----------------------------------------------------- |
| `summary` | Up to the inline limit | Not requested |
| `summary_and_csv` | Up to the inline limit | Requested from collected rows, up to the export limit |
| `csv_only` | None | Requested from collected rows, up to the export limit |
Summary means a compact structured result; it is not a guarantee that the AI has already interpreted the data. Ask for analysis separately when needed.
If there are no collected rows, no CSV is generated. In CSV-only mode, empty inline `rows` are expected even when a file exists. Confirm the export result and link before telling someone the download is ready. An export failure is not proof that Google returned no data. Retry with a smaller request or use summary output to inspect the report without requesting a file.
Download signed exports before expiry. Rerunning a report generates a new result, which may differ from the original. Treat export links and downloaded Analytics data as sensitive.
## Get Billing Status
This shared utility takes no parameters and reads the current HireOtto plan, billing status, period or trial dates, credits used and remaining, unlimited-credit status, and enabled features. It does not change a subscription and does not require a GA4 property ID.
Billing or access-period problems may also block this request; it is not an unconditional bypass for an inactive account. Refer to [credits and billing](/credits-and-billing) or contact HireOtto when access needs attention.
## Failures and interpretation limits
| What you see | What to check next |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| GA4 is not connected | Finish Google authorization for the selected profile, then list properties |
| Reconnect or refresh-access error | Reauthorize that Google login; do not paste credentials into chat |
| Missing property or permission error | Confirm the login can open the property directly and that the property ID is correct |
| Plan, feature, trial, or credit block | Review HireOtto access and usage; use `default` if named profiles are unavailable |
| A failed configuration section | Preserve successful sections and resolve the failed read; do not label it empty |
| Invalid or incompatible field | Inspect metadata and reduce the Core field set; use the separate realtime schema for realtime |
| Invalid JSON or output mode | Supply an object and supported parameter values, not a JSON-encoded string |
| Realtime request contains dates | Replace `dateRanges` with `minuteRanges`, or use a standard report |
| No rows | Verify property, dates, filters, and measurement coverage before concluding there was no activity |
| Fewer rows than expected | Compare matching, collected, inline, and exported row counts independently |
| Temporary quota or service failure | Reduce scope and retry after the indicated delay; unlimited HireOtto credits do not remove Google quotas |
| Missing or expired CSV | Check whether rows existed, inspect the export result, and rerun deliberately if needed |
For Core reports, inspect returned metadata for sampling, thresholding, schema restrictions, or data loss into an “other” row when those signals are present. A row cap and a privacy restriction are different problems; raising a row limit does not remove the latter. Google documents these indicators in [response metadata](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/ResponseMetaData).
Keep the business question separate from the retrieval result. A working report does not prove event quality, incremental advertising impact, or agreement with Google Ads or a CRM. State the property, dates, fields, filters, coverage limits, and any unresolved measurement questions alongside the conclusion.
## Practical review workflow
For cross-platform analysis, authorize each platform separately and keep its metrics distinct. GA4 can add on-site context to advertising or organic-search analysis; it does not turn different attribution systems into one interchangeable dataset.
## Related pages
* [GA4 authentication and quickstart](/google-analytics/quickstart)
* [Connect a HireOtto server](/setup/connect-ai-tool)
* [Feature and entitlement matrix](/feature-entitlement-matrix)
* [Credits, billing, and plans](/credits-and-billing)
* [Troubleshooting](/troubleshooting)
# Create a Google Ads Campaign with AI
Source: https://docs.hireotto.com/guides/create-a-google-ads-campaign-with-ai
Build a Google Search campaign with AI: campaign settings, budgets, ad groups, keywords, negative keywords, and responsive search ads.
***
HireOtto creates campaigns paused by default — so you can review everything before it goes live. This guide walks through creating a Search campaign end-to-end: campaign setup, ad groups, keywords, and ads.
## Step 1: Create the campaign
At minimum you need a campaign name, daily budget, location, and bidding strategy. Everything else uses sensible defaults (Google Search only, presence-based geo targeting, start date tomorrow).
**Maximise Clicks (simplest to start):**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]" with a [BUDGET]/day budget, targeting [LOCATION].
```
**Maximise Conversions:**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversions bidding.
```
**Maximise Conversions with a target CPA:**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversions with a target CPA of [TARGET_CPA].
```
**Maximise Conversion Value:**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversion Value.
```
**Maximise Conversion Value with a target ROAS:**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversion Value with a target ROAS of [TARGET_ROAS].
```
**Target Impression Share:**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Target Impression Share — top of page, 70% impression share target, max CPC [MAX_CPC].
```
**Manual CPC:**
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Manual CPC.
```
HireOtto will return the new campaign ID — making it handy for the AI for next steps.
***
## Step 2: Verify campaign settings (optional but recommended)
Before adding ad groups, confirm the campaign was set up as expected:
```text theme={null}
Show me the campaign settings for campaign [CAMPAIGN_ID].
```
Check: location targeting, network settings (Display Network should be off by default), bidding strategy, and ad serving.
If anything needs adjusting:
```text theme={null}
Turn off Search Partners for campaign [CAMPAIGN_ID].
```
```text theme={null}
Change the budget for campaign [CAMPAIGN_ID] to [NEW_BUDGET]/day.
```
***
## Step 3: Create ad groups
Add one or more tightly themed ad groups. Keep each ad group focused on a single keyword theme — this improves ad relevance and Quality Score.
```text theme={null}
Create an ad group called "[ADGROUP_NAME]" in campaign [CAMPAIGN_ID].
```
For multiple ad groups, create them one at a time in the same conversation:
```text theme={null}
Create an ad group called "[ADGROUP_NAME_1]" in campaign [CAMPAIGN_ID].
```
```text theme={null}
Create an ad group called "[ADGROUP_NAME_2]" in campaign [CAMPAIGN_ID].
```
HireOtto will return the ad group ID for each — you'll need these for the next steps.
***
## Step 4: Add keywords
Add your targeted (positive) keywords to each ad group. You can mix match types in a single prompt.
**All the same match type:**
```text theme={null}
Add these keywords to ad group [ADGROUP_ID] as exact match: [KW1], [KW2], [KW3].
```
**Mixed match types:**
```text theme={null}
Add these keywords to ad group [ADGROUP_ID]: "[KW1]" as phrase match, [KW2] as broad match, [KW3] as exact match.
```
**Tip:** If you ran keyword research first, you can reference the results from earlier in the conversation — HireOtto will use them directly. See the [Keyword research guide](/guides/keyword-research-ai).
***
## Step 5: Add negative keywords
Add negatives at the campaign level to block irrelevant queries across all ad groups.
```text theme={null}
Add "[NEGATIVE_KW1]", "[NEGATIVE_KW2]" as exact match negatives to campaign [CAMPAIGN_ID].
```
For broader exclusions (e.g. job-related terms for a B2B product), consider creating a shared negative keyword list and assigning it to the campaign — especially useful if you'll reuse the same exclusions across multiple campaigns. See the [Negative keywords guide](/guides/manage-negative-keywords-in-google-ads-with-ai).
***
## Step 6: Create responsive search ads
Add at least one RSA per ad group. Google needs 3+ headlines and 2+ descriptions to start serving.
**Character limits:** headlines ≤ 30 characters, descriptions ≤ 90 characters, display URL paths ≤ 15 characters each.
```text theme={null}
Create a responsive search ad in ad group [ADGROUP_ID]:
Headlines: [H1], [H2], [H3], [H4], [H5]
Descriptions: [D1], [D2]
Final URL: [YOUR_URL]
Display path: [PATH1] / [PATH2]
```
**With headline pinning** (e.g. to lock a brand name to position 1):
```text theme={null}
Create a responsive search ad in ad group [ADGROUP_ID]:
Headlines: pin "[BRAND_NAME]" to position 1, [H2], [H3], [H4], [H5]
Descriptions: [D1], [D2]
Final URL: [YOUR_URL]
```
**Tips for strong RSAs:**
* Include your main keyword in at least one headline
* Use all 15 headline slots if possible — Google needs variety to test
* Avoid over-pinning (it kills ad strength)
* Use the full 90 characters in descriptions
* Each description should stand alone (Google may show any combination)
Check ad strength after creation:
```text theme={null}
List all ads in campaign [CAMPAIGN_ID].
```
***
## Step 7: Enable the campaign
Once you've reviewed everything, enable the campaign:
```text theme={null}
Enable campaign [CAMPAIGN_ID].
```
***
## Full setup prompt sequence (copy-paste)
Replace all placeholders before running:
```text theme={null}
Create a Search campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversions with a target CPA of [TARGET_CPA].
```
```text theme={null}
Show me the campaign settings for campaign [CAMPAIGN_ID].
```
```text theme={null}
Create an ad group called "[ADGROUP_NAME]" in campaign [CAMPAIGN_ID].
```
```text theme={null}
Add these keywords to ad group [ADGROUP_ID] as exact match: [KW1], [KW2], [KW3].
```
```text theme={null}
Add "[NEGATIVE_KW1]", "[NEGATIVE_KW2]" as exact match negatives to campaign [CAMPAIGN_ID].
```
```text theme={null}
Create a responsive search ad in ad group [ADGROUP_ID]:
Headlines: [H1], [H2], [H3], [H4], [H5]
Descriptions: [D1], [D2]
Final URL: [YOUR_URL]
Display path: [PATH1] / [PATH2]
```
```text theme={null}
Enable campaign [CAMPAIGN_ID].
```
## Before enabling the campaign
Before you turn the campaign on, review:
* Campaign name, budget, and location targeting
* Bidding strategy
* Ad group structure
* Keyword match types
* Negative keywords
* Responsive search ad headlines and descriptions
After launch, use [Analyze Google Ads performance reports with AI](/guides/reporting) and [Daily Optimization](/guides/google-ads-daily-optimization-with-ai) to monitor performance.
# Manage Demand Gen campaigns with HireOtto
Source: https://docs.hireotto.com/guides/demand-gen
Create, inspect, and safely update non-product-feed Demand Gen campaigns from an AI client.
HireOtto can create and manage non-product-feed Demand Gen campaigns across supported YouTube, Discover, Gmail, and Display inventory. You can build the campaign shell, configure ad-group channel controls and targeting, create reusable assets, create supported ads, inspect every layer, and make controlled updates.
These are write-capable Google Ads workflows. HireOtto acts only when your connected AI client calls an action. New campaigns, ad groups, and ads default to paused so you can inspect the complete structure before enabling anything.
Demand Gen management is part of HireOtto’s core Google Ads access across current plans. Free, Starter, and Pro use plan credits; Agency includes unlimited usage. Your connected Google Ads role still determines whether you can read or change the selected account.
# Before you begin
* Connect the Google Ads server to your AI client and authorize the Google account that can access the intended customer account.
* Confirm the Google Ads customer ID. Use explicit campaign, ad-group, ad, budget, and audience IDs when updating existing entities.
* Prepare the campaign objective, budget, conversion actions, locations, audience, inventory mix, creative variants, final URLs, and review owner.
* Use a non-shared budget. Demand Gen campaigns cannot use shared budgets.
* Decide whether you are creating reusable assets or using inline image URLs and YouTube video IDs for a one-off ad.
# Understand the structure
A complete Demand Gen build has four layers:
* Campaign shell: budget, goal and bidding, dates, device eligibility, geo interpretation, schedule, tracking, and status.
* Ad group: channel controls, locations, language, audience, name, and status.
* Assets: reusable images, videos, text, and calls to action.
* Ads: single-image or multi-asset, carousel, or video-responsive creative.
Creation is not one atomic launch. Build and verify each layer before enabling the campaign.
***
## Step 1 – Create the campaign shell
## Required inputs
* Customer ID.
* Campaign name.
* Either an existing non-shared budget ID or a new budget amount.
## Defaults and campaign settings
* Status: PAUSED by default. Use ENABLED only when the user explicitly requests launch.
* Campaign goal: CONVERSIONS by default. Other supported goals are CLICKS, CONVERSION\_VALUE, and YOUTUBE\_ENGAGEMENTS.
* Bid target: optional target CPA for conversions, target ROAS for conversion value, or target CPC for clicks. If omitted, Google Ads uses the closest unconstrained strategy for the selected goal.
* Budget period: DAILY by default. CUSTOM\_PERIOD uses the supplied amount as the total campaign budget.
* Start: the next day by default when no start date is supplied. An end date is optional.
* Devices: all devices are eligible by default. You can restrict delivery to desktop, mobile, tablet, or connected TV.
* Positive location interpretation: PRESENCE by default. PRESENCE\_OR\_INTEREST is also supported. Negative location interpretation remains PRESENCE.
* EU political advertising: defaults to does not contain EU political advertising. Declare the alternative explicitly when applicable.
* Tracking template and final URL suffix: optional.
* Ad schedule: optional day and time windows in 15-minute increments.
## Goal and bidding examples
* Conversions → Maximize Conversions, with optional target CPA.
* Conversion value → Maximize Conversion Value, with optional target ROAS. Enter 3.5 for 350%.
* Clicks → Maximize Clicks, with optional target CPC.
* YouTube engagements → Maximize Engagements. Matching YouTube engagement goals must exist for the goal configuration to apply cleanly.
## Example prompt
***
## Step 2 – Add an ad group
An ad group belongs to an existing Demand Gen campaign and controls inventory, locations, language, and audience.
## Required inputs
* Customer ID, campaign ID, and ad-group name.
* Status defaults to PAUSED.
## Channel controls
* ALL\_CHANNELS: uses Google’s broad Demand Gen inventory preset.
* ALL\_OWNED\_AND\_OPERATED\_CHANNELS: uses Google-owned inventory and excludes Display expansion.
* Explicit selection: choose supported YouTube in-stream, YouTube in-feed, YouTube Shorts, Discover, Gmail, or Display inventory.
Use the broad preset when reach is the priority. Use explicit channels when the creative or placement strategy is specific. If both a preset and explicit channels are supplied, the explicit selection takes precedence. At least one supported explicit channel must be enabled.
## Targeting
* Locations and exclusions: use human-readable names; HireOtto resolves them to Google Ads locations.
* Language: English by default. Spanish, French, German, Italian, Portuguese, Japanese, Korean, Hindi, and Chinese are also supported by name or code. Leave language unset only when intentional.
* Audience: supply the full Google Ads audience resource name. The current ad-group workflow accepts one audience.
## Example prompt
***
## Step 3 – Create reusable assets when needed
Create standalone assets when the same creative will be reused across ads. For one-off ads, inline image URLs and YouTube video IDs are usually simpler.
## Supported reusable asset inputs
* Marketing image: landscape image URL.
* Square marketing image: 1:1 image URL.
* Logo image: logo image URL.
* YouTube video: video ID, not the full YouTube URL.
* Text: text value.
* Call to action: human-readable text such as Apply now, Book now, Contact us, Download, Get quote, Learn more, See more, Shop now, Sign up, Subscribe, Visit site, or Donate now.
Asset creation can succeed even if a later ad creation fails. Before retrying, inspect the returned asset resource names and reuse valid assets rather than creating duplicates.
***
## Step 4 – Create a paused ad
Every supported ad requires a customer ID, ad-group ID, ad name, ad type, and at least one final URL. The remaining required fields depend on the format.
## Single image or multi-asset
* Required: business name, at least one headline, at least one description, at least one logo, and at least one landscape or square marketing image.
* Optional: CTA text, additional headlines and descriptions, portrait, tall-portrait, and classic-display image assets.
* Pass image asset resource names or use inline URLs for logo, landscape, and square images.
## Carousel
* Required: business name, one logo, at least one headline, at least one description, and 2–10 carousel cards.
* Cards can be existing carousel-card asset resource names or created inline.
* Each inline card can include its own headline, destination, CTA, and supported image asset. If a card destination is omitted, the top-level final URL is used.
* Optional breadcrumbs control the displayed path.
## Video or video responsive
* Required: business name, at least one YouTube video, at least one logo, at least one headline, and at least one description.
* Optional: multiple videos, long headlines, CTA text, and breadcrumbs.
* When CTA text is supplied, HireOtto creates the required CTA asset as part of the workflow.
* Use human-readable CTA text—not enum-style text such as LEARN\_MORE.
## Example prompt
***
# Inspecting Demand Gen structure
Read the live structure before every update:
* Campaign settings: campaign ID, status, goal, bidding, budget, devices, geo interpretation, dates, schedule, and tracking.
* Ad-group settings: channel strategy, effective selected channels, locations, exclusions, language, audience, and status.
* Ads: ad ID, format, status, top-level destinations, and format-specific creative asset references.
Ask the AI client to repeat the customer ID, entity IDs, current values, and proposed values before applying a write.
***
# Update campaigns safely
Supported campaign-level updates include name, status, budget assignment, goal, bidding targets, dates, EU political declaration, geo interpretation, tracking, device eligibility, and schedules.
* Pass only fields you intend to change. Omitted fields remain unchanged.
* Targets can be added, changed, or explicitly removed. Changing the campaign goal may also change the bidding strategy.
* A replacement budget must be an existing non-shared budget.
* Omitting devices leaves current device targeting unchanged.
* Schedule updates use REPLACE by default: existing schedules are removed before the new list is added. Use APPEND when you intend to preserve existing windows.
## Example prompt
***
# Update ad groups safely
You can change the ad-group name, status, broad channel strategy, or explicit channel selection. Location, language, and audience changes are not part of the current ad-group update workflow; create a new structure when those need to differ.
Before changing inventory, read the current effective channels. Google may infer channel values from a broad strategy, and some UI channels may not be exposed by the connected API client.
***
# Direct ad updates versus creative replacement
## Direct update: preserve the ad ID
Use a direct ad update for the top-level final URL, mobile final URL, tracking template, final URL suffix, supported custom parameters, or status. Omitted fields remain unchanged.
* Passing an empty tracking template or suffix clears that field.
* Updating custom parameters replaces the complete existing set. Include every parameter you want to keep.
* A direct destination update does not change final URLs stored inside carousel cards.
## Creative replacement: create a new ad
Images, videos, headlines, descriptions, logos, CTA text, and carousel creative are replaced by creating a new ad. The existing creative is not mutated in place.
* Prepare the complete replacement, not only the field that changed.
* The replacement ad defaults to PAUSED unless you explicitly choose ENABLED.
* The previous ad is paused by default after replacement. Set keep old ad running only when you deliberately want both ads.
* Creative replacement is a multi-step operation. Inspect the returned result and read both ads back; do not assume new-ad creation and old-ad pausing succeeded together.
* For a controlled handoff, create the replacement paused, verify creative and policy state, then enable the new ad and confirm the previous ad is paused.
## Example prompt
***
# Common failures and recovery
* Wrong account or permissions: the connected identity can read the account but cannot write, or the customer ID belongs to another profile.
* Budget rejected: the budget does not exist, is shared, or the amount or period is invalid.
* Goal and bid mismatch: the selected target does not match the campaign goal, or the account lacks the conversion goal needed for YouTube engagements.
* Channel validation: no explicit channel is enabled, a channel name is invalid, or the current Google Ads client does not expose the requested channel.
* Location resolution: a human-readable location is ambiguous or not found. Review resolved locations before creation.
* Audience rejected: the value is not a full Google Ads audience resource name or more than one audience is supplied.
* Creative requirements: business name, logo, required text, image or video assets, final URL, or the minimum carousel-card count is missing.
* Asset or policy failure: an image cannot be fetched, an asset is invalid, or Google Ads rejects the creative or destination. Review any assets already created before retrying.
* CTA failure: enum-style CTA text or an unsupported value is supplied.
* Schedule surprise: REPLACE was used when APPEND was intended.
* Tracking loss: a custom-parameter update omitted existing parameters and replaced the complete set.
* Partial replacement: the new ad and previous-ad status do not match the intended handoff. Read both live ads and repair status explicitly.
***
# Practical workflows
## Build without launching
Create a complete Demand Gen campaign for customer \[CUSTOMER\_ID] in paused state. Stop after each layer and return the new IDs. Do not enable the campaign, ad group, or ads. At the end, list the live campaign settings, effective ad-group channels, targeting, ads, and asset references for review.
## Change inventory only
For customer \[CUSTOMER\_ID], inspect Demand Gen ad group \[AD\_GROUP\_ID]. Propose a change to YouTube Shorts and Discover only. Show current and proposed effective channels, wait for approval, apply only the channel change, and read the result back.
## Change a landing page without replacing creative
For customer \[CUSTOMER\_ID], inspect Demand Gen ad \[AD\_ID]. Change only its top-level final URL to \[NEW\_URL], preserve the ad ID and all creative, and read the final URL and tracking fields back. If the destination is stored in carousel cards, stop and explain that direct update does not cover those URLs.
## Review before enabling
Review Demand Gen campaign \[CAMPAIGN\_ID] in customer \[CUSTOMER\_ID]. Confirm the budget, goal and bidding, dates, devices, geo interpretation, schedule, ad-group channels, locations, language, audience, ad formats, required assets, destinations, and current statuses. Do not enable anything. Return blockers and an approval checklist.
***
# Pre-launch checklist
* Campaign goal matches the conversion actions and commercial objective.
* Budget is non-shared and uses the intended daily or custom-period amount.
* Dates, devices, geo interpretation, and schedule are correct.
* Ad-group locations, language, audience, and effective channels are correct.
* Creative format fits the selected inventory, including vertical video for Shorts.
* Every ad includes its required business name, logo, text, media, and destination.
* Replacement ads and previous ads have the intended statuses.
* At least one reviewed, policy-eligible ad is ready in each ad group before enabling the campaign.
***
# Related documentation
* [Connect Google Ads to an AI client](https://docs.hireotto.com/quickstart)
* [Google Ads authentication and account access](https://docs.hireotto.com/authentication-1)
* [Google Ads MCP tools reference](https://docs.hireotto.com/google-ads-mcp-tools)
* [HireOtto feature and entitlement matrix](https://docs.hireotto.com/feature-entitlement-matrix)
* [HireOtto pricing](https://hireotto.com/pricing)
* [Product changelog](https://docs.hireotto.com/changelog)
# Manage Google Ads Extension Assets with HireOtto MCP
Source: https://docs.hireotto.com/guides/extension-assets
Create, list, link, reuse, unlink, and report on Google Ads sitelinks, callouts, structured snippets, call assets, and price assets using HireOtto’s Google Ads MCP server.
These assets are reusable. You can create an asset once, link it at the account, campaign, or ad group level where supported, and reuse the same asset elsewhere without creating duplicates.
## What HireOtto supports
HireOtto currently supports:
* `SITELINK`
* `CALLOUT`
* `STRUCTURED_SNIPPET`
* `CALL`
* `PRICE`
You can:
* List existing extension assets
* Create new extension assets
* Link existing assets at the account, campaign, or ad group level
* Reuse the same asset across supported levels
* Unlink an asset association without deleting the underlying asset
* Pull extension asset performance reports
## 1. List existing extension assets
Start here if you want to reuse existing assets or find the right resource names.
```text theme={null}
List all extension assets in account [CUSTOMER_ID]. Include sitelinks, callouts, structured snippets, call assets, and price assets. Include active links.
```
HireOtto returns:
* asset ID
* asset resource name
* asset type
* asset details
* active links, if any
* campaign or ad group IDs when the asset is already linked
You will need the asset\_resource\_name when linking an existing asset.
## 2. Create a sitelink asset
```text theme={null}
Create a sitelink asset in account [CUSTOMER_ID]:
Name: Pricing Sitelink
Link text: View Pricing
Description 1: Compare plans
Description 2: Choose your fit
Final URL: https://example.com/pricing
Mobile URL: https://m.example.com/pricing
```
Optional sitelink settings include:
* tracking template
* final URL suffix
* custom parameters
* start date
* end date
* ad schedule
Example:
```text theme={null}
Create a sitelink asset in account [CUSTOMER_ID]:
Name: Pricing Sitelink
Link text: View Pricing
Description 1: Compare plans
Description 2: Choose your fit
Final URL: https://example.com/pricing
Tracking template: {lpurl}?utm_source=google&utm_medium=cpc
Final URL suffix: utm_content=sitelink
Start date: 2026-05-07
End date: 2026-05-20
Schedule: Monday and Tuesday, 9am to 5pm
```
## 3. Create callouts
```text theme={null}
Create these callout assets in account [CUSTOMER_ID]:
Free setup
No long-term contract
24/7 support
```
You can also include start/end dates and schedules:
```text theme={null}
Create a callout asset called "Free Setup Callout" in account [CUSTOMER_ID].
Text: Free setup
Start date: 2026-05-07
End date: 2026-05-20
Schedule: Monday to Friday, 9am to 5pm.
```
## 4. Create a structured snippet
```text theme={null}
Create a structured snippet asset in account [CUSTOMER_ID]:
Name: Services Snippet
Header: Services
Values: Audits, Reporting, Automation
```
## 5. Create a call asset
```text theme={null}
Create a call asset in account [CUSTOMER_ID]:
Name: Main Sales Phone
Country: US
Phone number: (800) 555-0100
Schedule: Monday to Friday, 9am to 5pm.
```
## 6. Create a price asset
```text theme={null}
Create a price asset in account [CUSTOMER_ID]:
Name: Services Price Asset
Type: Services
Qualifier: From
Language: English
Currency: USD
Offerings:
1. Audit — Account review — $49/month — https://example.com/audit
2. Reporting — Performance reports — $99/month — https://example.com/reporting
3. Automation — Workflow support — $149/month — https://example.com/automation
```
## 7. Link an existing asset
After creating or listing assets, link the asset to the right level.
### Link at campaign level
```text theme={null}
Link this sitelink asset to campaign [CAMPAIGN_ID]:
customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
### Link at ad group level
```text theme={null}
Link this structured snippet asset to ad group [ADGROUP_ID]:
customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
### Link at account level
```text theme={null}
Link this callout asset at the account level:
customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
## 8. Reuse the same asset
Reusable assets are useful when you want consistent messaging across campaigns or ad groups.
```text theme={null}
Reuse this same sitelink asset and link it to ad group [ADGROUP_ID]:
customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
HireOtto will create another association using the same underlying asset.
## 9. Unlink an asset association
Use unlink when you no longer want an asset attached at a specific level.
```text theme={null}
Unlink this campaign-level sitelink association:
customers/[CUSTOMER_ID]/campaignAssets/[CAMPAIGN_ID]~[ASSET_ID]~SITELINK
```
Important: unlinking removes the association only. It does not delete the underlying reusable asset. Google Ads may show removed associations under removed asset filters in the UI.
## 10. Check extension asset performance
Use the reporting tool to review performance.
```text theme={null}
Show extension asset performance for account [CUSTOMER_ID] over the last 30 days.
```
```text theme={null}
Show campaign-level sitelink performance for campaign [CAMPAIGN_ID] over the last 30 days.
```
```text theme={null}
Show customer-level call asset performance for account [CUSTOMER_ID] this month.
```
Newly created or newly linked assets may show zero metrics until they start serving.
## Common workflow
A typical workflow looks like this:
```text theme={null}
List existing sitelinks in account [CUSTOMER_ID].
```
Then:
```text theme={null}
Create a new sitelink for the pricing page, but do not link it yet.
```
Then:
```text theme={null}
Link that sitelink to campaign [CAMPAIGN_ID].
```
Then:
```text theme={null}
Reuse the same sitelink for ad group [ADGROUP_ID].
```
This keeps asset creation and asset linking separate, which is how Google Ads treats reusable assets behind the scenes.
## Notes and limitations
* Create and link are separate operations. If you ask HireOtto to add a new sitelink or callout to a campaign, your AI assistant may first create the asset and then link it.
* Unlinking removes only the association. The underlying asset remains reusable by asset\_resource\_name.
* Supported extension asset types in this version are SITELINK, CALLOUT, STRUCTURED\_SNIPPET, CALL, and PRICE.
* New assets may not show performance immediately. Use the listing action to confirm whether the asset is attached, and use reporting once the asset has had time to serve.
# Google Ads Account Audit with AI
Source: https://docs.hireotto.com/guides/google-ads-account-audit-with-ai
When you take on a new Google Ads account — or review an existing one — there's a standard set of checks every PPC manager runs. This guide walks through each one using HireOtto, following the same structure as a full account audit.
HireOtto surfaces the data for each check. The judgment calls (is this naming convention sensible? is this ad copy good?) are still yours.
Run these in sequence in a single conversation, passing the same `[CUSTOMER_ID]` throughout.
***
## 1. Account settings
**What to check:** Auto-tagging, auto-apply recommendations, disapproved ads.
```text theme={null}
Run an account review for [CUSTOMER_ID]. Check auto-tagging, auto-apply recommendations, and disapproved ads.
```
What to look for:
* Auto-tagging should be on. If it's off, HireOtto can turn it on — ask it to.
* Auto-apply recommendations should mostly be off. Google's defaults are aggressive. Review anything that's enabled and disable what you don't want applied automatically.
* Any disapproved ads need immediate attention — check the disapproval reasons and fix or replace.
***
## 2. Campaign settings
**What to check:** Network targeting, location targeting, language settings, ad schedule, ad rotation, device targeting.
```text theme={null}
Show me campaign settings for all active campaigns in account [CUSTOMER_ID].
```
HireOtto returns each campaign's bidding strategy, networks, geo targets, language, ad schedule, and device settings. Work through these questions for each campaign:
* Is Search Partners enabled? (Should be off)
* Is Display Network enabled? (Should be off for pure Search campaigns)
* Is location targeting set correctly — and is the location *option* set to "Presence" rather than "Presence or interest"?
* Is one language targeted per campaign?
* Is the ad schedule still relevant to the business?
* Are device bid modifiers set intentionally, or left at default?
**Note:** Naming convention and logical campaign structure are judgment calls — HireOtto can list all campaign names, but whether they follow a sensible convention is for you to assess.
***
## 3. Ad group & keyword review
**What to check:** Keyword count per ad group, negative keywords at ad group and campaign level, negative keyword lists, keyword match types, underperforming keywords.
Run these in order:
```text theme={null}
List all active keywords in account [CUSTOMER_ID]. CSV only.
```
Check: does any ad group have more than 15 keywords? Tightly themed ad groups perform better — flag any that are bloated for restructuring.
```text theme={null}
Review negative keywords for account [CUSTOMER_ID].
```
Check: are negatives present at the ad group level where needed? Are there obvious gaps (branded terms being blocked, or clear irrelevant queries not blocked)?
```text theme={null}
List all negative keyword lists in account [CUSTOMER_ID] and include the keywords in each list.
```
Check: is there a meaningful shared negative list in place, and is it assigned to the right campaigns?
```text theme={null}
Get keyword performance for account [CUSTOMER_ID] for the last 30 days, sorted by cost.
```
This single pull covers several audit questions:
* **Match type spread** — are you over-reliant on broad match? Is exact match capturing your highest-intent terms?
* **Underperforming keywords** — high spend, zero or low conversions. Candidates to pause or add as negatives.
* **Quality Score** — aim for 70%+ of keywords at QS 7 or above. Flag anything below 5 for ad copy and landing page review.
* **QS improvement areas** — HireOtto surfaces expected CTR, ad relevance, and landing page experience breakdowns where available.
For the follow-up workflow, see [Manage Negative Keywords in Google Ads with AI](/guides/manage-negative-keywords-in-google-ads-with-ai).
***
## 4. Ads review
**What to check:** RSA presence, ad copy quality, use of pinning, character utilisation.
```text theme={null}
List all ads in account [CUSTOMER_ID].
```
HireOtto returns all RSAs with their headlines, descriptions, display paths, status, and ad strength. Review for:
* At least 2–3 RSAs per ad group (Google needs variety to test)
* Keywords appearing in headlines
* Title case used consistently
* All character limits used (30 chars for headlines, 90 for descriptions, 15 for paths)
* Pinning used sparingly and intentionally — over-pinning kills ad strength
* Each ad communicating a clear benefit and CTA
Ad copy quality is a judgment call — HireOtto surfaces the content, you assess it.
***
## 5. Budget & performance review
**What to check:** Performance spread by region, device, day of week, and match type.
These four pulls give you the full picture. Run them for the same date range (last 30 days is standard for a new account audit):
```text theme={null}
Get geo performance for account [CUSTOMER_ID] for the last 30 days, sorted by cost.
```
→ Are you spending in the right regions? Are any locations burning budget with no conversions?
```text theme={null}
Get device performance for account [CUSTOMER_ID] for the last 30 days.
```
→ Where is performance strongest? Are device bid modifiers set to reflect this?
```text theme={null}
Get campaign performance for account [CUSTOMER_ID] for the last 30 days, segmented by day.
```
→ Are there day-of-week patterns? Is the ad schedule aligned with when conversions actually happen?
The keyword performance pull from step 3 also covers **match type performance** — look at how spend and conversions break down across broad, phrase, and exact.
For the full reporting workflow, see [Analyze Google Ads performance reports with AI](/guides/reporting).
***
## 6. Visibility review
**What to check:** Impression share at account level — are you visible enough?
```text theme={null}
Get impression share data for account [CUSTOMER_ID] for the last 30 days.
```
What to look for:
* **Search Impression Share** — what % of eligible impressions you're winning. Below 50% on your core campaigns is worth investigating.
* **Lost IS (Budget)** — if you're losing share due to budget, that's a scaling signal.
* **Lost IS (Rank)** — if you're losing share due to rank, look at Quality Scores and bids.
***
## Change history (optional but useful on takeovers)
If you're auditing an account you're taking over, pulling recent change history tells you what the previous manager was doing — and helps you understand why things look the way they do.
```text theme={null}
Show me the detailed change history for account [CUSTOMER_ID] over the last 30 days.
```
Look for: bid strategy changes, budget cuts, paused keywords, ad edits. This context often explains anomalies you'd otherwise spend time investigating.
***
## Full audit prompt sequence (copy-paste)
Run these in a single conversation, replacing `[CUSTOMER_ID]` and `[DATE_RANGE]` throughout:
```text theme={null}
Run an account review for [CUSTOMER_ID]. Check auto-tagging, auto-apply recommendations, and disapproved ads.
```
```text theme={null}
Show me campaign settings for all campaigns in account [CUSTOMER_ID].
```
```text theme={null}
List all active keywords in account [CUSTOMER_ID]. CSV only.
```
```text theme={null}
Review negative keywords for account [CUSTOMER_ID].
```
```text theme={null}
List all negative keyword lists in account [CUSTOMER_ID] and include the keywords in each list.
```
```text theme={null}
Get keyword performance for account [CUSTOMER_ID] for the last 30 days, sorted by cost.
```
```text theme={null}
List all ads in account [CUSTOMER_ID].
```
```text theme={null}
Get geo performance for account [CUSTOMER_ID] for the last 30 days, sorted by cost.
```
```text theme={null}
Get device performance for account [CUSTOMER_ID] for the last 30 days.
```
```text theme={null}
Get campaign performance for account [CUSTOMER_ID] for the last 30 days, segmented by day.
```
```text theme={null}
Get impression share data for account [CUSTOMER_ID] for the last 30 days.
```
# Run a Google Ads account health audit with HireOtto
Source: https://docs.hireotto.com/guides/google-ads-account-health-audit
Review account structure, settings, measurement signals, and coverage in one read-only workflow.
# What this audit does
HireOtto’s account health audit gives you a monthly or quarterly structural review of a connected Google Ads account. It checks configuration, campaign structure, keyword and Quality Score patterns, negative-keyword coverage, geographic and device performance, Search visibility, and – when requested – responsive search ad structure.
The audit is read-only. It does not change campaigns, budgets, keywords, ads, targeting, or conversion settings. It is available on the Agency plan.
By default, HireOtto reviews the last 90 days and compares them with the preceding 90 days. It returns prioritized findings, passed checks, coverage notes, and downloadable CSV exports. Optional RSA review and checklist modes are off by default.
Use this audit when you need to understand whether the account is structurally sound – not when you need a short-term optimization queue. For weekly performance decisions, use the weekly optimization audit instead.
# Before you begin
* An active HireOtto Agency plan.
* A connected Google Ads profile and access to the account you want to review.
* The Google Ads customer ID. You can enter it with or without hyphens.
* Enough recent activity to interpret performance and Quality Score patterns. Low-volume accounts can return valid but limited evidence.
# Run a default account health audit
Ask your connected AI client:
The default audit uses the last 90 days, compares them with the previous equal period, reviews up to 5,000 enabled keyword rows, returns up to 100 findings inline, and keeps export links available for 30 minutes.
# What HireOtto checks
## Tracking and campaign settings
* Auto-tagging status.
* Enabled campaign settings, including network configuration, positive location matching, languages, schedules, and other available settings.
* Configuration patterns that deserve review, such as a Search campaign targeting the Display Network or a broader-than-presence positive location option.
* Multiple languages are reported as a review signal, not an automatic error.
## Performance and account structure
* Campaign performance for the current and comparison periods.
* Enabled-keyword counts by ad group and match-type performance.
* Ad groups with more than 15 enabled keywords may be flagged for review. This is a heuristic, not a universal failure.
* Quality Score coverage and component distributions. When at least 10 enabled keywords have a score, the audit flags an account where fewer than 70% score above 7.
## Negative-keyword coverage
* Counts of campaign-level and ad-group-level negative keywords.
* A finding when no campaign or ad-group negatives are present.
* This check does not prove that a negative-keyword strategy is complete. Review current search terms and shared negative lists before adding exclusions.
## Geography, devices, and Search visibility
* Geographic and device performance for enabled campaigns.
* Search impression share and impression share lost to budget or rank when Google Ads supplies those metrics.
* A medium-priority budget visibility finding when Search impression share lost to budget is at least 30%. Treat it as a prompt to review economics and constraints—not as an instruction to raise budgets.
## Optional responsive search ad review
Turn on RSA review when you want structural evidence about enabled responsive search ads. It is off by default because it adds a heavier account read.
The review can flag an RSA with fewer than eight headlines or three descriptions, and it reports pinned assets. These are review signals. Pinning may be intentional, and asset count alone does not establish creative quality.
## Optional audit checklist
Turn on the checklist when you want the audit evidence organized into a reusable review list. The checklist does not make extra Google Ads requests; it reuses evidence already collected by the audit.
* Checklist answers have three forms:
* Computed: HireOtto can answer directly from account data.
* Needs interpretation: your AI client can interpret only the evidence included with the item.
* Needs user input: a business or account owner must confirm the answer.
Evidence in checklist items is capped for readability. Use the raw exports when you need the complete available row set.
# Parameters and defaults
* Customer ID: required; hyphens are optional.
* Audit period: last 90 days by default. You can request another supported preset, a LAST\_N\_DAYS period from 1 to 365 days, or supported custom dates.
* Comparison period: the preceding equal-length period by default. You can supply a different supported preset or custom period.
* Include RSA review: false by default.
* Include checklist: false by default.
* Maximum keyword rows: 5,000 by default; allowed range 100–20,000.
* Maximum ad rows: 1,000 by default; allowed range 100–5,000. This applies only when RSA review is enabled.
* Findings shown inline: 100 by default; allowed range 1–300.
* Export-link lifetime: 30 minutes by default; allowed range 1–1,440 minutes.
# How to read the result
* Start with execution status and coverage. A complete audit means all requested sections ran; a partial audit means at least one section failed, was unavailable, or was truncated.
* Review all high- and medium-priority findings first. Low-priority findings are usually heuristics or context-dependent review prompts.
* Read passed checks as evidence of what was examined, not proof that every possible account issue was ruled out.
* Keep HireOtto’s generated findings separate from any additional interpretation supplied by your AI client.
* Check row and finding limits. A valid result can still be partial when a large account exceeds the selected limits.
* Open every relevant export before it expires.
Available exports can include keywords, campaign settings, geographic performance, device performance, Search visibility, and – when enabled and available – ad copy.
# Safe follow-through
The account health audit never writes to Google Ads. If a finding merits action, handle the change in a separate, approval-gated request:
* Read the current value and identify the exact account, campaign, ad group, keyword, ad, or budget.
* State the proposed value and affected scope.
* Check the finding against business context, conversion lag, sample size, and account constraints.
* Ask for approval before making a consequential change.
* Apply one class of changes at a time.
* Read the live setting back after the write.
A finding is evidence for a decision. It is not an instruction to change the account automatically.
# Practical prompts
## Monthly structural review
## Quarterly takeover review
## Large account with longer-lived exports
## Custom comparison
## Decision queue
# Limits and common failures
* Plan restriction: the account health audit is available only on the Agency plan.
* Read-only scope: the audit does not change Google Ads. Any follow-up write requires a separate supported action, adequate Google Ads permissions, and your approval.
* External context: the audit cannot see CRM pipeline impact, competitor activity, landing-page experiments, quarterly business goals, or other data you have not supplied.
* Semantic judgment: naming conventions, ad-group themes, negative-keyword strength, and some schedule decisions require interpretation or owner input.
* Partial coverage: API errors, permissions, quotas, unavailable metrics, or selected row limits can leave a section incomplete. Read the execution status and coverage notes before calling the audit complete.
* Large accounts: increasing keyword and ad limits makes the request heavier. Enable RSA review only when you need it.
* Low-volume accounts: a missing finding can mean there was not enough eligible data, not that the account passed every check.
* Quality Score: the distribution check applies only when at least 10 enabled keywords have scores. Keywords without scores are not treated as passing.
* Visibility: impression-share metrics are available only when Google Ads returns them. Lost visibility does not establish that spending more will be profitable.
* Expired exports: CSV links stop working after the selected lifetime. Run the audit again if you need fresh links.
* Access errors: confirm that the correct HireOtto profile and Google Ads identity are connected and that the identity can access the requested customer ID.
# Choose the right audit
* Daily operations audit: use for near-term operational checks and urgent issues.
* Weekly optimization audit: use for recent performance, search-term, keyword, bid, disapproval, and RSA decision queues.
* Account health audit: use monthly, quarterly, during onboarding, or after a major restructure to review settings, structure, quality, coverage, and Search visibility.
* Manual account audit guide: use when you want to assemble a custom review from separate prompts and reports.
# Related documentation
* [Google Ads quickstart](https://docs.hireotto.com/quickstart)
* [Authentication and account access](https://docs.hireotto.com/authentication-1)
* [Google Ads MCP tools reference](https://docs.hireotto.com/google-ads-mcp-tools)
* [Google Ads account audit with AI](https://docs.hireotto.com/guides/google-ads-account-audit-with-ai)
* [Output modes and CSV exports](https://docs.hireotto.com/output-modes)
* [HireOtto pricing](https://hireotto.com/pricing)
* [Product changelog](https://docs.hireotto.com/changelog)
# Daily Google Ads Optimization with AI
Source: https://docs.hireotto.com/guides/google-ads-daily-optimization-with-ai
Run a daily Google Ads audit to catch budget pacing issues and wasted search term spend, then adjust budgets or add negatives from the same chat.
***
A good daily Google Ads routine catches two things: budget pacing issues (campaigns over- or underspending) and wasted search term spend (queries converting at zero). HireOtto combines both into a single audit you can run every morning, then act on directly in the same conversation.
## The daily ops audit
Run this every morning, ideally against yesterday's data:
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID].
```
This returns two things:
1. **Pacing flags** — campaigns that overspent or underspent yesterday relative to their daily budget. Defaults: flagged if over 150% or under 50% of daily budget.
2. **Wasteful search terms** — queries with zero conversions, sorted by cost. The top 25 are shown inline; the full list exports to CSV.
***
## Adjusting the pacing thresholds
The defaults (150% overspend, 50% underspend) work for most accounts. If you want tighter or looser flagging:
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID] — flag campaigns over 130% spend or under 60%.
```
***
## Exporting the wasteful search terms
The inline view shows the top 25 wasted terms. For the full list (useful for large accounts or when you want to review everything in a spreadsheet):
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID] and export the full wasteful search terms list to CSV.
```
***
## Acting on the audit output
The audit flags issues — it doesn't fix them automatically. But you can act on everything in the same conversation.
**Budget pacing:**
If a campaign overspent significantly:
```text theme={null}
Reduce the budget for campaign [CAMPAIGN_ID] to [NEW_BUDGET]/day.
```
If a campaign underspent consistently and it matters:
```text theme={null}
Increase the budget for campaign [CAMPAIGN_ID] to [NEW_BUDGET]/day.
```
**Wasteful search terms:**
Add the wasted terms as negatives directly from the audit output:
```text theme={null}
Add these as exact match negatives to campaign [CAMPAIGN_ID]: "[WASTED_TERM_1]", "[WASTED_TERM_2]", "[WASTED_TERM_3]".
```
For terms that should be excluded across all campaigns, add them to your shared negative list:
```text theme={null}
Add "[WASTED_TERM]" to negative keyword list [LIST_ID] — exact match.
```
***
## Running across multiple accounts
If you manage several accounts, run the audit for each in sequence in the same conversation:
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID_1].
```
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID_2].
```
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID_3].
```
For large-scale agency use where you want everything exported without inline output:
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID] — csv_only, full search terms export.
```
***
## Custom date ranges
The audit defaults to yesterday. To run it over a longer window (e.g. catching a weekend):
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID] for the last 3 days.
```
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID] for this week.
```
***
## Full daily routine sequence (copy-paste)
```text theme={null}
Run the daily ops audit for account [CUSTOMER_ID].
```
Review pacing flags → adjust any budgets that need it:
```text theme={null}
Change the budget for campaign [CAMPAIGN_ID] to [NEW_BUDGET]/day.
```
Review wasteful search terms → add negatives:
```text theme={null}
Add these as exact match negatives to campaign [CAMPAIGN_ID]: "[TERM_1]", "[TERM_2]".
```
Done. The whole routine — audit, budget fix, negatives — typically takes under 5 minutes in a single conversation.
## Weekly follow-up
At the end of the week, pull a fuller performance report using [Analyze Google Ads performance reports with AI](/guides/reporting). If you manage PMax campaigns, also review [Performance Max reporting](/guides/manage-performance-max-campaigns).
# Analyze Search Console performance and URL indexing with HireOtto
Source: https://docs.hireotto.com/guides/google-search-console
Turn Google Search Console data into organic-search decisions, inspect Google's indexed version of important URLs, and export review-ready evidence from your AI client.
Use HireOtto to answer two practical Search Console questions from your AI client:
1. Which queries and pages deserve action?
2. What does Google currently know about an important URL?
HireOtto can retrieve clicks, impressions, CTR, and average position; break results down by query, page, country, device, date, hour, or search appearance; export up to 25,000 rows; list submitted sitemaps; and inspect Google's indexed version of a URL.
Search Console access is read-only. HireOtto cannot change a property, submit or remove a sitemap, request indexing, run a live URL test, edit a canonical, or change your website.
## Before you start
You need:
* HireOtto connected to an MCP-capable AI client
* Search Console authorized separately through HireOtto
* A Google login that can access the property you want to review
* The exact Search Console property value, such as `sc-domain:example.com` or `https://www.example.com/`
Search Console tools currently use HireOtto's Google Ads MCP endpoint:
```text theme={null}
https://googleads.hireotto.com/mcp
```
Connecting that endpoint does not authorize Search Console automatically. Follow the [Search Console quickstart](/search-console/quickstart) if you have not completed the separate Google permission flow.
Copy the returned `site_url` exactly. A domain property looks like `sc-domain:example.com`. A URL-prefix property looks like `https://www.example.com/`; its protocol, subdomain, and trailing slash matter.
Search Console is available on HireOtto Free, Starter, Pro, and Agency. The default connection uses the `default` profile. Current public plan guidance reserves additional named profiles for Agency.
## Choose the right workflow
| Job | Use | What it returns |
| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------- |
| Find organic opportunities | Search performance | Clicks, impressions, CTR, and average position grouped by the dimensions you choose |
| Diagnose a specific page | URL inspection | Google's indexed verdict, coverage state, crawl and fetch details, and canonical information |
| Confirm property coverage | Property list | Exact property values and permission levels available to the connected Google login |
| Review sitemap records | Sitemap list | Sitemaps submitted for the selected property and the fields returned by Google |
Use performance data to identify where to investigate. Use URL inspection to check Google's indexed information for a specific page. Neither result, by itself, proves what is happening in the browser right now or what caused a performance change.
## Workflow 1: Turn Search performance into decisions
### 1. Define the question before the dimensions
Start with the decision you need to make. Then request only the dimensions required to answer it.
| Question | Useful dimensions | What to review |
| ------------------------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| Which queries are gaining or losing demand? | `query`, then `date` if a trend is needed | Clicks, impressions, CTR, position, intent, and volume |
| Which landing pages need attention? | `page` | Visibility, clicks, CTR, position, and page purpose |
| Is performance different by market? | `country` plus `query` or `page` | Market-specific demand and landing-page fit |
| Is mobile behaving differently? | `device` plus `query` or `page` | Device-specific visibility and CTR |
| Which search-result features appear? | `searchAppearance` | Values actually present for the property |
Adding dimensions makes the result more granular. It can also fragment the data and increase Search Console query load. Begin with one or two dimensions, then drill into the rows that matter.
### 2. Use a completed date range
For routine analysis, use finalized data and end the range at yesterday or earlier. Search Console interprets `start_date` and `end_date` in Pacific Time, and both dates are inclusive.
Use fresh data only when the most recent activity matters more than completeness. Hourly reporting requires the `hour` dimension and hourly data. Treat fresh and hourly results as directional because recent data can be incomplete.
### 3. Filter deliberately
Search Console filters are combined with AND logic. Supported filter dimensions are `country`, `device`, `page`, `query`, and `searchAppearance`.
Supported operators are:
* `equals`
* `contains`
* `notEquals`
* `notContains`
* `includingRegex`
* `excludingRegex`
Country filters use three-letter country codes such as `USA`, `IND`, and `GBR`. Device values are `DESKTOP`, `MOBILE`, and `TABLET`. Regex filters use RE2 syntax.
Do not infer that a missing row has zero demand. Search Console may omit anonymized queries, and the API returns top rows rather than guaranteeing every possible row.
### 4. Keep output appropriate to the job
| Parameter | Default | Accepted value or range | Use it for |
| -------------------- | ----------------- | ---------------------------------------- | -------------------------------------------------- |
| `output_mode` | `summary_and_csv` | `summary`, `summary_and_csv`, `csv_only` | Choose inline rows, an export, or both |
| `limit` | `50` | `1` to `5,000` | Control rows shown inline |
| `export_limit` | `25,000` | `1` to `25,000` | Control rows retrieved for CSV |
| `export_ttl_minutes` | `30` | `1` to `1,440` | Set how long the signed CSV link remains available |
Use `summary` for a quick review, `summary_and_csv` for most analysis, and `csv_only` when the export is the deliverable. No CSV is created when the report returns zero rows. Download signed exports before they expire; rerun the report if a link has expired.
HireOtto makes one Search Console request per performance call and does not currently paginate beyond the first 25,000 rows. A CSV export is therefore a larger slice of the available top rows, not a promise of complete Search Console data.
### 5. Separate evidence from interpretation
Search Console returns:
* Clicks
* Impressions
* CTR as a decimal from `0` to `1`
* Average position
Rows are generally sorted by clicks in descending order. A report grouped by date is returned chronologically.
Use the metrics as evidence, then add the commercial and editorial context Search Console does not contain:
* What the page is meant to do
* Whether the query is branded, commercial, navigational, or informational
* Whether the page changed during the period
* Whether seasonality, a launch, or a migration affected the comparison
* Whether the site has another page serving the same intent
Do not treat average position as a fixed rank for every searcher. Do not treat high impressions and low CTR as an automatic title-tag rewrite. First check query intent, page relevance, search appearance, brand presence, and the size of the evidence.
## Compare two periods safely
Run the same property, search type, dimensions, filters, and aggregation for both periods. Use complete, equal-length periods and keep the raw values next to percentage changes. If a page launched midway through one period, or the comparison crosses a seasonal event, label that structural difference.
If the AI client runs two separate reports, verify that both used the same `site_url`, dimensions, filters, search type, and date conventions before accepting the comparison.
## Workflow 2: Inspect Google's indexed version of a URL
Use URL inspection after performance analysis identifies an important page, or when a new, updated, or business-critical URL needs an index-status check.
### 1. Select the correct property
The full `inspection_url` must belong to the selected `site_url`. A domain property can cover protocols and subdomains for the domain. A URL-prefix property covers only its exact prefix.
### 2. Ask for the fields that support a diagnosis
HireOtto can return:
* Verdict and coverage state
* Robots.txt and indexing states
* Page-fetch state
* Last crawl time
* Google-selected canonical
* User-declared canonical
* Additional URL Inspection details returned by Google
URL Inspection reports the version currently known in Google's index. It cannot test the live URL, request indexing, recrawl the page, or change robots and canonical settings.
### 3. Complete the diagnosis outside the indexed report
An indexed-URL result is one layer of evidence. When a page looks wrong or stale, also check:
1. The live HTTP response and redirects
2. The rendered page and canonical tag
3. Robots directives and robots.txt
4. Internal links and sitemap inclusion
5. Recent deployments, migrations, or URL changes
6. Search Console's live inspection tools when a live test is required
Label the conclusion carefully:
* **Confirmed:** directly reported for Google's indexed version
* **Likely:** supported by the indexed result and another source
* **Needs live validation:** cannot be established from the indexed result alone
## Review submitted sitemaps
HireOtto can list sitemaps submitted for a Search Console property. It does not submit, remove, edit, fetch, or validate sitemap XML on the live website.
If a sitemap is missing from the list, check whether you selected the correct property and Google login before concluding that it was never submitted.
## Cross-platform workflow: paid and organic search
Search Console and Google Ads describe different systems. Search Console reports organic visibility and clicks. Google Ads reports paid delivery, cost, and tracked conversions. Keep each dataset intact, align the date range, market, device, and query treatment, then compare them at the decision layer.
Use the output to form hypotheses, not automatic budget decisions. Organic visibility does not prove paid search is non-incremental, and a paid-only query does not prove that a new SEO page should be created.
## Parameters and defaults
### Search performance
| Parameter | Required | Default | Accepted value or range |
| ------------------------- | -------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `site_url` | Yes | — | Exact property value returned by the property list |
| `start_date` | Yes | — | Inclusive date in `YYYY-MM-DD` format, interpreted in Pacific Time |
| `end_date` | Yes | — | Inclusive date in `YYYY-MM-DD` format, interpreted in Pacific Time |
| `dimensions` | No | `["query"]` | Any supported combination of `query`, `page`, `country`, `device`, `date`, `hour`, `searchAppearance` |
| `search_type` | No | `web` | `web`, `image`, `video`, `news`, `discover`, `googleNews` |
| `dimension_filter_groups` | No | None | A JSON string, one filter-group object, or an array of filter-group objects |
| `aggregation_type` | No | Search Console default | `auto`, `byPage`, `byProperty`, or the conditional News Showcase option |
| `data_state` | No | `final` behavior | `final`, `all`, `hourly_all` |
| `output_mode` | No | `summary_and_csv` | `summary`, `summary_and_csv`, `csv_only` |
| `limit` | No | `50` | `1` to `5,000` inline rows |
| `export_limit` | No | `25,000` | `1` to `25,000` export rows |
| `export_ttl_minutes` | No | `30` | `1` to `1,440` minutes |
| `profile_id` | No | `default` | `default` or an eligible named profile |
Leave `aggregation_type` unset unless you need a specific calculation. Do not use `byProperty` when grouping or filtering by page. `byProperty` is also unavailable for Discover and Google News reports.
### URL inspection and resources
| Parameter | Required | Default | Accepted value |
| ---------------- | ----------- | --------- | ------------------------------------------------- |
| `action` | Yes | — | `list_sites`, `list_sitemaps`, `inspect_url` |
| `site_url` | Conditional | — | Required for sitemaps and URL inspection |
| `inspection_url` | Conditional | — | Full URL required for URL inspection |
| `language_code` | No | `en-US` | Supported BCP 47 language code for issue messages |
| `profile_id` | No | `default` | `default` or an eligible named profile |
See the [Search Console MCP tools reference](/search-console/tools-reference) for tool-by-tool details and request shapes.
## Access, credits, and limits
* Search Console is available now on Free, Starter, Pro, and Agency.
* Search Console access is read-only.
* Each successful property, sitemap, URL-inspection, or performance request uses 5 HireOtto credits. Agency includes unlimited credits.
* Authentication starts the permission flow but does not retrieve Search Console data.
* The default Google connection is `default`; current public plan guidance reserves additional named profiles for Agency.
* Inline output is limited to 5,000 rows per performance request.
* CSV output is limited to 25,000 rows per performance request.
* Signed CSV links default to 30 minutes and can be set from 1 minute to 24 hours.
* Google may return fewer rows than requested and does not guarantee every possible row.
* Search Analytics and URL Inspection have separate Google quotas.
* Large date ranges and queries grouped or filtered by both page and query consume more Search Console load.
## Common failures
### Search Console is not connected
Complete the separate Search Console authorization. A working HireOtto or Google Ads connection does not grant Search Console access.
### No properties appear
Confirm that the same Google login can open the property directly in Search Console. Successful authorization proves which identity was connected; it does not prove that the identity has property access.
### The property or URL is rejected
List properties again and copy the exact `site_url`. For a URL-prefix property, confirm the protocol, subdomain, and trailing slash. For URL inspection, confirm that the full URL belongs to the selected property.
### A named profile is blocked
Use the default profile or confirm that the account includes multiple-profile access. Current public plan guidance reserves additional profiles for Agency.
### A report returns no rows
Check the property, date range, search type, dimensions, filters, and selected profile. An empty result can mean there is no matching data, the filter is too narrow, recent data is not finalized, or the selected login cannot access the intended property.
### A parameter combination fails
Check for an unsupported dimension or search type, an invalid date, a filter with the wrong shape, or an incompatible aggregation. Avoid `byProperty` when a page dimension or page filter is present.
### A quota error appears
Wait before retrying. Then shorten the date range, remove unnecessary page or query grouping and filtering, and avoid repeatedly requesting the same large dataset.
### The CSV link expired
Rerun the report and download the new file before its expiry time.
### The result differs from the Search Console interface
Align the property, search type, dates, dimensions, filters, and aggregation. Search Console may omit anonymized or lower-volume rows, and its API returns top rows rather than guaranteeing a complete table.
## Practical checklist
Before acting on a Search Console finding:
* Confirm the Google login and exact property
* Use complete dates unless recent data is intentionally required
* Keep dimensions and filters tied to the question
* Preserve raw clicks, impressions, CTR, and position
* Check sample size before interpreting a rate
* Inspect important URLs under the correct property
* Treat indexed information separately from live-page behavior
* Bring in content, conversion, and commercial context
* Keep Google Ads metrics separate in cross-platform analysis
* Record what is confirmed, likely, and still unverified
## Related pages
* [Connect Google Search Console](/search-console/quickstart)
* [Search Console MCP tools reference](/search-console/tools-reference)
* [Connect a HireOtto server](/setup/connect-ai-tool)
* [HireOtto plans and credits](/credits-and-billing)
* [Troubleshoot HireOtto](/troubleshooting)
* [Search Console product page](https://hireotto.com/search-console-mcp)
## Sources
* [HireOtto Search Console product page](https://hireotto.com/search-console-mcp)
* [HireOtto pricing](https://hireotto.com/pricing)
* [Google Search Analytics query reference](https://developers.google.com/webmaster-tools/v1/searchanalytics/query)
* [Google URL Inspection API reference](https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect)
* [Google Search Console API usage limits](https://developers.google.com/webmaster-tools/limits)
# Google Ads Keyword Research with AI
Source: https://docs.hireotto.com/guides/keyword-research-ai
Generate keyword ideas, get search volume, check competition, review CPC ranges, and export Google Keyword Planner data using HireOtto.
***
HireOtto connects directly to the Google Keyword Planner API — the same data source the Google Ads UI uses, without the extra clicks. You can generate new keyword ideas from seed terms or a URL, score a list of keywords you already have, or do both in a single conversation.
## Two modes: ideas vs. metrics
**Keyword ideas** — you give HireOtto seed keywords or a landing page URL, and it returns an expanded list of related keywords with search volume, competition, and CPC ranges. Use this when you're building a new campaign or exploring a new topic.
**Historical metrics** — you give HireOtto a list of specific keywords you already have, and it returns search volume, competition, and bid data for exactly those terms. No expansion. Use this to score and prioritise a keyword list you've already built.
***
## Generating keyword ideas
**From seed keywords:**
```text theme={null}
Generate keyword ideas for [SEED_KEYWORD_1], [SEED_KEYWORD_2] — target [LOCATION].
```
**From a URL:**
```text theme={null}
Generate keyword ideas from this URL: [YOUR_URL] — target [LOCATION].
```
**Combining seeds and a URL:**
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" and this page: [YOUR_URL] — target United States.
```
**Options you can add:**
Filter by competition level to focus on winnable terms:
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — target US, low competition only, minimum 500 monthly searches.
```
Sort by a different metric:
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — sort by competition (ascending), target UK.
```
Get more results than the default (25):
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — return top 50 results, target US.
```
Export for further analysis:
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — target US, export to CSV.
```
***
## Getting historical metrics for a known list
Use this when you already have keywords and want to score them before adding to a campaign.
```text theme={null}
Get historical metrics for these keywords: [KW1], [KW2], [KW3] — target [LOCATION].
```
**Tip:** If you're passing more than 25 keywords, tell HireOtto to increase the limit — otherwise results will be cut off:
```text theme={null}
Get historical metrics for these 40 keywords: [LIST] — target US, show all results.
```
***
## Targeting multiple locations
By default results are aggregated across all locations you specify. If you want separate results per location (e.g. to compare US vs UK volume), ask for per-location mode:
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — show results separately for US, UK, and Australia.
```
```text theme={null}
Get historical metrics for [KW1], [KW2] — per location: United States, Canada, India.
```
***
## Language targeting
Default is English. To target a different language:
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — target Germany, language German.
```
***
## Including Google Search Partners
By default, results reflect Google Search only. To include Search Partners in the network:
```text theme={null}
Generate keyword ideas for "[SEED_KEYWORD]" — target US, include Search Partners.
```
***
## Typical keyword research workflow
A full research session for a new campaign might look like this:
**Step 1 — Explore and expand:**
```text theme={null}
Generate keyword ideas for "[CORE_TOPIC]" — target [LOCATION], minimum 200 monthly searches, show top 50.
```
**Step 2 — Score your shortlist:**
```text theme={null}
Get historical metrics for these keywords: [SHORTLISTED_KWs] — target [LOCATION].
```
**Step 3 — Export for the campaign:**
```text theme={null}
Export the keyword ideas to CSV.
```
## Next step: build the campaign
Once you have a keyword list, use [How to Create a Google Ads Campaign with AI](/guides/create-a-google-ads-campaign-with-ai) to turn those keywords into ad groups, match types, responsive search ads, and a paused Search campaign you can review before launch.
# Manage shared budgets and portfolio bidding strategies
Source: https://docs.hireotto.com/guides/manage-budgets-portfolio-bidding
Inspect, create, align, attach, split, and safely clean up Google Ads shared budgets and portfolio bidding strategies with HireOtto.
Use HireOtto to manage the account-level budget and bidding objects that several Google Ads campaigns can share. You can inspect every relationship first, apply an approved change, and verify the saved campaign settings without switching between multiple Google Ads screens.
This guide covers two related resources:
* A **shared budget** sets one average daily budget across multiple eligible campaigns.
* A **portfolio bidding strategy** applies one automated bidding strategy across multiple eligible campaigns.
They are independent by default. Google Ads can also explicitly align a shared budget with a portfolio strategy. When that relationship exists, update the budget and bidding assignment together so the campaign never passes through an invalid intermediate state.
HireOtto can read and change supported Google Ads budget and bidding settings. It does not decide how much you should spend or which bidding target is commercially appropriate. Review the affected campaigns, current values, proposed values, and expected scope before approving a write.
## Before you begin
You need:
* The HireOtto Google Ads MCP server connected at `https://googleads.hireotto.com/mcp`.
* A Google Ads login with access to the customer account.
* Sufficient Google Ads permissions for any create, update, assignment, alignment, or removal action.
* The customer ID, campaign IDs, budget IDs, and bidding strategy IDs involved in the change.
Use the customer ID without hyphens when a tool asks for `customer_id`.
These workflows are live core Google Ads tools on Free, Starter, Pro, and Agency. Free, Starter, and Pro use plan credits; Agency includes unlimited credits. Multiple connected Google profiles are available on Agency. A listing action costs 1 credit and a write action costs 2 credits.
Start with an inventory instead of guessing from names:
## Choose the right operation
| Your job | Preferred workflow |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Change how much an existing campaign or shared group can spend | Update the current budget amount. |
| Give several campaigns one spending pool | Create or identify an explicitly shared daily budget, then attach the campaigns. |
| Give one campaign its own budget | Create and attach a new non-shared daily budget. |
| Apply one bidding strategy across campaigns | Create or identify a portfolio strategy, then attach eligible campaigns. |
| Use a shared budget and portfolio strategy as an aligned pair | Ensure both resources cover the same campaign set, link them, then attach campaigns to both together. |
| Split one campaign out of an aligned shared setup | Create a dedicated budget and set standard campaign-level bidding in one atomic operation. |
| Clean up an unused resource | Confirm that no campaigns use it, then remove it explicitly. |
Replacing a campaign's budget can change spend and overdelivery behavior because the new budget has different history and associations. If your only goal is to change spend, update the current budget amount instead.
## Campaign budget parameters and defaults
HireOtto exposes budget workflows through `manage_campaign_budgets`.
| Parameter | Required | Default | Use |
| --------------------------- | ---------------------------------------------: | -------------------------------------------- | -------------------------------------------------------------------------------------- |
| `action` | Yes | — | Choose the budget operation. |
| `customer_id` | Yes | — | Google Ads customer ID, without hyphens. |
| `campaign_id` | For attach actions | — | Campaign to move to a budget. |
| `budget_id` | For usage, update, attach, and removal actions | — | Existing budget ID. |
| `amount` | For daily-budget creation; optional on update | — | Average daily amount in the account currency. |
| `name` | For standalone creation | Generated for create-and-attach when omitted | Budget name. |
| `explicitly_shared` | No | `false` when creating | `true` creates a shared budget; `false` creates a standalone budget. |
| `period` | No | `DAILY` | `DAILY` or `CUSTOM_PERIOD` for standalone creation. |
| `total_amount` | For a custom-period total budget | — | Total amount for the campaign duration, in account currency. |
| `include_campaigns` | No | `true` | Include campaigns in a budget inventory. |
| `include_budget` | No | `true` | Include budget metadata when listing campaigns that use one budget. |
| `allow_removal_if_assigned` | No | `false` | Safety override for removal. Leave false unless the user explicitly approves the risk. |
Supported budget actions:
| Action | Scope |
| ----------------------------------- | ----- |
| `list_campaign_budgets` | Read |
| `list_campaigns_using_budget` | Read |
| `create_campaign_budget` | Write |
| `update_campaign_budget` | Write |
| `attach_campaign_budget` | Write |
| `create_and_attach_campaign_budget` | Write |
| `remove_campaign_budget` | Write |
### Create and use a shared budget
A shared budget must use the `DAILY` period. Creating the budget does not attach campaigns automatically.
After creation, review the eligible campaigns and attach them one at a time unless you have an aligned budget–portfolio setup.
### Split a campaign into a dedicated budget
For a campaign that is not in an explicitly aligned budget–portfolio setup, create and attach a new non-shared daily budget in one operation.
### Update a budget
An update can change the daily amount, make an eligible non-shared budget explicitly shared, or do both. Budget names are not editable through this workflow.
Once a budget is explicitly shared, Google Ads does not allow it to become non-shared again. To isolate one campaign, move that campaign to a new dedicated budget instead.
## Portfolio bidding parameters and defaults
HireOtto exposes standard, portfolio, and aligned workflows through `manage_bidding_strategies`.
| Parameter | Required | Default | Use |
| --------------------------- | --------------------------------------------------: | ---------------------- | ------------------------------------------------------------- |
| `action` | Yes | — | Choose the bidding operation. |
| `customer_id` | Yes | — | Google Ads customer ID, without hyphens. |
| `campaign_id` | For campaign assignment or standard-bidding actions | — | Campaign to update. |
| `bidding_strategy_id` | For usage, attach, alignment, and removal actions | — | Existing portfolio strategy ID. |
| `budget_id` | For aligned workflows | — | Existing shared budget ID. |
| `name` | For portfolio creation or a new dedicated budget | — | Resource name. |
| `strategy_type` | For creation and standard-bidding actions | — | Supported bidding strategy type. |
| `target_cpa` | When used by the chosen strategy | — | Target CPA in account currency. |
| `target_roas` | When used by the chosen strategy | — | ROAS ratio; `3.5` means 350%. |
| `cpc_bid_ceiling` | When supported | — | Maximum CPC in account currency. |
| `enhanced_cpc_enabled` | Manual CPC standard bidding only | Unchanged when omitted | Enable or disable enhanced CPC where supported. |
| `location` | Target impression share only | — | `ABSOLUTE_TOP_OF_PAGE`, `TOP_OF_PAGE`, or `ANYWHERE_ON_PAGE`. |
| `location_fraction` | Target impression share only | — | Share target expressed as 0–1 or 0–100. |
| `include_campaigns` | No | `true` | Include assigned campaigns in a strategy inventory. |
| `include_bidding_strategy` | No | `true` | Include strategy metadata when listing campaigns that use it. |
| `allow_removal_if_assigned` | No | `false` | Safety override for removal. |
Portfolio creation supports:
* `TARGET_SPEND` with an optional CPC ceiling.
* `TARGET_CPA` with an optional CPA target.
* `TARGET_ROAS` with an optional ROAS target.
* `MAXIMIZE_CONVERSIONS` with an optional CPA target.
* `MAXIMIZE_CONVERSION_VALUE` with an optional ROAS target.
* `TARGET_IMPRESSION_SHARE` with a location, share target, and CPC ceiling.
Standard campaign-level bidding supports `MANUAL_CPC`, `TARGET_SPEND`, `MAXIMIZE_CONVERSIONS`, `MAXIMIZE_CONVERSION_VALUE`, and `TARGET_IMPRESSION_SHARE`. Not every strategy is eligible for every campaign type, and automated strategies may have data or configuration requirements.
### Create and attach a portfolio strategy
Creating a portfolio strategy does not attach it to any campaign.
Before attaching it, compare the strategy's campaign eligibility and current assignments with the campaign you intend to move.
When a portfolio strategy is attached, its settings become the active bidding surface. Campaign-level standard bidding fields no longer control the campaign.
## Align a shared budget and portfolio strategy
Alignment is an explicit relationship between two existing account-level resources. It is not created merely because the same campaigns use both resources.
Before linking:
1. Confirm the budget is explicitly shared.
2. Confirm both resources exist in the same customer account.
3. Compare their assigned campaign sets.
4. Make the campaign sets identical, or ensure both resources are unused.
5. Check whether either resource is already aligned to a different partner.
After the pair is linked, attach a campaign to both resources in one update:
Do not attach only the budget or only the strategy when Google Ads expects an aligned pair. A one-sided update can fail because it would break the alignment relationship.
## Move a campaign out of an aligned setup
To split one campaign out of an aligned shared budget and portfolio strategy, use the combined workflow. It creates a new non-shared daily budget, moves the campaign to it, clears the portfolio assignment, and applies standard campaign-level bidding in one operation.
This combined update avoids a temporary state in which the campaign points to only one side of the previous alignment.
## Remove unused resources safely
HireOtto never removes the previous budget or portfolio strategy automatically after a campaign moves. That behavior prevents a cleanup step from deleting a resource still needed by another campaign.
Use a two-step cleanup:
1. List the resource and its current campaign assignments.
2. Remove it only when the assigned campaign count is zero and you have confirmed the ID.
The removal safety override defaults to `false`. Keep it that way for normal cleanup. A budget associated with active or paused campaigns cannot be removed, and forcing an assigned-resource removal is not a substitute for moving campaigns first.
## Read and write scope
Read-only actions can:
* List all current budgets or portfolio strategies.
* Show the campaigns assigned to one resource.
* Return budget amounts, periods, shareability, statuses, bidding types, targets, and alignment metadata.
Write actions can:
* Create daily or eligible campaign-total budgets.
* Change a daily budget amount or make an eligible standalone budget shared.
* Replace a campaign's current budget.
* Create and attach portfolio bidding strategies.
* Move a campaign back to supported standard bidding.
* Link an eligible shared budget and portfolio strategy.
* Attach a campaign to an aligned pair in one update.
* Split a campaign out of an aligned setup in one update.
* Remove eligible unused resources.
HireOtto does not activate a future workflow automatically or decide that a budget, target CPA, target ROAS, or campaign grouping is appropriate. Each write occurs only when the connected AI client calls the action.
## Limits and failure cases
### Budget restrictions
* A campaign must always have a budget. Replacing the budget is the supported way to detach the old one.
* A `CUSTOM_PERIOD` campaign-total budget cannot be shared.
* Eligible campaign-total budgets require supported campaign and bidding configurations, including start and end dates where Google requires them.
* A non-shared budget can become shared in eligible cases, but a shared budget cannot become non-shared.
* Campaign experiments require their own non-shared budgets.
* Google Ads limits the number of budget resources in an account.
* A budget still used by an active or paused campaign cannot be removed.
### Bidding and alignment restrictions
* The requested strategy may be incompatible with the campaign type or its current configuration.
* An automated strategy may not be eligible when conversion history, goals, or required targets are missing.
* A shared budget and portfolio strategy cannot be linked when their assigned campaign sets differ.
* A budget or strategy already aligned to a different partner cannot be silently realigned.
* An aligned campaign move can fail when only the budget or only the strategy is updated.
* Creating a resource does not make it active; it remains unused until attached.
### Access and request failures
* The connected Google login can see the account but lacks permission to edit it.
* A customer, campaign, budget, or strategy ID belongs to a different account or no longer exists.
* A required value is missing, has the wrong unit, or uses an unsupported strategy name.
* A write succeeds for a new resource but a later, separate assignment fails, leaving the new object unused. Prefer the combined workflows when they match the job.
* Google Ads rejects the request because of account limits, eligibility rules, policy state, or a temporary API error.
When a request fails, keep the returned IDs, inspect the live account state, and resume from the failed step. Do not rerun an entire creation sequence blindly, because that can create duplicate unused resources.
## Verification checklist
After every approved write, confirm:
* The customer and campaign IDs match the intended account.
* The campaign points to the intended budget ID.
* The saved budget amount is in the account currency.
* The budget's shareability and period match the plan.
* The campaign points to the intended portfolio strategy, or to standard bidding when that was the goal.
* Target CPA, target ROAS, CPC ceiling, or impression-share fields match the approved values.
* Both sides of an explicit budget–strategy alignment reference each other.
* The assigned campaign sets are correct.
* Any previous budget or strategy reported as unused remains in the account until separately reviewed and removed.
For broader capability details, see the [Google Ads tools reference](/google-ads-mcp-tools), [Google Ads quickstart](/quickstart), and [credits, billing, and plans](/credits-and-billing).
# Manage Google Ads conversion actions with HireOtto
Source: https://docs.hireotto.com/guides/manage-google-ads-conversion-actions
Review tracking readiness, create a native action, import an eligible GA4 key event, or update an existing action without confusing configuration with measurement.
# What you can do
Use HireOtto’s Google Ads server to inspect conversion tracking, create supported native conversion actions, import eligible GA4 key events, and update supported settings on existing actions.
The server can change Google Ads configuration when you explicitly ask it to. It does not decide which business outcome should guide bidding, install or test your website tag, validate GA4 measurement, upload offline conversion records, or change campaign goals automatically.
A safe workflow starts by reading the current setup, chooses one source of truth for the outcome, makes one reviewable change, and reads the live action back.
# Choose the right path
## Create a native website conversion action
Choose this path when Google Ads should receive a website conversion directly through the Google tag or Google Tag Manager. HireOtto creates the conversion action definition in Google Ads. You must still implement and test the tag separately.
## Import a GA4 key event
Choose this path when the business event is already measured correctly in a linked GA4 property and marked as a key event. Importing makes the eligible event available as a Google Ads conversion action; it does not validate the GA4 event or repair its implementation.
## Create an offline upload action
Choose `UPLOAD_CLICKS` or `UPLOAD_CALLS` only when you already have an appropriate offline-conversion ingestion workflow. HireOtto creates the action definition. It does not upload click or call conversion records, and Google may apply separate eligibility or integration restrictions to ingestion.
## Update an existing action
Choose this path when the correct action already exists and you need to change a supported setting. Inspect the action first: editable fields vary by source, owner, conversion type, and Google Ads eligibility.
# Access, plans, and write scope
* Connect the Google Ads server at [https://googleads.hireotto.com/mcp](https://googleads.hireotto.com/mcp) and select the intended Google Ads customer.
* Conversion review is read-only. Create, import, and update operations write to the connected Google Ads account.
* Your connected Google identity needs sufficient Google Ads permission for the requested operation. HireOtto cannot exceed that identity’s access.
* Conversion management is part of the core Google Ads server across the plans shown on the current pricing page. Usage-based plans consume credits; Agency currently advertises unlimited usage.
* Write access is capability, not approval. Ask the AI client to show the exact customer, action, current value, and proposed value before a consequential change.
# Before you begin
* Identify the exact Google Ads customer ID and business outcome.
* Decide whether Google Ads or GA4 is the source of truth for that outcome.
* List existing actions and check for duplicates, ownership, source, status, primary status, and recent data.
* For GA4 imports, confirm the property is linked to Google Ads and the exact event is marked as a GA4 key event.
* Choose the counting rule, value behavior, and whether the action should begin as primary or secondary.
* Review how a primary-status, attribution, or lookback-window change could affect reporting and automated bidding.
# Review conversion tracking first
Begin with a read-only review. HireOtto can report auto-tagging, conversion-tracking ownership, available GA4 link evidence, imported GA4 actions, and GA4 key events that Google Ads exposes as available to import.
Treat “not detected” carefully. If a linked GA4 property has not exposed a synced key event to Google Ads, the review may be inconclusive rather than proof that no link exists. Confirm the link and key-event status in the platforms, then allow time for synchronization.
You can also list conversion actions and inspect conversion volume and value for a date range. Use those results to find duplicates and stale or unused actions; do not treat a short period with zero conversions as automatic evidence that an action is broken.
## Read-only prompt
# Create a native conversion action
Creating a native action requires a customer ID and a name. The default source type is WEBPAGE. The supported source types are WEBPAGE, UPLOAD\_CLICKS, and UPLOAD\_CALLS.
## Supported settings and defaults
* name — Required. Use a clear business-outcome name and check for an equivalent action first.
* source type — WEBPAGE by default; UPLOAD\_CLICKS and UPLOAD\_CALLS are also supported.
* status — New actions are created as ENABLED. A different creation status is not supported.
* category — DEFAULT when omitted, or another valid Google Ads conversion category.
* counting type — ONE\_PER\_CLICK or MANY\_PER\_CLICK. When omitted, Google Ads applies its applicable behavior.
* primary for goal — Set true for a primary action or false for a secondary action. When omitted, Google Ads applies its applicable behavior.
* default value — Optional and must be zero or greater.
* always use default value — Optional. If you provide a default value without enabling this setting, event-specific values can still take precedence.
* attribution model — Optional and limited to a model supported and eligible for that action.
* click-through lookback window — A whole number from 1 to 90 days.
* view-through lookback window — A whole number from 1 to 30 days.
For optional settings that you omit, HireOtto does not invent a value; Google Ads applies the behavior available to that action.
## Example: create a secondary website action
After creation, implement the Google tag or GTM configuration, test it, and wait for reliable data before considering primary status. Creating the action does not install or verify the website measurement.
## Example: create an offline action definition
# Import a GA4 key event
A GA4 import requires the exact, case-sensitive key-event name. If more than one linked property exposes the same name, provide the GA4 property ID as a number or in properties/123456789 format.
## Prerequisites
* The GA4 property is linked to the intended Google Ads customer.
* The event exists in GA4 and is marked as a key event.
* Google Ads has synchronized and exposed the event as eligible to import.
* The event has not already been imported into that customer.
For an import, you can set a name, category, primary status, default value, and default-value behavior. Counting type, attribution model, and a custom creation status are not accepted during import. The imported action becomes enabled.
If the event is already imported, HireOtto returns the existing state instead of creating a duplicate. If multiple properties match, the operation stops and asks for a property ID.
## Example: import as secondary
Validate the event’s trigger, parameters, consent behavior, and observed data in GA4 before using it for optimization. Importing an event is not measurement QA.
# Update an existing action
Provide the conversion action ID or full resource name and at least one field to change. Only the supplied fields are updated; omitted fields remain unchanged.
## Supported update fields
* name
* status, when Google Ads allows it
* category
* counting type: ONE\_PER\_CLICK or MANY\_PER\_CLICK
* primary for goal
* default value of zero or greater
* always use default value
* an eligible attribution model
* click-through lookback window from 1 to 90 whole days
* view-through lookback window from 1 to 30 whole days
The legacy include\_in\_conversions\_metric field cannot be changed. Use primary for goal to manage primary-versus-secondary behavior where the action supports it.
Google Ads may reject a field because the action’s source, owner, type, or current eligibility makes it read-only. HireOtto does not change an action’s source, owner, ID, or resource identity.
## Example: change value behavior
## Example: change a lookback window
## Example: promote a validated action
# Recommended review sequence
1. List existing conversion actions and identify the intended action by customer ID and action ID.
2. Check for duplicates and confirm whether the source is native Google Ads, GA4, or offline upload.
3. Review ownership, status, primary status, counting, value behavior, attribution, and lookback windows.
4. Prepare one action or one class of updates with exact before-and-after values.
5. Wait for practitioner approval before a write.
6. Apply the change and read the live action back.
7. Validate measurement data separately before allowing the signal to influence bidding.
# Limits and common failure cases
## The action already exists
A duplicate name or equivalent outcome can fragment reporting and bidding signals. List actions first. GA4 imports also stop when the exact event is already imported.
## The GA4 key event is missing or ambiguous
Confirm the property link, exact case-sensitive name, key-event status, and synchronization. If several properties expose the same name, supply the property ID.
## The field is unsupported for that operation
GA4 import does not accept counting type, attribution model, or a custom status. New native actions cannot be created paused. Update support varies by action source and eligibility.
## A value or window is invalid
Default value must be zero or greater. Click-through windows must be whole numbers from 1 to 90 days; view-through windows must be whole numbers from 1 to 30 days.
## Google Ads rejects the write
Check the connected identity, customer access, action owner, source, current status, and Google Ads eligibility. A manager-account view does not guarantee edit permission in every client account.
## The action exists but no data arrives
For website actions, confirm tag or GTM implementation, consent, trigger conditions, and network requests. For GA4 imports, validate the event in GA4 and allow for reporting delay. For upload actions, confirm the separate ingestion workflow. HireOtto’s configuration response is not proof that measurement is firing.
## A change alters bidding or reporting
Primary status, attribution, counting, value behavior, and lookback windows can change how conversions appear or influence automated bidding. Review downstream goals and campaigns before applying the change.
# Related documentation
* Google Ads quickstart — [https://docs.hireotto.com/quickstart](https://docs.hireotto.com/quickstart)
* Authentication — [https://docs.hireotto.com/authentication-1](https://docs.hireotto.com/authentication-1)
* Google Ads MCP tools reference — [https://docs.hireotto.com/google-ads-mcp-tools](https://docs.hireotto.com/google-ads-mcp-tools)
* Video walkthrough: manage Google Ads conversions with AI — [https://docs.hireotto.com/manage-google-ads-conversions-with-ai](https://docs.hireotto.com/manage-google-ads-conversions-with-ai)
* Plans and pricing — [https://hireotto.com/pricing](https://hireotto.com/pricing)
* Product changelog — [https://docs.hireotto.com/changelog](https://docs.hireotto.com/changelog)
# Manage Google Ads Negative Keywords with AI
Source: https://docs.hireotto.com/guides/manage-negative-keywords-in-google-ads-with-ai
Find wasted search terms, add negatives at campaign or ad group level, and create, review, or clean up shared negative keyword lists in Google Ads using HireOtto.
***
Negative keywords are one of the highest-leverage optimisations in Google Ads — they stop your budget from being wasted on irrelevant queries. HireOtto supports all three levels of negative keyword management: campaign-level, ad group-level, and shared lists. This guide covers each approach and how to use them together effectively.
## Negative keyword workflow
A practical workflow looks like this:
1. Pull the search terms report
2. Sort by cost, clicks, or conversions
3. Identify irrelevant queries or high-spend zero-conversion terms
4. Decide whether each term belongs at campaign, ad group, or shared-list level
5. Add confirmed negatives – or remove stale, incorrect, or overly broad negatives from shared lists
6. Re-check performance after a few days
Start with the [Reporting guide](/guides/reporting) if you need to pull search terms first.
## Three ways to add negatives
**Campaign-level** — blocks a term across every ad group in the campaign. Best for broad exclusions that apply to the whole campaign (e.g. "free", "jobs", "DIY").
**Ad group-level** — blocks a term only within a specific ad group. Best for preventing cross-contamination between ad groups (e.g. blocking "product B" keywords in the "product A" ad group).
**Shared negative keyword lists** — a reusable list you create once and assign to multiple campaigns. Best for exclusions you'll want across many campaigns (e.g. a brand safety list, a competitor exclusion list, or a standard jobs/free-trial exclusion set).
***
## Finding negatives to add
The search terms report is the primary source. Pull it for any account or campaign you want to clean up:
```text theme={null}
Get the search terms report for account [CUSTOMER_ID] for the last 30 days, sorted by cost, output mode summary_and_csv.
```
Look for: terms with spend but zero or low conversions, irrelevant queries, competitor brand names you don't want to pay for, and queries that don't match your offer.
***
## Adding negatives at the campaign level
For broad exclusions across an entire campaign:
```text theme={null}
Add "[NEGATIVE_KW1]", "[NEGATIVE_KW2]", "[NEGATIVE_KW3]" as exact match negatives to campaign [CAMPAIGN_ID].
```
Mixed match types:
```text theme={null}
Add these negatives to campaign [CAMPAIGN_ID]: "[KW1]" as broad match, "[KW2]" as phrase match, "[KW3]" as exact match.
```
**Match type guidance:**
* **Exact** — only blocks that precise query. Most surgical, lowest risk of over-blocking.
* **Phrase** — blocks any query containing that phrase in order.
* **Broad** — blocks any query containing all the words in any order. Use carefully — it can block more than you intend.
When in doubt, start with exact match negatives. You can always expand later.
***
## Adding negatives at the ad group level
For cross-contamination prevention between ad groups:
```text theme={null}
Add "[NEGATIVE_KW]" as exact match negative to ad group [ADGROUP_ID] in campaign [CAMPAIGN_ID].
```
***
## Shared negative keyword lists
### Creating a new list
Create a list with initial keywords in one step:
```text theme={null}
Create a negative keyword list called "[LIST_NAME]" with these keywords as exact match: [KW1], [KW2], [KW3].
```
Mixed match types:
```text theme={null}
Create a negative keyword list called "[LIST_NAME]": "[KW1]" broad, "[KW2]" phrase, "[KW3]" exact.
```
### Assigning a list to campaigns
After creating a list (or to assign an existing one), get the list ID first:
```text theme={null}
List all negative keyword lists in account [CUSTOMER_ID].
```
Then assign it:
```text theme={null}
Assign negative keyword list [LIST_ID] to campaign [CAMPAIGN_ID].
```
You can assign the same list to multiple campaigns:
```text theme={null}
Assign negative keyword list [LIST_ID] to campaign [CAMPAIGN_ID_1].
```
```text theme={null}
Assign negative keyword list [LIST_ID] to campaign [CAMPAIGN_ID_2].
```
### Adding more keywords to an existing list
```text theme={null}
Add these keywords to negative list [LIST_ID]: "[KW1]", "[KW2]", "[KW3]" — exact match.
```
### Reviewing an existing list
```text theme={null}
List all negative keyword lists in account [CUSTOMER_ID] and include the keywords in each list.
```
Shared negative lists are especially useful during [Google Ads account audits](/guides/google-ads-account-audit-with-ai), because they reveal whether an account has reusable exclusions or scattered one-off negatives.
### Removing keywords from an existing list
Shared negative keyword lists change over time. You may need to remove a keyword that is too broad, no longer relevant, or was added by mistake.
HireOtto supports two workflows.
#### **Remove directly using keyword text and match type**
Specify both the keyword and match type so HireOtto removes the intended entry:
```text theme={null}
Remove “social media” as broad match and “open source” as phrase match from the negative keyword list “[LIST_NAME]”.
```
![Claude using HireOtto to remove broad- and phrase-match keywords from a shared Google Ads negative keyword list.]()
#### **Review the list first, then remove selected entries**
Start by listing the keywords:
```text theme={null}
List all negative keyword lists in account [CUSTOMER_ID] and include the keywords in each list.
```
HireOtto returns each keyword’s text, match type, and exact identifier. You can then continue in the same conversation:
```text theme={null}
From negative keyword list [LIST_ID], remove “[KW1]” ([MATCH_TYPE]) and “[KW2]” ([MATCH_TYPE]) using the entries you just returned.
```
You can also provide the returned resource names directly when you already have them:
```text theme={null}
Remove these entries from negative keyword list [LIST_ID] using their resource names: [RESOURCE_NAME_1], [RESOURCE_NAME_2].
```
The review-first workflow is useful when you want to confirm exactly what will be removed before changing a list shared across several campaigns.
***
## Typical negative keyword workflow
**New account or campaign:**
1. Pull search terms for context (if the account has history)
2. Create a shared brand-safety / common-exclusions list
3. Assign it to all campaigns
4. Add any campaign-specific negatives at campaign level
**Ongoing optimisation (weekly or monthly):**
1. Pull search terms report sorted by cost
2. Identify wasted spend — zero-conversion terms with significant spend
3. Add confirmed wasted terms as campaign-level exact match negatives
4. Add any terms that indicate ad group cross-contamination at ad group level
5. For terms you'll want to exclude permanently across all campaigns, add to your shared list
6. Periodically review shared lists and remove outdated or overly broad exclusions that may be blocking useful traffic.
**Full weekly negative review sequence:**
```text theme={null}
Get the search terms report for account [CUSTOMER_ID] for the last 7 days, sorted by cost, output mode summary_and_csv.
```
```text theme={null}
Add these negatives to campaign [CAMPAIGN_ID]: "[WASTED_TERM_1]", "[WASTED_TERM_2]" — exact match.
```
```text theme={null}
Add "[BROAD_EXCLUSION]" to negative keyword list [LIST_ID] — phrase match.
```
***
## Related workflows
* [Analyze Google Ads performance reports with AI](/guides/reporting)
* [Google Ads Daily Optimization with AI](/guides/google-ads-daily-optimization-with-ai)
* [Google Ads Account Audit with AI](/guides/google-ads-account-audit-with-ai)
# Manage Performance Max Campaigns with AI
Source: https://docs.hireotto.com/guides/manage-performance-max-campaigns
Create and manage Google Performance Max campaigns with AI. Handle asset groups, assets, audience signals, search themes, and PMax reporting.
***
This guide covers everything HireOtto can do with PMax: creating campaigns, managing asset groups, updating assets, managing signals, and reporting.
## Concepts worth understanding first
**Asset group** — the core unit of a PMax campaign. Each asset group contains a set of creative assets (headlines, images, logos) and optional signals. Google mixes and matches these assets to create ads. One campaign can have multiple asset groups, typically organised by product line, audience, or landing page.
**Signals** — hints you give Google about who to target. Two types:
* **Audience signals** — reusable audience lists from your account (remarketing lists, customer match, similar audiences)
* **Search themes** — keyword-like text strings that tell Google what searches are relevant for this asset group. Not keywords — Google can serve beyond them, but they bias the algorithm.
**Brand guidelines** — an optional campaign-level setting that locks your business name and logos at the campaign level rather than the asset group level. When enabled, brand assets are shared across all asset groups in the campaign automatically. This affects what you need to provide when adding a new asset group (you won't need to re-supply logos and business name — they're inherited).
## What HireOtto can do for Performance Max
Use HireOtto to:
* Create Performance Max campaigns
* Add and update asset groups
* Upload and reuse image, logo, headline, and description assets
* Manage audience signals
* Add or remove search themes
* Review asset group strength
* Pull PMax search terms, placements, feed type, and asset reports
***
## Creating a PMax campaign
One step creates everything: the budget, the campaign, the first asset group, and optional signals.
**Required assets:**
* 3–15 headlines (≤ 30 characters each)
* 1 long headline (≤ 90 characters)
* 2–5 descriptions (≤ 90 characters each)
* Business name
* At least 1 landscape marketing image (URL)
* At least 1 square marketing image (URL)
* At least 1 logo (URL)
* Final URL (landing page)
**Minimum viable prompt:**
```text theme={null}
Create a Performance Max campaign called "[CAMPAIGN_NAME]" with a [BUDGET]/day budget.
Asset group: "[ASSET_GROUP_NAME]"
Final URL: [YOUR_URL]
Business name: [BUSINESS_NAME]
Headlines: [H1], [H2], [H3]
Long headline: [LH1]
Descriptions: [D1], [D2]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
```
**With bidding and location targeting:**
```text theme={null}
Create a Performance Max campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversions with a target CPA of [TARGET_CPA].
Asset group: "[ASSET_GROUP_NAME]"
Final URL: [YOUR_URL]
Business name: [BUSINESS_NAME]
Headlines: [H1], [H2], [H3], [H4], [H5]
Long headline: [LH1]
Descriptions: [D1], [D2], [D3]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
```
Bidding options: `Maximise Conversions` (with optional target CPA) or `Maximise Conversion Value` (with optional target ROAS). No other bidding strategies are available for PMax.
**With audience signals and search themes (recommended):**
```text theme={null}
Create a Performance Max campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION].
Asset group: "[ASSET_GROUP_NAME]"
Final URL: [YOUR_URL]
Business name: [BUSINESS_NAME]
Headlines: [H1], [H2], [H3], [H4], [H5]
Long headline: [LH1]
Descriptions: [D1], [D2]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
Audience signals: [AUDIENCE_ID_1], [AUDIENCE_ID_2]
Search themes: [THEME_1], [THEME_2], [THEME_3]
```
To find available audience IDs before creating:
```text theme={null}
List audiences in account [CUSTOMER_ID].
```
**With brand guidelines enabled:**
Brand guidelines lock your business name and logos at the campaign level. When enabled, all asset groups in the campaign inherit these brand assets automatically — you won't need to supply them again when adding more asset groups later.
```text theme={null}
Create a Performance Max campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, brand guidelines enabled.
Asset group: "[ASSET_GROUP_NAME]"
Final URL: [YOUR_URL]
Business name: [BUSINESS_NAME]
Headlines: [H1], [H2], [H3]
Long headline: [LH1]
Descriptions: [D1], [D2]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
Landscape logo: [LANDSCAPE_LOGO_URL]
```
Note: landscape logo is optional for standard campaigns but worth providing when enabling brand guidelines — it becomes a campaign-level brand asset used across all placements.
***
## Adding a second asset group
Add asset groups to an existing PMax campaign to segment by product, audience, or landing page.
**Standard campaign (no brand guidelines):**
```text theme={null}
Add a new asset group called "[ASSET_GROUP_NAME]" to PMax campaign [CAMPAIGN_ID].
Final URL: [YOUR_URL]
Business name: [BUSINESS_NAME]
Headlines: [H1], [H2], [H3]
Long headline: [LH1]
Descriptions: [D1], [D2]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
```
**Brand-guidelines-enabled campaign:**
Business name and logos are already attached at the campaign level — don't re-supply them. HireOtto handles this automatically.
```text theme={null}
Add a new asset group called "[ASSET_GROUP_NAME]" to PMax campaign [CAMPAIGN_ID].
Final URL: [YOUR_URL]
Headlines: [H1], [H2], [H3]
Long headline: [LH1]
Descriptions: [D1], [D2]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
```
***
## Reviewing existing campaigns and asset groups
**List all PMax campaigns:**
```text theme={null}
List all campaigns in account [CUSTOMER_ID].
```
**List asset groups in a campaign:**
```text theme={null}
List asset groups for PMax campaign [CAMPAIGN_ID].
```
**List all assets attached to an asset group:**
```text theme={null}
List assets for asset group [ASSET_GROUP_ID].
```
This returns asset resource names — you'll need these for remove operations or when reusing assets across groups.
**List signals on an asset group:**
```text theme={null}
List signals for asset group [ASSET_GROUP_ID].
```
Returns current audience signals and search themes, with their signal resource names — needed for removal.
**List campaign-level brand assets (brand-guidelines campaigns only):**
```text theme={null}
List brand assets for PMax campaign [CAMPAIGN_ID].
```
Returns business name, logo, and landscape logo assets linked at the campaign level, including asset resource names and image dimensions.
***
## Updating asset group status
Pause, enable, or remove an asset group without touching the campaign:
```text theme={null}
Pause asset group [ASSET_GROUP_ID] in account [CUSTOMER_ID].
```
```text theme={null}
Enable asset group [ASSET_GROUP_ID] in account [CUSTOMER_ID].
```
```text theme={null}
Remove asset group [ASSET_GROUP_ID] in account [CUSTOMER_ID].
```
***
## Adding new assets to an existing asset group
Use this when you want to upload and attach new creative — new image URLs, new headlines, etc.
```text theme={null}
Add these headlines to asset group [ASSET_GROUP_ID]: [H1], [H2].
```
```text theme={null}
Add a new landscape image to asset group [ASSET_GROUP_ID]: [IMAGE_URL].
```
```text theme={null}
Add a new square image and logo to asset group [ASSET_GROUP_ID]:
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
```
You can add multiple asset types in one prompt.
***
## Reusing existing assets across asset groups
If the same image or text asset already exists in your account (uploaded to another asset group), you can attach it to a new asset group without re-uploading — this avoids creating duplicate assets in your library.
You'll need the asset resource names first:
```text theme={null}
List assets for asset group [ASSET_GROUP_ID].
```
Then attach them to another group:
```text theme={null}
Attach these existing assets to asset group [ASSET_GROUP_ID]:
Landscape image: customers/[CUSTOMER_ID]/assets/[ASSET_ID]
Square image: customers/[CUSTOMER_ID]/assets/[ASSET_ID]
```
HireOtto skips any assets that are already linked to the target asset group — no duplicates created.
**When to use this vs. adding new assets:**
* New URL or new creative → use `add` (creates and uploads)
* Same asset already in your library → use `attach` (links existing, no duplicate)
***
## Removing assets from an asset group
You need the exact asset resource names to remove assets. Get them first:
```text theme={null}
List assets for asset group [ASSET_GROUP_ID].
```
Then remove:
```text theme={null}
Remove the landscape image customers/[CUSTOMER_ID]/assets/[ASSET_ID] from asset group [ASSET_GROUP_ID].
```
HireOtto validates that the removal won't leave the asset group below Google's minimum asset requirements before proceeding.
***
## Managing audience signals
**Add an audience signal:**
```text theme={null}
Add audience [AUDIENCE_ID] as a signal to asset group [ASSET_GROUP_ID].
```
To find available audiences first:
```text theme={null}
List audiences in account [CUSTOMER_ID].
```
**Remove an audience signal:**
You need the signal resource name, not the audience ID. Get it first:
```text theme={null}
List signals for asset group [ASSET_GROUP_ID].
```
Then remove:
```text theme={null}
Remove signal [SIGNAL_RESOURCE_NAME] from asset group [ASSET_GROUP_ID].
```
***
## Managing search themes
**Add search themes:**
```text theme={null}
Add these search themes to asset group [ASSET_GROUP_ID]: [THEME_1], [THEME_2], [THEME_3].
```
Search themes are plain text — write them like keyword phrases, not as match-type keywords. They're signals, not targeting constraints.
**Remove a search theme:**
Get the signal resource name first:
```text theme={null}
List signals for asset group [ASSET_GROUP_ID].
```
Then remove:
```text theme={null}
Remove search theme [SIGNAL_RESOURCE_NAME] from asset group [ASSET_GROUP_ID].
```
***
## Reporting
PMax has eight dedicated reports. Because Google doesn't expose keyword-level data for PMax, these reports are your primary diagnostic tools.
### Campaign performance
Overall metrics: impressions, clicks, conversions, cost, ROAS.
```text theme={null}
Get PMax campaign performance for account [CUSTOMER_ID] for the last 30 days.
```
### Asset group performance
Breaks down metrics per asset group — useful for comparing performance across segments.
```text theme={null}
Get PMax asset group performance for campaign [CAMPAIGN_ID] for the last 30 days.
```
### Asset group strength
Ad strength score and action items per asset group. No date range needed — this reflects current state.
```text theme={null}
Get asset group strength for campaign [CAMPAIGN_ID].
```
What to look for: any asset group rated "Poor" or "Good" (not "Excellent") will have specific action items. Addressing them — adding more headlines, improving image variety — directly improves Performance.
### Asset-level performance
Metrics per individual asset (each headline, image, description). Shows which creative is performing and which isn't.
```text theme={null}
Get PMax asset performance for asset group [ASSET_GROUP_ID] for the last 30 days.
```
For large asset libraries, export to CSV:
```text theme={null}
Get PMax asset performance for campaign [CAMPAIGN_ID] for the last 30 days, export to CSV.
```
### Top asset combinations
Shows the actual asset combinations Google is serving most — which headlines are appearing with which images and descriptions.
```text theme={null}
Get top asset combinations for campaign [CAMPAIGN_ID].
```
No date range needed. Use this to understand what Google is favouring and whether it aligns with your messaging.
### Search terms report
Queries that triggered your PMax ads. One of the most valuable reports — helps identify wasted spend and negative keyword candidates.
```text theme={null}
Get PMax search terms report for campaign [CAMPAIGN_ID] for the last 30 days, sorted by cost, output mode summary_and_csv.
```
Terms with spend and zero conversions are candidates for negatives. Add them at the campaign level:
```text theme={null}
Add "[WASTED_TERM]" as an exact match negative to campaign [CAMPAIGN_ID].
```
### Campaign placements
Where your PMax ads are showing — websites, apps, YouTube channels.
```text theme={null}
Get PMax campaign placements for campaign [CAMPAIGN_ID] for the last 30 days, sorted by cost.
```
Use this to identify low-quality placement categories or specific sites/apps burning budget.
### Campaign feed types
Breaks down performance by feed type (product feeds, store feeds, etc.). Relevant if your PMax campaign uses a Google Merchant Center feed.
```text theme={null}
Get PMax campaign feed types for campaign [CAMPAIGN_ID] for the last 30 days.
```
For non-PMax campaign reporting, see [Analyze Google Ads performance reports with AI](/guides/reporting).
***
## Typical PMax audit sequence
For an existing PMax campaign, this sequence gives you a full picture:
```text theme={null}
Get asset group strength for campaign [CAMPAIGN_ID].
```
```text theme={null}
Get PMax asset group performance for campaign [CAMPAIGN_ID] for the last 30 days, sorted by cost.
```
```text theme={null}
Get PMax search terms report for campaign [CAMPAIGN_ID] for the last 30 days, sorted by cost, output mode summary_and_csv.
```
```text theme={null}
Get top asset combinations for campaign [CAMPAIGN_ID].
```
```text theme={null}
Get PMax asset performance for campaign [CAMPAIGN_ID] for the last 30 days, export to CSV.
```
```text theme={null}
Get PMax campaign placements for campaign [CAMPAIGN_ID] for the last 30 days, sorted by cost.
```
Start with asset strength — it tells you where to focus. Then search terms for waste. Then asset performance and combinations to understand what creative is working.
***
## Full creation sequence (copy-paste)
Replace all placeholders before running:
```text theme={null}
List audiences in account [CUSTOMER_ID].
```
```text theme={null}
Create a Performance Max campaign called "[CAMPAIGN_NAME]", [BUDGET]/day, targeting [LOCATION], Maximise Conversions.
Asset group: "[ASSET_GROUP_NAME]"
Final URL: [YOUR_URL]
Business name: [BUSINESS_NAME]
Headlines: [H1], [H2], [H3], [H4], [H5]
Long headline: [LH1]
Descriptions: [D1], [D2], [D3]
Landscape image: [IMAGE_URL]
Square image: [SQUARE_IMAGE_URL]
Logo: [LOGO_URL]
Audience signals: [AUDIENCE_ID]
Search themes: [THEME_1], [THEME_2], [THEME_3]
```
```text theme={null}
Get asset group strength for campaign [CAMPAIGN_ID].
```
```text theme={null}
Enable campaign [CAMPAIGN_ID].
```
## Related workflows
* [Google Ads Account Audit with AI](/guides/google-ads-account-audit-with-ai)
* [Analyze Google Ads performance reports with AI](/guides/reporting)
* [Manage Negative Keywords in Google Ads with AI](/guides/manage-negative-keywords-in-google-ads-with-ai)
* [Google Ads MCP Tools Reference](/google-ads-mcp-tools)
# Analyze Google Ads performance reports with AI
Source: https://docs.hireotto.com/guides/reporting
Pull campaign, ad group, keyword, search terms, geo, device, impression share, and PMax reports from Google Ads using AI prompts.
***
HireOtto gives you every performance report available in Google Ads — campaign, ad group, keyword, search terms, geo, device, impression share, demographics, and more — through a single conversation. This guide covers when to use each report, how to pull it efficiently, and how to get the output format that suits your workflow.
## Before you start: choosing the right output mode
Most reports support three [output modes](/output-modes). Pick the right one upfront to avoid pulling twice:
* **`summary`** (default) — results inline in chat, up to 50 rows. Good for quick checks on small accounts or when you want to read and act immediately.
* **`summary_and_csv`** — inline preview plus a CSV download. Best for weekly reviews where you want to scan in chat and keep the full export.
* **`csv_only`** — CSV link only, nothing printed inline. Best for large accounts, bulk pulls, or when you're taking the data elsewhere.
CSV download links expire after 30 minutes by default. Download before the link expires.
***
## Filtering saves you money
Every performance report accepts optional `campaign_id` and (where relevant) `adgroup_id` filters. If you only need data for one campaign, pass the ID — it limits what gets fetched and keeps responses fast. List your campaigns first if you need the IDs:
```text theme={null}
List all campaigns in account [CUSTOMER_ID].
```
***
## Campaign performance
Your top-level view: spend, impressions, clicks, conversions, CTR, avg CPC, cost per conversion — one row per campaign.
```text theme={null}
Get campaign performance for account [CUSTOMER_ID] for the last 30 days, sorted by cost.
```
To segment by day (useful for spotting day-of-week patterns or the impact of a change):
```text theme={null}
Get campaign performance for account [CUSTOMER_ID] for last month, segmented by day, export to CSV.
```
***
## Ad group performance
Drill into how individual ad groups are performing within a campaign. Pass `campaign_id` to limit the pull to one campaign.
```text theme={null}
Get ad group performance for campaign [CAMPAIGN_ID] in account [CUSTOMER_ID] for the last 30 days.
```
For a large account where you want the full export:
```text theme={null}
Get ad group performance for account [CUSTOMER_ID] for the last 30 days, csv_only.
```
***
## Keyword performance
One of the most useful reports — covers metrics, match types, and Quality Score signals. A single pull answers several questions: which keywords are spending without converting, how match type is distributed, and where QS needs work.
Always filter by campaign or ad group when you can — keyword reports across large accounts can be very long.
```text theme={null}
Get keyword performance for campaign [CAMPAIGN_ID] for the last 30 days, sorted by cost.
```
For a full export to analyse match type distribution or pause decisions:
```text theme={null}
Get keyword performance for account [CUSTOMER_ID] for the last 30 days, output mode summary_and_csv, sorted by cost.
```
***
## Search terms report
Shows the actual queries that triggered your ads — the raw input your match types are working with. Essential for finding wasted spend and negative keyword candidates.
```text theme={null}
Get the search terms report for account [CUSTOMER_ID] for the last 30 days, sorted by cost, output mode summary_and_csv.
```
For a specific campaign:
```text theme={null}
Get the search terms report for campaign [CAMPAIGN_ID] for the last 14 days, sorted by cost.
```
From the output: terms with spend and zero conversions are your first negative keyword candidates. You can add them directly from the same conversation — see the [Negative keywords guide](/guides/manage-negative-keywords-in-google-ads-with-ai).
***
## Ad performance
Ad-level metrics: impressions, clicks, CTR, conversions, cost. Useful for comparing RSA performance within an ad group.
```text theme={null}
Get ad performance for campaign [CAMPAIGN_ID] for the last 30 days.
```
***
## Geographic performance
Spend and conversions broken down by location. Useful for identifying regions to exclude, adjust bids for, or expand into.
```text theme={null}
Get geo performance for account [CUSTOMER_ID] for the last 30 days, sorted by cost.
```
***
## Device performance
Splits performance across desktop, mobile, and tablet. Use this alongside campaign settings — if mobile is converting at half the rate of desktop, that should be reflected in your device bid modifiers.
```text theme={null}
Get device performance for account [CUSTOMER_ID] for the last 30 days.
```
***
## Impression share
Competitive visibility metrics: Search Impression Share, Lost IS (Budget), Lost IS (Rank), and Click Share. Tells you how much of the available auction you're winning and why you're losing the rest.
```text theme={null}
Get impression share data for account [CUSTOMER_ID] for the last 30 days.
```
For a specific campaign:
```text theme={null}
Get impression share for campaign [CAMPAIGN_ID] for last month.
```
***
## Conversion actions
Lists all conversion actions in the account with their aggregated performance. Useful for auditing which conversion types are firing and which aren't.
```text theme={null}
Get conversion actions for account [CUSTOMER_ID] for the last 30 days.
```
***
## Demographics (age & gender)
Breaks down performance by age range or gender. Only meaningful if your campaigns target the Display Network or YouTube, or if you have demographic bid modifiers set.
```text theme={null}
Get age performance for account [CUSTOMER_ID] for the last 30 days.
```
```text theme={null}
Get gender performance for account [CUSTOMER_ID] for the last 30 days.
```
***
## Extension asset performance
Use extension asset performance when you want to understand how sitelinks, callouts, structured snippets, call assets, and price assets are performing.
This is useful when you want to answer questions like:
* Which sitelinks are getting impressions?
* Are call assets getting clicks?
* Which account-level assets are active but not delivering?
* Which campaign or ad group has attached assets with no recent activity?
### Supported levels
HireOtto can pull extension asset performance at three levels:
* `customer` — account-level assets
* `campaign` — campaign-level assets
* `ad_group` — ad group-level assets
### Supported asset types
* `SITELINK`
* `CALLOUT`
* `STRUCTURED_SNIPPET`
* `CALL`
* `PRICE`
### Example prompts
```text theme={null}
Show extension asset performance for account [CUSTOMER_ID] over the last 30 days.
```
```text theme={null}
Show customer-level callout performance for account [CUSTOMER_ID] this month.
```
```text theme={null}
Show campaign-level sitelink performance for campaign [CAMPAIGN_ID] over the last 30 days.
```
```text theme={null}
Show ad group-level structured snippet performance for ad group [ADGROUP_ID] over the last 30 days.
```
```text theme={null}
Export extension asset performance for account [CUSTOMER_ID] for LAST_30_DAYS as CSV.
```
Newly created or newly linked assets may show zero metrics until they start serving.
Some Google Ads asset reports may return zero rows for fresh campaign-level or ad group-level associations with no delivery yet. If you want to check whether an asset is attached, use the extension asset listing action instead of the performance report.
***
## Running multiple reports in sequence
You can pull several reports in one conversation — HireOtto keeps context across turns. A typical weekly review sequence:
```text theme={null}
Get campaign performance for account [CUSTOMER_ID] for the last 7 days, sorted by cost.
```
```text theme={null}
Get search terms report for account [CUSTOMER_ID] for the last 7 days, sorted by cost, output mode summary_and_csv.
```
```text theme={null}
Get keyword performance for account [CUSTOMER_ID] for the last 7 days, sorted by cost.
```
If you want everything in one go and plan to work in spreadsheets:
```text theme={null}
Get campaign performance, ad group performance, and keyword performance for account [CUSTOMER_ID] for last month — all as CSV exports.
```
***
## Performance Max reports
PMax has its own dedicated report set. See the [Performance Max guide](/guides/manage-performance-max-campaigns#reporting) for the full breakdown.
***
## Custom reports (Agency plan)
If none of the above cover your specific report cut, you can write a custom GAQL query:
```text theme={null}
Run a custom GAQL query for account [CUSTOMER_ID]: SELECT campaign.name, campaign.status, metrics.impressions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 100
```
## Related workflows
* Use [Negative Keywords](/guides/manage-negative-keywords-in-google-ads-with-ai) after reviewing search terms with wasted spend.
* Use [Daily Optimization](/guides/google-ads-daily-optimization-with-ai) for a repeatable morning reporting routine.
* Use [Account Audit](/guides/google-ads-account-audit-with-ai) for a deeper review of settings, tracking, keywords, and hygiene.
* Use [Performance Max](/guides/manage-performance-max-campaigns) for PMax-specific reporting.
# Run a weekly Google Ads optimization audit with HireOtto
Source: https://docs.hireotto.com/guides/weekly-google-ads-optimization-audit
Turn mature account data into a ranked, review-ready decision queue without changing Google Ads.
# What the weekly audit does
The weekly optimization audit reviews enabled Google Ads campaigns after performance and conversion data has had time to mature. It compares the selected performance period with the preceding equal-length period, checks Search visibility, and reviews search terms, keywords, and responsive search ads.
The result is a severity-ranked decision queue with supporting evidence and downloadable CSV exports. The audit is read-only: it does not add negative keywords, change bids, pause ads, or make any other account changes.
# Before you begin
* Use an Agency plan. Weekly optimization audits are not included in Starter or Pro.
* Connect Google Ads and save the account you want HireOtto to access.
* Use the correct ten-digit Google Ads customer ID. Hyphens are optional.
* Make sure the selected period contains enough mature performance data to support a decision.
* Treat every recommendation as a review candidate, not an instruction to change the account.
# Quick start
With the defaults, HireOtto reviews the last 7 days against the previous 7 days. Search terms use a separate 30-day window that excludes the most recent 3 days so late conversions have more time to appear.
# How the audit works
## 1. Resolve the reporting windows
HireOtto resolves the main performance period in the Google Ads account’s time zone. If you do not supply a comparison period, it uses the immediately preceding period of equal length.
Search terms use their own mature window. By default, the audit includes 30 days and ends 3 days before the current day. You can replace that automatic window with an explicit search-term date range.
## 2. Review enabled-campaign trends
The audit compares enabled campaigns across the current and comparison periods. It reviews cost, clicks, impressions, conversions, conversion value, CPA context, and Search impression share.
A campaign-level conversion decline is flagged when the current period falls to 50% or less of the comparison period, provided the comparison period had at least 2 conversions. This protects the default check from reacting to a fall from one conversion to zero as if it were a mature trend.
## 3. Find search-term candidates
Search terms are organized into review queues rather than changed automatically.
* Possible negatives: fewer than 1 conversion, at least 3 clicks, and at least the minimum spend you set. The default minimum spend is 0 in the account currency.
* Possible new keywords: at least 1 conversion and not already represented as the same keyword.
* Same-as-keyword underperformance: a search term already represented by a keyword but showing evidence that deserves a closer look.
These are candidates only. A term can look inefficient because of conversion lag, a small sample, match behavior, offline lead quality, or an intentional upper-funnel role.
## 4. Review keywords
Enabled keywords are reviewed after they reach the minimum click threshold. The default is 10 clicks.
If you provide a target CPA, HireOtto uses it as the benchmark. If you omit it and the account has at least 5 conversions in the selected period, the audit can use the account CPA. A converting keyword is a high-CPA candidate at 1.5 times the benchmark by default.
Manual CPC keywords may also be returned for bid review. The audit does not change the bid.
## 5. Review responsive search ads
Enabled responsive search ads are reviewed for disapproval and relative CTR performance.
* Disapproved enabled ads are high-priority investigation items.
* An RSA needs at least 100 impressions before the default relative-performance check applies.
* The RSA is compared with other eligible RSAs in the same ad group—not with a universal CTR benchmark.
* The default low-CTR threshold is 75% or less of the eligible ad-group CTR.
An ad group needs at least two eligible ads for the relative CTR comparison.
## 6. Rank and export the results
HireOtto ranks findings by severity and returns the evidence behind each finding. It also separates detailed campaign, search-term, keyword, bid-review, and ad candidate rows.
CSV exports are created only for non-empty datasets. Depending on the account, the response can include exports for campaign performance, negative candidates, new-keyword candidates, keyword candidates, Manual CPC bid candidates, and underperforming ads.
# Parameters and defaults
## Reporting windows
* Performance period – LAST\_7\_DAYS by default. You can use a supported predefined period or provide custom start and end dates.
* Comparison period – omitted by default. HireOtto uses the immediately preceding period of equal length.
* Search-term period – omitted by default. HireOtto creates the mature search-term window from the lookback and lag settings.
* Search-term lookback – 30 days by default; set 1–90 days. Ignored when you provide an explicit search-term period.
* Conversion lag – 3 days by default; set 0–30 days. The most recent days are excluded from the automatically generated search-term window.
## Search-term and keyword thresholds
* Negative candidate conversions – fewer than 1 conversion by default.
* Negative candidate clicks – at least 3 clicks by default.
* Negative candidate cost – at least 0 in the account currency by default.
* New-keyword candidate conversions – at least 1 conversion by default.
* Keyword review clicks – at least 10 clicks by default.
* Target CPA – optional. When omitted, the account CPA is used only if the period has at least 5 conversions.
* High-CPA ratio – 1.5 times the CPA benchmark by default.
## Ad and performance thresholds
* RSA minimum impressions – 100 by default.
* RSA CTR ratio – 0.75 by default, meaning 75% or less of the eligible ad-group CTR.
* Campaign conversion-drop ratio – 0.5 by default, meaning current conversions are 50% or less of the comparison period.
## Output limits
* Detailed query limit – 500 rows per focused query by default; set 25–5,000. The limit applies separately to negative terms, positive terms, keywords, and ads.
* Inline findings limit – 50 by default; set 1–200. Full eligible candidate tables can still be available through CSV exports.
* CSV link lifetime – 30 minutes by default; set 1–1,440 minutes.
# How to read the response
## Start with scope
Confirm the customer ID, account time zone, performance period, comparison period, search-term period, conversion lag, enabled-campaign count, and detailed-query limit. This proves what the audit actually reviewed.
## Separate findings from interpretation
Each finding should include its severity, confidence, evidence, and a suggested next step. The finding is produced from the selected data and thresholds. Any additional explanation from the AI client should be presented separately.
Ask the client to show every high- and medium-severity finding. Low-severity findings can be summarized, but they should not disappear silently.
## Review passed checks
A useful audit reports important checks that passed as well as issues. No material finding does not mean the account is healthy in every respect; it means the reviewed data did not cross the selected thresholds.
## Check truncation and exports
If the inline findings or detail rows were truncated, use the CSV exports before calling the review complete. Download exports before their signed links expire, or rerun the audit to create fresh links.
# Move from finding to action safely
The audit can suggest the next supported Google Ads workflow, but it never executes it. Use a separate, approval-gated request for each change.
* Read the live entity and confirm the customer, campaign, ad-group, keyword, or ad ID.
* Check the finding against conversion lag, intent, attribution, sample size, lead quality, and account strategy.
* Ask for the exact proposed change and affected scope.
* Approve one class of change at a time.
* Read the live account state back after the change.
For negative keywords, review match type and scope before adding anything. For new keywords, choose the destination ad group and match type. For bids and ad status, confirm that the campaign’s bidding strategy and experiment structure make the proposed action valid.
# Practical examples
## Default weekly review
## Account with a known CPA target
## Longer conversion lag
## Large-account export
## Decision-queue follow-up
# Limits and failure cases
* Plan restriction – weekly optimization audits require the Agency plan.
* Read-only scope – the audit cannot add negatives, create keywords, change bids, pause ads, or edit campaigns.
* Missing account – reauthenticate or refresh accessible accounts if the customer ID was not saved or the connected Google identity no longer has access.
* Low conversion volume – when no target CPA is supplied and the selected period has fewer than 5 conversions, CPA-based keyword classifications can be limited.
* Young or low-volume account – default thresholds may produce few findings even when a marketer should still inspect the account manually.
* Privacy and reporting limits – some search terms can be absent because of Google Ads privacy thresholds or reporting behavior.
* Row limits – detailed queries can stop at their configured limits. Increase the limit or narrow the request when important entities are missing.
* Truncated inline output – the findings limit controls what appears in chat, not necessarily every eligible candidate. Use the exports.
* Expired export – signed CSV links expire. Rerun the audit or request a longer lifetime.
* Permissions, quota, or platform error – read the returned error before retrying. Do not describe the audit as complete if a required section failed or was not run.
# Weekly audit versus other HireOtto audits
Use the daily operations audit for delivery, pacing, stopped-serving campaigns, and sudden spend changes. Use the weekly optimization audit for mature campaign, search-term, keyword, and RSA decisions. Use the account health audit for monthly or quarterly structural, tracking, targeting, Quality Score, negative-coverage, geographic, device, and Search visibility checks.
# Related documentation
[Connect Google Ads to HireOtto](https://docs.hireotto.com/quickstart)
[Google Ads authentication and account access](https://docs.hireotto.com/authentication-1)
[Google Ads MCP tools reference](https://docs.hireotto.com/google-ads-mcp-tools)
[Google Ads report output modes](https://docs.hireotto.com/output-modes)
[HireOtto pricing](https://hireotto.com/pricing)
[HireOtto product changelog](https://docs.hireotto.com/changelog)
# HireOtto MCP servers for performance marketers
Source: https://docs.hireotto.com/index
Connect Google Ads, LinkedIn Ads, Google Tag Manager, Search Console, and GA4 to your AI client, then start with the right reporting, analysis, or reviewable action.
HireOtto connects the advertising and measurement platforms you already use to Claude, ChatGPT, Cursor, VS Code, Make, and other remote MCP-capable clients.
Choose a server below, complete the platform authorization, and begin with a small read request. Google Ads supports reporting and account changes; LinkedIn Ads supports reporting and selected draft-first actions; Tag Manager, Search Console, and GA4 are read-only in their current releases.
Report, investigate, build, and make supported account changes.
Pull reports, resolve targeting, manage images, & prepare campaign changes.
Set up HireOtto with Claude, Cursor, Windsurf, or any MCP client.
Browse all available tools and their parameters.
## Choose the server for your job
| Your job | Server | Current scope | Start here |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------- | ------------------------------- | ------------------------------------------------------- |
| Analyze performance, inspect account structure, research keywords, create supported campaigns, or apply approved changes | Google Ads | Read and write | [Google Ads quickstart](/quickstart) |
| Analyze Campaign Manager, research targeting, estimate audience size, or prepare supported image-led campaigns as drafts | LinkedIn Ads | Read and selected write actions | [LinkedIn Ads quickstart](/linkedin-ads/quickstart) |
| Review a live container or workspace and trace tags to firing and blocking triggers | Google Tag Manager | Read-only | [Tag Manager quickstart](/tag-manager/quickstart) |
| Analyze queries and pages, compare paid and organic search, inspect indexed URLs, or review sitemaps | Google Search Console | Read-only | [Search Console quickstart](/search-console/quickstart) |
| Analyze acquisition, landing pages, events, conversions, and compatible realtime metrics | Google Analytics 4 | Read-only beta | [GA4 quickstart](/google-analytics/quickstart) |
Each platform keeps its own account, property, container, role, and permission model. Connecting HireOtto does not expand the access of the Google or LinkedIn identity you authorize.
## Server endpoints
Add only the servers you need. Each endpoint is a separate remote MCP connection.
| Server | Endpoint | Platform authorization |
| ----------------------------- | -------------------------------------- | ---------------------------------------------------------------------- |
| Google Ads and Search Console | `https://googleads.hireotto.com/mcp` | Google Ads and Search Console use separate Google permissions |
| LinkedIn Ads | `https://linkedinads.hireotto.com/mcp` | LinkedIn identity with access to the intended Campaign Manager account |
| Google Tag Manager | `https://tagmanager.hireotto.com/mcp` | Google login with access to the intended GTM accounts and containers |
| Google Analytics 4 | `https://ga4.hireotto.com/mcp` | Google login with access to the intended GA4 properties |
You do not need your own Google Cloud project, LinkedIn developer application, API keys, JSON credentials, terminal, or local server. Your client must support remote MCP over HTTP and OAuth.
## Connect in three steps
### 1. Add the server to your AI client
Open the client's Apps, Connectors, Tools, Integrations, or MCP settings. Add a remote HTTP connection with the endpoint for the platform you need, then complete the HireOtto sign-in.
Client menus and workspace controls change over time. If the labels differ, look for the option to add a custom remote MCP server with OAuth. Do not configure HireOtto as a local command or `stdio` process.
### 2. Authorize the marketing platform
Connecting the MCP server and connecting the platform are two separate steps. After the HireOtto connection is active, ask the AI client to connect the relevant Google or LinkedIn service. Open the returned authorization link and choose an identity that already has access to the required accounts or properties.
Never paste a Google or LinkedIn password, API key, access token, refresh token, or encoded credential into a prompt.
### 3. Verify with a small read
Start by listing the resources available to the connected identity. Confirm the returned account or property name and ID before running a longer report or requesting a write.
## What each server can change
### Google Ads
Google Ads supports reporting, planning, account inspection, and supported write actions across campaigns and related entities. Some complex workflows, bulk changes, and audit tools have additional requirements. Read the live setting before a consequential change, review the proposed diff, apply one class of change at a time, and read the saved value back.
[Browse Google Ads tools and parameters →](/google-ads-mcp-tools)
### LinkedIn Ads
LinkedIn Ads supports read-only account discovery, hierarchy inspection, targeting research, audience estimates, and reporting. It can also upload supported images, create supported campaign objects as drafts, apply selected updates, and delete eligible draft entities. Write capability depends on the connected ad-account role and, for some sponsored-content workflows, access to the associated LinkedIn Page.
Campaign Manager remains the final place to preview rendering, review Page identity, check platform warnings, and activate deliberately.
[Browse LinkedIn Ads tools and parameters →](/linkedin-ads/tools-reference)
### Google Tag Manager
The current GTM server is read-only. It can inspect live or workspace configuration, connect tags with firing and blocking triggers, export container inventory, and scan public HTML for tracking signals. It cannot create, edit, delete, or publish GTM changes, and configuration inspection does not prove that a tag fired in a browser.
[Browse Tag Manager tools and parameters →](/tag-manager/tools-reference)
### Google Search Console
Search Console is read-only and uses a separate Google permission inside the Google Ads HireOtto connection. It can list properties and sitemaps, inspect Google's indexed information for a URL, and report organic performance by supported dimensions. It cannot change a site, sitemap, or indexing state, and URL inspection is not a live-page test.
[Browse Search Console tools and parameters →](/search-console/tools-reference)
### Google Analytics 4
GA4 is a read-only beta. It supports account and property discovery, configuration inspection, metadata search, Core field-compatibility checks, standard reports, comparisons, basic realtime reporting, and CSV exports. It does not edit properties, events, key events, audiences, attribution settings, or reports saved in the GA4 interface.
[Browse GA4 tools and parameters →](/google-analytics/tools-reference)
## Start with a practical workflow
After the connection check succeeds, ask for one job with a clearly defined scope.
## Plans, profiles, and usage
Core access to Google Ads, LinkedIn Ads, Tag Manager, Search Console, and GA4 beta is available on Free, Starter, Pro, and Agency. Capabilities still vary by server.
| Plan | Included usage | Best fit |
| ------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| Free | 200 credits or 14 days, whichever comes first | Test supported core workflows |
| Starter | 2,000 credits per month | Lighter in-house usage |
| Pro | 5,000 credits per month | Higher individual usage |
| Agency | Unlimited credits, two included seats, audits, multiple connected profiles, and team billing | Teams and multi-profile account work |
The default profile is used when `profile_id` is omitted. Additional named profiles require Agency or enabled Enterprise access in the public workflow. A named profile represents a separately authorized Google or LinkedIn identity; renaming the same identity does not expand its platform access.
Starter, Pro, and Agency do not impose a plan-based limit on supported platforms, ad accounts, or managed spend. More accounts, reports, and exports naturally use more credits on Starter and Pro. Audit tools are Agency-only. Tool-specific credit costs, row limits, output modes, pagination, and temporary export-link lifetimes are documented in each server's tools reference.
[Review current plans and entitlements →](/credits-and-billing)
## Common connection problems
| Problem | What to check |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No tools appear | Confirm the endpoint ends in `/mcp`, finish client OAuth, enable the connection, and refresh or reconnect the client's cached tool list |
| The platform asks you to authenticate again | Run the relevant connect prompt, open the newest authorization link, and finish consent with the intended Google or LinkedIn identity |
| No accounts, containers, or properties appear | Confirm that the same identity can open the resource directly in the platform and has the required role or permission |
| Search Console is missing | Authorize Search Console separately inside the Google Ads HireOtto connection; Google Ads consent does not grant Search Console access |
| A read works but a write fails | Confirm the platform role, parent-object state, account billing or policy warnings, Page permission where relevant, and whether the requested field is supported and mutable |
| A report is empty or incomplete | Check the account or property ID, date range, filters, selected dimensions, pagination or row limit, data freshness, and privacy thresholds |
| A CSV link expired | Rerun the same read-only request with a suitable supported export lifetime |
| A tool is blocked | Check the trial or billing period, remaining credits, server entitlement, and whether the request uses an Agency-only audit or named profile |
If the client does not support remote MCP or OAuth, it cannot complete the hosted HireOtto connection.
## Keep the practitioner in control
HireOtto gives the AI client structured access to the platform. It does not decide the business objective, budget, audience, creative standard, conversion definition, or acceptable risk for you.
For consequential actions:
1. Read the current account and entity.
2. Show the exact proposed change, including IDs and current versus new values.
3. Confirm the affected scope and required permissions.
4. Wait for approval.
5. Apply one class of change.
6. Read the live value back.
Access is not autonomy. The connected AI client calls tools only within the workflow you give it, and platform permissions still govern what those tools can read or change.
## Next steps
* [Learn what HireOtto is](/introduction)
* [Connect a HireOtto server](/setup/connect-ai-tool)
* [Review the feature and entitlement matrix](/feature-entitlement-matrix)
* [Understand credits, billing, and plans](/credits-and-billing)
* [Troubleshoot connections and permissions](/troubleshooting)
# What is HireOtto?
Source: https://docs.hireotto.com/introduction
Connect your AI client to advertising, analytics, tag management, and organic-search platforms through hosted MCP servers built for performance marketers.
HireOtto is a set of hosted MCP servers for performance marketers. It gives an MCP-capable AI client structured, permission-bound access to Google Ads, LinkedIn Ads, Google Tag Manager, Google Search Console, and Google Analytics 4.
Use it to ask questions, investigate performance, inspect measurement configuration, and—where the connected server supports it—prepare or apply reviewable changes from the same conversation. You do not need to build a developer app, configure a cloud project, manage API credentials, or run a local server.
HireOtto is an execution layer, not an autonomous media buyer. Your AI client can use the tools and data you authorize, but the marketer still owns the objective, business context, interpretation, and approval of consequential changes.
## What HireOtto connects
Each HireOtto server exposes a defined set of tools. Access is limited by the HireOtto plan, the marketing-platform identity you connect, and that identity's permissions.
| Server | Availability | What it can do | Platform scope |
| --------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| Google Ads | Available | Report, analyze, research, audit, create, and update supported Google Ads entities | Read and supported writes |
| LinkedIn Ads | Available | Inspect Campaign Manager, report performance and professional demographics, research targeting, manage supported images, create drafts, and make selected updates | Read and selected writes |
| Google Tag Manager | Available | Inspect accounts, containers, workspaces, tags, triggers, variables, folders, and tag wiring; scan public pages for tracking signals | Read-only |
| Google Search Console | Available | Discover properties, query organic performance, list sitemaps, and inspect Google's indexed information for URLs | Read-only |
| Google Analytics 4 | Beta | Discover properties, inspect configuration and metadata, check field compatibility, and run standard or realtime reports | Read-only |
Google Ads and Search Console share one HireOtto endpoint, but Google treats them as separate services. Connecting Google Ads does not grant Search Console access; authorize Search Console separately when you need organic-search data.
A server's write capability is not permission to make every possible platform change. HireOtto supports specific actions, while Google Ads and LinkedIn still enforce account roles, object state, policy, validation, and other platform rules. Review the exact account, object, current value, and proposed value before approving a consequential edit.
## How it works
MCP, or Model Context Protocol, is a standard way for AI clients to use external tools and data. HireOtto runs the MCP server remotely and handles the platform connection.
The workflow has two authorization layers:
1. **Connect the AI client to HireOtto.** Add the relevant remote MCP endpoint and complete the HireOtto sign-in.
2. **Connect the marketing platform.** From the AI client, start the Google or LinkedIn authorization flow and approve access with an identity that can open the resources you need.
3. **Verify the resource.** Run a small read request and confirm the returned account, property, container, role, currency, and other identifiers before deeper analysis or any write.
4. **Ask for the job.** Describe the business question or task in normal marketing language. The AI client chooses an available HireOtto tool, supplies its parameters, and returns the result in the conversation.
5. **Review the result.** Check the evidence and scope. For supported write workflows, inspect the proposed change and verify the saved state afterward.
Your Google or LinkedIn password is never pasted into the conversation. OAuth grants HireOtto only the access approved during authorization, and the underlying platform continues to enforce that identity's permissions.
## Server endpoints
Add only the connections you need:
| Connection | Remote MCP endpoint |
| ----------------------------- | -------------------------------------- |
| Google Ads and Search Console | `https://googleads.hireotto.com/mcp` |
| LinkedIn Ads | `https://linkedinads.hireotto.com/mcp` |
| Google Tag Manager | `https://tagmanager.hireotto.com/mcp` |
| Google Analytics 4 | `https://ga4.hireotto.com/mcp` |
Your AI client must support remote MCP servers over HTTP and OAuth. HireOtto works with MCP-capable clients and workflows including Claude, ChatGPT, Cursor, VS Code, and Make. Menu names and workspace-level availability can differ by client.
For client-specific steps, see [Connect HireOtto to an AI client](/setup/connect-ai-tool).
## Start with a read request
A small verification prompt confirms both the MCP connection and the platform authorization. It also helps prevent work in the wrong account or property.
If the expected resource is missing, check the connected platform identity before changing the prompt. HireOtto cannot discover an account, container, or property that the authorized identity cannot access.
## From questions to reviewable work
HireOtto is most useful when the prompt defines the decision you need, the scope to inspect, and the boundary on what may change.
### Analyze one platform
### Inspect measurement configuration
### Combine evidence across servers
Cross-platform analysis requires every relevant HireOtto server to be connected in the same AI workflow. Results from different platforms should stay clearly labelled because their metrics, attribution, scopes, and data freshness are not interchangeable.
### Prepare a controlled change
For supported write workflows, separate investigation from execution. Ask the AI client to show the current value, proposed value, affected object, and expected scope before anything changes.
After an approved write, ask the AI client to read the live object again. A successful action response is not a substitute for verifying the saved state.
## Plans, credits, and profiles
All current plans include supported core access to Google Ads, LinkedIn Ads, Tag Manager, Search Console, and GA4 beta.
| Plan | Usage | Best fit |
| ------- | --------------------------------------------- | ----------------------------------------------------- |
| Free | 200 credits or 14 days, whichever comes first | Testing supported core tools |
| Starter | 2,000 credits per month | Lighter individual or in-house usage |
| Pro | 5,000 credits per month | Higher individual usage |
| Agency | Unlimited credits; two seats included | Audits, multiple connected profiles, and team billing |
Simple discovery requests generally use fewer credits than deeper reports, planning requests, or multi-step work. Agency-only audit tools combine several checks into one repeatable workflow. Starter, Pro, and Agency do not set plan-based limits on the number of supported platforms, ad accounts, or managed spend; usage on Starter and Pro still consumes credits.
Each connection uses a default platform profile unless a profile is specified. Multiple connected profiles are an Agency capability. A profile represents a separate authorized login; assigning another label to the same login does not expand its platform access.
See [Credits, billing, and plans](/credits-and-billing) and the [Feature and entitlement matrix](/feature-entitlement-matrix) for current details.
## Defaults and limits
HireOtto provides opinionated defaults so common marketing requests can start quickly, but there is no single date range, row limit, or output default shared by every server and tool. The selected tool determines its supported parameters, default reporting window, row limit, output modes, and credit cost.
Before a high-stakes or large request:
* State the exact account, property, container, campaign, or other resource identifier.
* Use complete dates and name the comparison period.
* Specify the business metric that should guide interpretation.
* Request CSV output when the relevant tool supports exports and the complete row set matters.
* Check the server's tools reference for tool-specific defaults, maximum ranges, row limits, and export expiry.
* Split a large investigation into smaller requests if the AI client, platform API, or tool returns partial or truncated data.
Platform limits still apply. Reporting can be delayed, estimated, sampled, thresholded, privacy-filtered, or unavailable for low-volume segments. Search Console and advertising platforms may omit data; GA4 dimensions and metrics are not always compatible; a GTM configuration inventory cannot prove browser runtime behavior; and an audience-size estimate is not a performance forecast.
## Common failure cases
| Symptom | Likely cause | What to do |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| The server is connected, but no tools appear | The client has not refreshed the MCP connection, the endpoint is wrong, or the connector is disabled | Confirm the endpoint ends in `/mcp`, complete client authorization, enable the connector, and refresh the tool list |
| A tool asks you to authenticate | The platform connection is missing, expired, or revoked | Run the relevant connection prompt and complete the newest OAuth link |
| An expected resource is missing | The connected identity lacks access, the wrong profile is active, or a manager hierarchy is not discoverable from that login | Confirm access in the native platform, identify the active profile, and reconnect the correct identity |
| A report is empty or incomplete | The date range, filters, data volume, privacy threshold, compatibility rules, or platform retention limit exclude rows | Broaden or correct the request, inspect the returned metadata, and avoid interpreting missing rows as zero activity |
| A write is rejected | The server does not support that action, the connected role cannot write, the object is ineligible, or platform validation failed | Read the live object and permissions, narrow the change, correct the invalid setting, and retry only the failed step |
| A multi-step creation stops partway through | A parent object succeeded before a child object failed | Keep the returned IDs, inspect what was created, and resume from the failed step instead of rerunning the entire workflow |
| A tool is blocked | Credits are exhausted or the capability requires another plan | Check billing status, reduce unnecessary work, or move to the plan that includes the capability |
## What HireOtto does not decide
HireOtto can make platform data and supported actions available to an AI client. It does not know your sales feedback, lead quality, margin, legal constraints, creative standards, risk tolerance, or business priorities unless you provide them.
Treat the AI client's output as a structured starting point:
* Evidence should remain distinguishable from interpretation.
* Recommendations should name the account and entity they affect.
* Low-volume results should be labelled as uncertain.
* Cross-platform comparisons should preserve each platform's definitions.
* Consequential changes should have an explicit approval boundary.
* Every applied write should be read back from the platform.
## Choose your next step
Add the right endpoint, authorize the platform, and verify your first resource.
Connect Google Ads and run a safe first account request.
Verify Campaign Manager access, role, and write capability.
Inspect containers and tag wiring without changing GTM.
Authorize organic-search access and verify properties.
Connect the read-only GA4 beta and verify properties.
# Create a draft LinkedIn Ads campaign with HireOtto
Source: https://docs.hireotto.com/linkedin-ads/create-campaign
Validate targeting, upload an image, create a campaign group, ad set, and single-image ad as drafts, then inspect the saved result before activation.
Create a reviewable LinkedIn Ads campaign from your AI client without handing activation over to the model. HireOtto can validate a proposed campaign, create or reuse a campaign group, create an ad set, upload or reuse an image, and create a single-image Direct Sponsored Content ad.
The safe sequence is:
**verify access → resolve targeting → estimate audience size → prepare the image → validate the complete hierarchy → create as drafts → read back → preview in Campaign Manager → verify tracking → activate after approval**
HireOtto calls LinkedIn's campaign-group object a **campaign group** and LinkedIn's API campaign object an **ad set**. Keep the returned account, campaign-group, ad-set, creative, and image IDs with every review or follow-up request.
## What this workflow can change
This guide uses both read and write actions.
| Step | Scope |
| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Verify the connection, list accounts, read the hierarchy, discover targeting, estimate audience size, and validate a request | Read-only |
| Upload an image | Creates an image asset in LinkedIn |
| Create a campaign group, ad set, or creative | Writes to LinkedIn unless `validate_only=true` |
| Update a campaign group, ad set, or creative | Writes to LinkedIn unless `validate_only=true` |
| Delete an eligible draft ad set or creative | Deletes the selected draft object |
| Preview rendering and review platform warnings | Completed in LinkedIn Campaign Manager |
Creation defaults to draft behavior, but a LinkedIn draft is only a platform status. It is not a substitute for a human review of the objective, audience, budget, schedule, creative, destination, measurement, and Page identity.
## Before you start
You need:
* An MCP-capable AI client connected to `https://linkedinads.hireotto.com/mcp`.
* A LinkedIn identity with access to the intended Campaign Manager account.
* A role with sufficient write permission. Viewer access is read-only.
* Access to the LinkedIn Page or advertiser identity used by the ad when the workflow requires it.
* An approved objective, audience, budget, schedule, landing page, copy, image, and tracking plan.
* Enough HireOtto credits for validation, image upload, and creation.
LinkedIn Ads is available on Free, Starter, Pro, and Agency. The default LinkedIn profile is available on every plan. Additional named profiles require Agency or enabled Enterprise access.
Confirm the exact account ID and currency before preparing budgets. Do not select an account from its display name alone.
## 1. Prepare a complete campaign brief
Give the AI client the decisions it cannot safely infer:
* Business objective and the one outcome the campaign should optimize for.
* Offer and landing page.
* Campaign group and ad-set names.
* Included and excluded audience logic.
* Daily or total budget, account currency, and schedule.
* Ad format, bid approach, and optimization goal.
* Introductory text, headline, call to action, alt text, and image.
* The LinkedIn Page or advertiser identity that should appear.
* The conversion action and how it will be tested.
* The person who can approve activation.
Do not ask HireOtto to choose the business objective or budget from account data alone. Reporting can inform those decisions, but it does not define the campaign's commercial job.
## 2. Resolve targeting before creation
Use targeting discovery to convert marketer-friendly audience ideas into valid LinkedIn entities. Review every match and keep the exact URNs returned by LinkedIn.
Then estimate the combined audience with the intended inclusions and exclusions. Audience size is a delivery guardrail, not a quality score or reach forecast. LinkedIn can round counts, suppress details, and deliver to fewer members than the estimate.
Use locations or profile locations for geography. HireOtto adds interface-language targeting only when you explicitly provide `languages` or `interfaceLocales`. An explicit interface locale must contain exactly one value and must match the ad-set locale.
## 3. Reuse or upload an image
For the supported single-image path, the creative needs an image URN whose LinkedIn processing status is `AVAILABLE`.
Start by listing recent active Media Library assets. Reuse an existing approved asset when possible.
If the image is not already available, use the interactive upload tool in ChatGPT or Claude web or Desktop. It accepts JPG, PNG, and GIF files. The upload interface is not currently available in Claude Code CLI or the Claude Code VS Code extension.
Programmatic byte upload is available when the client can read and encode the original file. The decoded image must be no larger than 8 MiB, and only `image/jpeg`, `image/png`, and `image/gif` are accepted. Do not paste base64 into chat. If an upload times out, list recent assets before retrying so you do not create a duplicate.
## 4. Choose the hierarchy workflow
Use `create_linkedin_campaign` when you want to validate or create the campaign group, ad set, and optional creatives in order. You can either:
* Reuse an existing campaign group by supplying its ID.
* Create a new campaign group from settings you provide.
Use `create_linkedin_ads_entities` when you need to create only one object or recover from a failure after a parent object already exists.
### Campaign-group inputs
| Input | Required | Default or behavior |
| ------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | Yes for one-object creation | For a new group in the hierarchy workflow, HireOtto derives ` Campaign` if no name is supplied. Supply an explicit approved name instead. |
| `status` | No | `DRAFT` |
| `start` | No | Approximately ten minutes after the request |
| `end` | No | No end date |
| `total_budget_amount` | No | None; requires `currency_code` when supplied |
| `daily_budget_amount` | No | None; requires `currency_code` when supplied |
| `objective_type` | No | None |
| `budget_optimization_strategy` | No | None |
| `bid_strategy` | No | None |
### Ad-set inputs and defaults
An ad set requires a parent campaign group, `name`, targeting, and at least one budget. For the current image-led path, use `SPONSORED_UPDATES` with the appropriate standard-update format.
| Input | Required | Default or behavior |
| --------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | None |
| `status` | No | `DRAFT` |
| `campaign_type` | No | `SPONSORED_UPDATES` |
| `ad_format` | Required for a controlled build | No inferred format; select carefully because LinkedIn fixes formats such as standard update, single video, and carousel at creation |
| `objective_type` | Recommended | None |
| `cost_type` | No | `CPC` |
| `bid_strategy` | No | None; supported choices include maximum delivery, manual, target cost, and cost cap where compatible |
| `daily_budget_amount` / `total_budget_amount` | At least one | None; every supplied amount needs `currency_code` |
| `start` | No | Approximately ten minutes after the request |
| `end` | Conditional | Required when only a total budget is supplied |
| `locale_language` | No | `en` |
| `locale_country` | No | `US` |
| `audience_expansion_enabled` | No | `false` |
| `offsite_delivery_enabled` | No | `false` |
| `connected_television_only` | No | `false` |
| `political_intent` | No | `NOT_DECLARED` |
Sponsored Content, Dynamic Ads, and Lead Generation require an associated advertiser entity. HireOtto normally resolves it from the selected ad account. If it cannot, verify the account's advertiser identity and your Page access instead of inventing an organization or person URN.
Additional platform rules apply:
* Dynamic Ads require both daily and total budgets plus an ad format.
* Connected TV requires offsite delivery.
* Lead Generation cannot enable offsite delivery.
* Changing a fixed ad format requires a new ad set.
### Single-image creative inputs and defaults
The supported first-class path is a normal single-image Direct Sponsored Content ad.
| Input | Required | Default or behavior |
| ----------------- | ----------- | --------------------------------------------------------------------------- |
| `image_urn` | Yes | Must begin with `urn:li:image:` and be `AVAILABLE` |
| `commentary` | Recommended | Empty text if omitted; provide approved introductory copy |
| `headline` | No | None; maximum 400 characters |
| `landing_page` | No | None; maximum 2,000 characters |
| `cta_label` | No | `LEARN_MORE` when a landing page is supplied; a CTA requires a landing page |
| `image_alt_text` | No | None |
| `name` | No | None; internal creative name |
| `intended_status` | No | `DRAFT` |
Supported CTA labels include `APPLY`, `DOWNLOAD`, `VIEW_QUOTE`, `LEARN_MORE`, `SIGN_UP`, `SUBSCRIBE`, `REGISTER`, `JOIN`, `ATTEND`, `REQUEST_DEMO`, `SEE_MORE`, `UNLOCK_FULL_DOCUMENT`, `BUY_NOW`, and `SHOP_NOW`.
This workflow does not create LinkedIn Lead Gen Forms and does not upload video or document ads. It also does not validate the final visual rendering.
## 5. Validate the complete hierarchy
Set `validate_only=true` before an unfamiliar create. Validation normalizes the proposed request and checks HireOtto's supported rules without sending a create request to LinkedIn. For an ad set, it also resolves the supplied targeting URNs. For the first-class image path, it confirms that the image is available.
Validation does **not** reserve IDs or guarantee that a later write will pass. LinkedIn still checks permissions, Page access, budgets, dates, account state, and lifecycle rules when the real create runs.
Review the normalized output field by field. Pay particular attention to:
* Account ID and currency.
* Campaign-group and ad-set names.
* Objective, format, cost type, bid strategy, and optimization goal.
* Daily and total budget ownership.
* Start and end dates.
* Complete targeting inclusions and exclusions.
* Locale and any explicit interface-language targeting.
* Page identity, image status, destination, CTA, and alt text.
* Draft statuses for every new object.
## 6. Create the approved objects as drafts
After approval, run the same reviewed configuration with `validate_only=false` and explicitly require draft statuses. The full hierarchy create costs 10 HireOtto credits after success. It can create a new campaign group or reuse an existing one, then create the ad set and creative in order.
For a single object, validation costs 1 credit and a successful create costs 5 credits. A successful image upload costs 5 credits. A full hierarchy validation costs 1 credit; a successful full hierarchy create costs 10 credits. Credits are deducted only after a successful charged action. Agency has unlimited credits, but LinkedIn permissions and lifecycle restrictions still apply.
## 7. Inspect the saved hierarchy
A success response is not verification. Read the saved objects back from LinkedIn and compare the live values with the approved configuration.
Then open Campaign Manager to confirm:
* The ad renders correctly on the intended Page identity.
* The image crop, headline, introductory text, CTA, and destination are correct.
* The account has no billing, policy, or serving warning.
* The conversion action and Insight Tag plan are appropriate.
Creating a creative does not install or test the LinkedIn Insight Tag, Google Tag Manager, or the landing page. Configuration inspection cannot prove that a tag fires in a browser. Test the real conversion path separately before activation.
## Partial creation and recovery
The full hierarchy workflow is not transactional. If an ad set or creative fails, a campaign group or ad set created earlier in the sequence remains in LinkedIn.
Do not blindly rerun the full request. That can create duplicate parents.
1. Save every ID in `partial_result`.
2. Read the live hierarchy.
3. Identify the first object that failed.
4. Correct and validate only that object.
5. Resume with `create_linkedin_ads_entities` using the existing parent ID.
6. Read the new object back.
Eligible draft ad sets and creatives can be deleted deliberately. Non-draft objects may require a different lifecycle action. Always inspect the current status before requesting deletion.
## Controlled updates and activation
HireOtto supports selected updates to campaign groups, ad sets, and creatives, plus eligible draft deletion. Keep activation separate from budget, targeting, creative, date, and bid changes so every decision remains reviewable.
For targeting, a partial friendly include or exclude map sent through a general ad-set update can replace the existing targeting. Use the additive-exclusion action when you only want to add exclusions. For any broader targeting change, read the complete current criteria, resolve new entities, estimate the revised audience, and review the full diff.
LinkedIn can reject activation when the parent remains in draft, the schedule is stale, the account cannot serve, the creative is not eligible, or the connected role lacks permission. `validate_only=true` does not override those platform checks.
## Common failures
| Failure | Likely cause | Recovery |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| No account appears | Wrong LinkedIn identity, no Campaign Manager access, or stale saved access | Confirm the login in Campaign Manager and list accounts again with refresh enabled |
| Reads work but writes fail | Viewer role, insufficient ad-account role, missing Page access, account warning, or lifecycle restriction | Confirm role, `can_write`, Page access, billing, dates, parent status, and Campaign Manager warnings |
| Targeting validation fails | An included or excluded value is not a valid LinkedIn URN | Search the failing facet again and rebuild the criteria from returned URNs |
| Audience is below the eligible threshold | The combined criteria are too restrictive | Review the business requirement, overlapping filters, exclusions, and geography; do not broaden blindly |
| Image cannot be used | Unsupported type, file too large, processing incomplete, wrong account ownership, or upload timeout | Use JPG, PNG, or GIF under 8 MiB, wait for `AVAILABLE`, and list recent assets before retrying |
| Creative validation fails | Image unavailable, invalid CTA, CTA without destination, excessive headline or URL length, or unresolved advertiser identity | Correct the named field and verify the account's Page or advertiser context |
| Ad-set creation fails | Missing budget or currency, invalid format/objective combination, total budget without end date, or incompatible delivery setting | Return to the validated configuration and change only the failing field |
| Creation partially succeeds | A parent was created before a child failed | Preserve returned IDs and resume from the failed child only |
| Update is rejected | Immutable format, invalid lifecycle transition, or incomplete targeting replacement | Read the current object, validate a smaller change, or create a new ad set when the format is fixed |
## Current limits
* The first-class creation path is a normal single-image Direct Sponsored Content ad.
* Lead Gen Form creation is not supported.
* Image upload does not imply video or document-ad upload support.
* Fixed ad formats cannot be swapped after ad-set creation.
* Campaign Manager remains the final source for rendering, Page identity, policy review, billing, serving warnings, and activation state.
* Image processing, account permissions, lifecycle transitions, and LinkedIn-side validation can still fail after local validation.
* Creating an ad does not prove that the destination or conversion tracking works.
## Recommended review checklist
* [ ] Correct ad account ID, name, currency, role, and write capability
* [ ] Approved objective and campaign hierarchy
* [ ] Valid targeting URNs and viable audience estimate
* [ ] Correct budget owner, amount, currency, and schedule
* [ ] Compatible format, bid strategy, cost type, and optimization goal
* [ ] Available image and approved Page identity
* [ ] Approved copy, headline, destination, CTA, and alt text
* [ ] Every new object created as `DRAFT`
* [ ] Returned IDs saved and live values read back
* [ ] Creative previewed in Campaign Manager
* [ ] Landing page and tracking tested separately
* [ ] Named human approval recorded before activation
## Related documentation
* [Connect LinkedIn Ads](/linkedin-ads/quickstart)
* [LinkedIn Ads MCP tools reference](/linkedin-ads/tools-reference)
* [Discover LinkedIn Ads targeting and estimate audience size](/linkedin-ads/targeting)
* [Analyze LinkedIn Ads performance and professional demographics](/linkedin-ads/reporting)
* [HireOtto feature and entitlement matrix](/feature-entitlement-matrix)
* [Troubleshoot HireOtto connections and permissions](/troubleshooting)
# Connect LinkedIn Ads to Claude, ChatGPT, Make, Grok, or Perplexity
Source: https://docs.hireotto.com/linkedin-ads/quickstart
Set up HireOtto’s LinkedIn Ads MCP server, authorize Campaign Manager access, and run your first account query.
# What you need
* An AI client or agent that supports remote MCP servers over HTTP and OAuth.
* HireOtto access that includes the LinkedIn Ads server.
* A LinkedIn member account with access to the ad accounts you want to use.
* For ad creation, sufficient ad-account permissions and access to the associated LinkedIn Page.
HireOtto is hosted remotely. You do not need a LinkedIn developer app, API keys, JSON credentials, a terminal, or a local process.
# 1. Add the LinkedIn Ads server
Use this endpoint:
```text theme={null}
https://linkedinads.hireotto.com/mcp
```
Add it as a remote HTTP MCP connection and choose OAuth when your client asks for an authentication method. Give the connection a clear name, such as HireOtto — LinkedIn Ads.
## Common client paths
* Claude: open Customize → Connectors → Add custom connector.
* ChatGPT: open Plugins, then create a plugin with the endpoint.
* Make AI Agents: open the agent module, select Add MCP, and create a connection with the endpoint.
* Cursor, VS Code, or another client: open MCP or tools settings and add a remote HTTP server with OAuth.
Client menus and workspace permissions can change. If the labels differ, look for Apps, Connectors, Tools, Integrations, or MCP settings. Do not configure HireOtto as a local command or stdio process.
# 2. Authorize LinkedIn Ads
Connecting the MCP server and connecting LinkedIn Campaign Manager are two separate steps. After the HireOtto connection is active, start a new conversation and ask:
Open the authorization link, sign in with the LinkedIn identity that can access the required ad account, and approve the requested permissions. Return to your AI client when the flow is complete.
# 3. Verify the account, role, and write access
Start with a small read request:
HireOtto reports the current connection state along with the account list:
| State | Meaning | What to do |
| ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `not_connected` | The HireOtto MCP server is connected, but a LinkedIn identity has not been linked yet. | Open the returned authorization URL and approve LinkedIn access. |
| `connected_no_accounts` | LinkedIn is linked, but that identity has no accessible Campaign Manager ad accounts. | Create an ad account or request access to an existing one, then ask HireOtto to refresh the account list. |
| `account_lookup_failed` | LinkedIn authorization is saved, but HireOtto could not check account access. | Retry with `refresh=true`; reconnect LinkedIn Ads if the error persists. |
| `connected_with_accounts` | One or more accessible ad accounts were found. | Select the account by its returned name and ID. |
Viewer access is read-only. Creating or changing ads requires a sufficient ad-account role. Some sponsored-content workflows also require access to the LinkedIn Page used by the ad.
Viewer access is read-only. Creating or changing ads requires a sufficient ad-account role. Some sponsored-content workflows also require access to the LinkedIn Page used by the ad.
# 4. Run your first account read
Before asking for recommendations or changes, map the account hierarchy:
HireOtto uses “ad set” for the object LinkedIn’s API calls a campaign. Confirm the returned names and IDs before requesting any update.
# 5. Try a useful read-only workflow
Choose one of these prompts:
Professional-demographic reporting is privacy-protected and can lag standard reporting. Small groups may be suppressed, so treat these breakdowns as directional rather than exhaustive.
# 6. Prepare changes as drafts
After the read-only checks succeed, keep campaign creation behind an explicit approval boundary:
Use the sequence: validate → create in DRAFT → inspect each object → preview in Campaign Manager → verify tracking → activate only after named human approval. Campaign creation is multi-step. If a child object fails after a parent was created, inspect the returned IDs and resume from the failed step. Do not rerun the full workflow blindly.
# Safety checklist
* Confirm the ad account name and ID before every account-specific action.
* Review the connected role and write capability.
* Resolve LinkedIn targeting entities instead of inventing IDs.
* Check audience size, inclusions, and exclusions before creation.
* Create new campaign objects as drafts.
* Review budget, dates, destination, copy, image crop, alt text, tracking, and Page identity.
* Preview the final ad in Campaign Manager.
* Keep activation as a separate, explicit decision.
# Common setup problems
* Confirm that the endpoint ends with /mcp.
* Complete the client-level OAuth prompt, then rescan or refresh the server tools.
* Enable the connector or app in the current chat or agent.
* Reconnect the client if its MCP tool list is cached.
An empty account list can mean either that no ad account exists yet or that the LinkedIn identity you authorized does not have access to an existing account.
* If an ad account already exists, confirm that the authorized LinkedIn identity can open it in Campaign Manager. Check that you are using the correct LinkedIn login and, where applicable, the correct Business Manager. After access changes, ask HireOtto to refresh the account list.
* If no ad account exists, [open Campaign Manager](https://www.linkedin.com/campaignmanager/) and create one. Then ask HireOtto to refresh the account list.
Before creating an ad account, confirm the selected Business Manager or personal-profile context, billing currency, and LinkedIn Page. LinkedIn suggests a currency from the member profile, and the currency and associated Page cannot be changed after the account is created. If the account should belong under a Business Manager, select the correct Business Manager before creating it.
See [LinkedIn’s ad-account creation guidance](https://www.linkedin.com/help/lms/answer/a426102) for the current creation steps and restrictions.
* Check the role returned for the account. Viewer access is read-only.
* Confirm that your role allows the requested action.
* For sponsored content, confirm access to the associated LinkedIn Page.
* Check Campaign Manager for lifecycle, billing, or account warnings that can block a valid API request.
* Confirm the account, object IDs, and date window.
* Check that the selected objects delivered during the period.
* For professional demographics, allow for reporting delay and privacy suppression.
# What to try next
* Inspect account, campaign-group, ad-set, and creative performance.
* Analyze professional demographics one compatible pivot at a time.
* Resolve and size a targeting hypothesis before applying it.
* Reuse or upload an eligible image and prepare a draft single-image ad.
* Apply selected updates only after reviewing the current object and proposed change.
# Current boundaries
* Campaign Manager remains the final place to preview rendering, billing, warnings, and Page permissions.
* HireOtto does not currently create LinkedIn Lead Gen Forms.
* Do not assume the image upload workflow also supports video or document ads.
* Creating an ad does not install or validate the LinkedIn Insight Tag, Google Tag Manager, or the destination page.
* LinkedIn permissions and lifecycle rules can still block status changes or edits.
# Analyze LinkedIn Ads performance and professional demographics with HireOtto
Source: https://docs.hireotto.com/linkedin-ads/reporting
Run account, campaign-group, ad-set, creative, and professional-demographic reports from your AI client, then turn the evidence into a review-ready decision queue.
Use HireOtto to inspect LinkedIn Ads delivery, engagement, conversions, and professional-demographic patterns without changing Campaign Manager.
Start at the highest useful level, find the entities behind the result, and only then add a professional-demographic breakdown. This keeps the report tied to a decision instead of producing a large table with no operating context.
LinkedIn Ads reporting is read-only. A report request does not create, edit, pause, or activate ads. It does use HireOtto credits and can create a temporary CSV export when requested.
## Before you run a report
You need:
* The HireOtto LinkedIn Ads server connected to your AI client.
* A linked LinkedIn identity with access to the intended ad account.
* The exact LinkedIn ad-account ID.
* A reporting start date in `YYYY-MM-DD` format.
* A clear question, reporting level, and primary outcome metric.
If you have not connected LinkedIn Ads yet, follow the [LinkedIn Ads quickstart](/linkedin-ads/quickstart). Use the [LinkedIn Ads tools reference](/linkedin-ads/tools-reference) when you need the complete tool schema.
## Choose the reporting level
HireOtto uses a marketer-friendly hierarchy:
`Account → campaign group → ad set → creative`
The `level` parameter accepts the following values:
| Level | What it reports | Default pivot | Use it for |
| ---------- | ------------------------------------------------- | ---------------- | ---------------------------------------------------------- |
| `account` | The whole ad account | `ACCOUNT` | Executive pulse, spend and results across the account |
| `campaign` | LinkedIn campaign groups | `CAMPAIGN_GROUP` | Finding the campaign groups behind an account-level change |
| `ad_set` | LinkedIn ad campaigns, called ad sets in HireOtto | `CAMPAIGN` | Delivery, audience, budget, and result diagnosis |
| `creative` | Individual ads and creatives | `CREATIVE` | Creative comparisons and test planning |
`campaign` in the HireOtto reporting parameter means campaign group. `ad_set` maps to the LinkedIn object called a campaign in the API. Keep this distinction in mind when copying IDs from Campaign Manager or another export.
If `ids` is omitted, HireOtto reports across the full ad account. If you provide `ids`, each ID must belong to the selected level.
## Run a useful performance report
A strong first report uses a complete period and raw metrics that match the business question. For a website-conversion campaign, that commonly means:
* `impressions`
* `clicks`
* `landingPageClicks`
* `costInLocalCurrency`
* `externalWebsiteConversions`
Use engagement, lead, document, or video metrics only when the campaign format and objective make them relevant. HireOtto returns raw LinkedIn metrics. Ask your AI client to calculate CTR, CPC, CPM, conversion rate, or CPA from the underlying counts instead of requesting those derived rates as reporting fields.
### Compare complete periods
Run the same fields at the same level for both periods. Keep launches, promotions, pauses, attribution lag, and major budget changes visible so a structural change does not masquerade as an optimization insight.
### Drill down without changing the question
When a campaign group moves materially, keep the date range and metrics fixed while changing the reporting level. This isolates whether the movement came from one ad set, broad delivery, or the creative mix.
## Add a professional-demographic breakdown
Professional-demographic reporting helps answer whether the campaign reached and engaged the intended market. It is aggregated, approximate reporting—not a list of individual members or leads.
HireOtto supports these professional-demographic pivots:
| Question | Pivot |
| ------------------------------------------------ | --------------------- |
| Which companies appeared in the eligible report? | `MEMBER_COMPANY` |
| Which company sizes appeared? | `MEMBER_COMPANY_SIZE` |
| Which industries appeared? | `MEMBER_INDUSTRY` |
| Which seniorities appeared? | `MEMBER_SENIORITY` |
| Which job titles appeared? | `MEMBER_JOB_TITLE` |
| Which job functions appeared? | `MEMBER_JOB_FUNCTION` |
| Which countries appeared? | `MEMBER_COUNTRY_V2` |
| Which regions appeared? | `MEMBER_REGION_V2` |
Use one demographic dimension at a time when the goal is diagnosis. Multiple pivots are supported, but a more granular report can become sparse and harder to interpret.
### Interpret demographic data carefully
LinkedIn applies privacy and completeness rules to professional-demographic reports:
* Demographic data can arrive later than ordinary performance data. The LinkedIn Ads API documents a typical 12–24 hour delay, while Campaign Manager guidance says the data can take up to 48 hours to appear. Allow 48 hours before treating a missing recent segment as a tracking or targeting problem.
* Values with fewer than three events are removed from API results.
* Only the top 100 professional-demographic values are returned for each creative for each day.
* Professional-demographic metrics are approximate and may not sum exactly across days, levels, or similar date ranges.
* Professional-demographic data is retained for two years; ordinary performance data has a longer retention period.
* A company in the report is evidence that eligible delivery or engagement was associated with that company. It is not proof that the company was explicitly targeted or that its traffic was wasteful.
For the most stable interpretation, request the full period rather than summing daily demographic rows, and use the highest reporting level that answers the question.
Missing demographic rows do not mean zero exposure. They may reflect low delivery, privacy suppression, reporting delay, an incompatible metric, or a date range with no matching activity.
## Parameters and defaults
The reporting tool is `get_linkedin_ads_report`.
| Parameter | Required | Default | Accepted values and limits |
| -------------------- | -------- | ----------------------------------------- | --------------------------------------------------------------------- |
| `ad_account_id` | Yes | — | LinkedIn sponsored-account ID |
| `start_date` | Yes | — | `YYYY-MM-DD` |
| `end_date` | No | LinkedIn reports through the current date | `YYYY-MM-DD`; use an explicit completed date for repeatable analysis |
| `level` | No | `campaign` | `account`, `campaign`, `ad_set`, or `creative` |
| `ids` | No | Whole ad account | One or more IDs that match the selected level |
| `pivots` | No | Pivot for the selected level | One to three supported pivots |
| `metrics` | No | See the default fields below | Up to 20 fields after required context fields are added |
| `time_granularity` | No | `ALL` | `ALL`, `DAILY`, `MONTHLY`, or `YEARLY` |
| `profile_id` | No | Default LinkedIn profile | Named profiles require Agency |
| `output_mode` | No | `summary_and_csv` | `summary`, `summary_and_csv`, or `csv_only` |
| `limit` | No | `50` | Inline rows: 1–5,000 |
| `export_limit` | No | `5,000` | CSV rows: 1–50,000, subject to LinkedIn's 15,000-element response cap |
| `export_ttl_minutes` | No | `30` | 1–1,440 minutes |
When `metrics` is omitted, HireOtto requests:
```text theme={null}
dateRange
pivotValues
impressions
clicks
landingPageClicks
costInLocalCurrency
externalWebsiteConversions
likes
shares
totalEngagements
```
HireOtto automatically adds `dateRange` and `pivotValues` when they are missing from a custom metric list. They count toward LinkedIn's 20-field limit.
### Output modes
* `summary` returns inline rows only.
* `summary_and_csv` returns inline rows and creates a temporary CSV when the report has data.
* `csv_only` returns report metadata and the temporary CSV without placing the rows in chat.
LinkedIn Ad Analytics does not paginate, and LinkedIn limits a response to 15,000 elements. Increasing `export_limit` cannot retrieve rows that LinkedIn did not return. The CSV link expires after `export_ttl_minutes`; download it before it expires or rerun the report.
## Metric and pivot compatibility
Some metrics are available only for particular objectives, ad formats, or pivots. HireOtto rejects unlisted metrics and blocks known-incompatible professional-demographic combinations before sending the report.
Do not use these fields with `MEMBER_*` pivots:
* `conversionValueInLocalCurrency`
* `cardImpressions`
* `cardClicks`
* `viralCardImpressions`
* `viralCardClicks`
* `approximateMemberReach`
Carousel-card metrics are not available with professional-demographic pivots. Other LinkedIn compatibility rules can still cause a request to fail; remove the least essential field and rerun rather than changing the business question.
## Common failure cases
### The report is empty
An empty report is a valid result. It can mean:
* No activity matched the account, IDs, pivots, and date range.
* The connected LinkedIn identity lacks read access to the requested data.
* Recent demographic data has not arrived yet.
* Privacy thresholds removed all eligible demographic values.
Confirm the account and role, run a broader non-demographic report, then widen the date range or wait for the demographic delay. Do not interpret missing rows as zero automatically.
### The IDs do not match the level
A campaign-group ID used with `level=ad_set`, or an ad-set ID used with `level=creative`, can return an error or no matching rows. Read the hierarchy first and preserve the account, parent, and child IDs in the report request.
### The metric is unsupported
Use exact LinkedIn field names. Derived measures such as CTR, CPC, CPM, conversion rate, and CPA should be calculated from raw metrics after retrieval.
### The report is too granular
Two or three pivots use LinkedIn's statistics reporting mode. More dimensions increase sparsity, and more than three pivots are rejected. Start with one pivot and add another only when it answers a specific follow-up question.
### Old daily dates shift to month boundaries
LinkedIn can round older `timeGranularity=ALL` ranges to month boundaries when the requested start or end falls outside its daily-granularity retention window. Read the returned `dateRange` instead of assuming it matches the request exactly.
### The CSV link expired
Rerun the same read-only report. Extending `export_ttl_minutes` changes only the temporary link lifetime, not LinkedIn's reporting retention or row cap.
## Turn the report into decisions
Use a consistent review sequence:
1. Confirm account, currency, date range, and primary outcome.
2. Read the account or campaign-group pulse.
3. Isolate material movers at ad-set level.
4. Review creative performance with delivery volume beside each rate.
5. Add one professional-demographic view to test an audience hypothesis.
6. Label findings as Act, Investigate, Monitor, or Insufficient data.
7. Keep any proposed change separate from this read-only reporting workflow and require explicit review.
For cross-platform diagnosis, compare LinkedIn's campaign evidence with consistently tagged GA4 traffic or CRM outcomes. Keep each platform's attribution and metric definitions visible; a LinkedIn conversion, a GA4 key event, and a CRM opportunity are not interchangeable.
## Access, plans, and credits
LinkedIn Ads reporting is available on Free, Starter, Pro, and Agency. A report call uses 5 credits on credit-based plans; Agency includes unlimited credits. `profile_id` is optional for the default connection, while multiple named LinkedIn profiles require Agency.
The LinkedIn identity still needs access to the ad account. Viewer access is sufficient for reporting. Write permissions are not required because this workflow does not change LinkedIn Ads.
See [HireOtto pricing](https://hireotto.com/pricing) for current plan allowances and [LinkedIn's reporting documentation](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) for upstream retention, privacy, delay, and response restrictions.
# Discover LinkedIn Ads targeting and estimate audience size with HireOtto
Source: https://docs.hireotto.com/linkedin-ads/targeting
Resolve valid LinkedIn targeting entities, build inclusion and exclusion criteria, and check audience size before creating or updating an ad set.
Use HireOtto to turn an audience hypothesis into valid LinkedIn targeting criteria before you create or edit an ad set.
The safe sequence is:
`Describe the audience → resolve entities → review matches → build criteria → estimate audience size → approve the targeting`
This matters because LinkedIn targeting uses facets and exact entity URNs. A plausible company name, job title, or numeric ID is not enough. Resolve every value against LinkedIn, keep the returned URNs, and inspect ambiguous matches before the targeting is used.
Targeting discovery, criteria building, and audience estimation are read-only. They do not create or change a campaign. A successful targeting action uses 2 HireOtto credits.
## Before you start
You need:
* The HireOtto LinkedIn Ads server connected to your AI client.
* A linked LinkedIn identity with Campaign Manager access.
* A clear audience hypothesis in business language.
* The market, professional attributes, and exclusions you want to test.
* A decision about whether interface language should be an explicit audience filter.
If LinkedIn Ads is not connected yet, follow the [LinkedIn Ads quickstart](/linkedin-ads/quickstart). Use the [LinkedIn Ads tools reference](/linkedin-ads/tools-reference) for the complete tool schema.
You do not need write access to research targeting or estimate an audience. You do need access to the connected LinkedIn identity and enough HireOtto credits for the request.
## Understand facets and entities
LinkedIn organizes targeting into:
* **Facets:** categories such as locations, industries, job titles, job functions, seniorities, skills, or employers.
* **Entities:** the exact LinkedIn values inside a facet, each represented by a URN.
For example, `industries` is a facet. A specific industry returned by LinkedIn is an entity. HireOtto accepts marketer-friendly facet names, but targeting values should be the exact URNs returned by entity discovery.
Common friendly facet keys include:
| Audience idea | Friendly facet keys |
| ------------------- | --------------------------------------- |
| Geography | `locations`, `profileLocations` |
| Current company | `companies`, `employers` |
| Industry | `industries` |
| Current job title | `job_titles`, `titles` |
| Job function | `job_functions`, `functions` |
| Seniority | `seniorities` |
| Skills | `skills` |
| Company size | `company_sizes`, `staffCountRanges` |
| Years of experience | `years_of_experience` |
| Education | `degrees`, `fields_of_study`, `schools` |
| LinkedIn groups | `groups` |
| Interface language | `languages`, `interfaceLocales` |
Start with the smallest set of facets that represents the buying context. More filters do not automatically create a better audience.
## Resolve targeting entities
Use `search_entities` to find valid values inside one facet. Supply a text query when you know the concept but not the URN. Supply `entity_urns` when you already have URNs and want to confirm their names and facets.
The default result locale is English for the United States:
* `locale_language`: `en`
* `locale_country`: `US`
These fields localize discovery results. They do not add geographic targeting. Use `locations` or `profileLocations` for geography.
### Review matches before using them
Do not select the first result only because its label resembles the brief. Check:
* Whether the entity belongs to the intended facet.
* Whether a company is the correct organization rather than a similarly named employer.
* Whether a job title is the intended role rather than a nearby specialty.
* Whether a location represents the intended market.
* Whether a broad job function is being combined with a narrower title intentionally.
* Whether every exclusion identifies the exact company, role, or category you intend to remove.
If a search returns several plausible entities, keep them separate and ask the marketer to approve the intended match. Do not merge them or invent an ID.
For known URNs, use resolution as a preflight:
Never convert a label into a guessed numeric ID or URN. If LinkedIn does not return a valid entity for the intended facet, leave that value unresolved and revise the targeting hypothesis.
## Build inclusion and exclusion criteria
After you approve the entities, place their URNs into friendly include and exclude maps.
```json theme={null}
{
"included_targeting": {
"locations": ["urn:li:geo:103644278"],
"industries": ["urn:li:industry:4"],
"job_functions": ["urn:li:function:15"],
"seniorities": ["urn:li:seniority:4"]
},
"excluded_targeting": {
"companies": ["urn:li:organization:123456"]
}
}
```
Within one included facet, multiple values are alternatives. Different included facets narrow the audience together. Keep the final logic visible in plain language so the marketer can confirm what a member must match.
`build_criteria` converts friendly include and exclude maps into LinkedIn targeting criteria locally. It does not contact LinkedIn to validate the values. Use it to inspect the structure, not as proof that every URN is valid.
## Estimate audience size
Use `audience_count` only after the selected entities have been reviewed. HireOtto resolves every included and excluded facet-and-URN pair before requesting an estimate. If any value is invalid, unresolved, or assigned to the wrong facet, the action fails before LinkedIn receives an audience-estimate request.
The response can contain:
* `total`: LinkedIn's rounded estimate of members who fit the criteria.
* `active`: LinkedIn's estimate of members who are more likely to visit LinkedIn.
* Targeting validation showing which supplied entities resolved.
* The criteria used for the estimate.
LinkedIn requires an audience of at least 300 members for a campaign to run. To protect privacy, `total` is returned as `0` when the audience is below 300. The total is approximate, and actual reach will be lower than the target audience size.
### Treat the estimate as a guardrail
Audience size answers whether the targeting is plausibly eligible to deliver. It does not tell you whether the audience is commercially valuable, likely to convert, or large enough for your budget and learning goals.
Do not:
* Treat a larger estimate as a quality score.
* Sum separate estimates; the audiences can overlap and LinkedIn rounds the totals.
* Interpret `active=0` as an error or a campaign-status signal.
* Interpret a valid exclusion as proof that members from that company or category were present.
* Infer the exact number removed by an exclusion from the final rounded estimate.
When exclusions are supplied, HireOtto confirms that each exclusion is a valid entity for its facet. LinkedIn does not return an unrounded per-exclusion match count or an exact excluded-audience delta in this workflow.
## Use language and geography correctly
`locale_language` and `locale_country` localize entity discovery and supply ad-set locale metadata during creation. The country suffix in a LinkedIn locale is not geographic targeting.
For example:
* `en_US` means the English interface locale.
* It does not mean members located in the United States.
* Use `locations` or `profileLocations` to target the United States.
HireOtto adds interface-language targeting only when you explicitly supply `languages` or `interfaceLocales`. An explicit interface-language filter must contain exactly one supported value and match the normalized ad-set locale. Create separate ad sets when you need different interface languages.
Some enumerated facets—including seniorities, job functions, company sizes, years-of-experience ranges, age ranges, genders, and interface locales—use finite lists rather than normal free-text typeahead. HireOtto can list these values and filter the returned enumeration when you provide a query.
If a non-English job-title search returns no matches, retry with the English equivalent. The returned title URN is the targeting value; the search phrase itself is not added to the audience.
## Parameters and defaults
The targeting tool is `discover_linkedin_targeting`.
| Parameter | Required | Default | Meaning |
| -------------------- | --------------------- | ------------------------ | ----------------------------------------------------------------------- |
| `action` | Yes | — | `list_facets`, `search_entities`, `build_criteria`, or `audience_count` |
| `facet` | For `search_entities` | — | Friendly facet key or complete LinkedIn facet URN |
| `query` | No | None | Text to search within the chosen facet |
| `entity_urns` | No | None | Known URNs to resolve and verify |
| `included_targeting` | For `audience_count` | — | Friendly map of facets to approved URNs |
| `excluded_targeting` | No | Empty | Friendly map of exclusions |
| `locale_language` | No | `en` | Discovery language and ad-set locale input |
| `locale_country` | No | `US` | Discovery locale suffix and ad-set locale input; not geography |
| `profile_id` | No | Default LinkedIn profile | Additional named profiles require Agency or enabled Enterprise access |
The tool is available on the Free trial, Starter, Pro, and Agency plans. The normal credit or usage rules for the plan apply. Additional named LinkedIn profiles are reserved for Agency or enabled Enterprise access.
## Common failure cases
### An entity does not resolve
The URN may be malformed, unavailable, or valid under a different facet. Search the intended facet again and choose one of the returned entities. HireOtto returns structured validation and does not send an audience estimate or campaign write when a supplied value remains unresolved.
### The audience count is zero
A zero can mean the audience falls below LinkedIn's 300-member privacy threshold. It can also mean the combined criteria are too restrictive. Confirm that every entity resolved, then remove or broaden one deliberate constraint at a time. Do not assume that the tool failed.
### The audience is large but strategically weak
Audience size measures eligibility, not intent or quality. Revisit the business brief, roles, industries, company attributes, exclusions, and offer. A broad audience can deliver while missing the actual buying committee.
### An exclusion appears to have no effect
The estimate is rounded and does not expose an exact per-exclusion delta. A valid exclusion confirms that LinkedIn recognizes the entity for that facet; it does not prove how many matching members were removed.
### Interface language and locale do not match
Use exactly one valid `interfaceLocales` URN that matches the normalized ad-set locale, or omit explicit language targeting. Use geography facets for location. HireOtto stops before estimation or creation when these values conflict.
### Search returns no job-title matches
Retry the title in English, especially when the discovery locale is not English. Keep the intended business role visible and review the returned title before using its URN.
### Access or credits block the action
Verify the LinkedIn connection and confirm that the connected identity can access Campaign Manager. Check the current HireOtto plan and remaining credits. Targeting discovery is read-only, so a Viewer role is sufficient when the account and connection are otherwise accessible.
## Review checklist before campaign creation
Before you attach targeting to an ad set, confirm:
* Every included and excluded value was returned by LinkedIn for the intended facet.
* Ambiguous companies, titles, schools, or locations were approved by a marketer.
* The plain-language logic matches the brief.
* Geography uses `locations` or `profileLocations`.
* Interface language is included only when intentionally requested.
* The audience estimate clears the eligibility threshold without becoming the quality criterion.
* Separate estimates were not summed.
* The target audience, exclusions, budget, offer, and measurement plan were reviewed together.
* No campaign creation or update will run without an explicit approval step.
## Related documentation
* [Connect LinkedIn Ads](/linkedin-ads/quickstart)
* [LinkedIn Ads MCP tools reference](/linkedin-ads/tools-reference)
* [Analyze LinkedIn Ads performance and professional demographics](/linkedin-ads/reporting)
* [HireOtto feature and entitlement matrix](/feature-entitlement-matrix)
* [Troubleshoot HireOtto connections and permissions](/troubleshooting)
# LinkedIn Ads MCP tools reference
Source: https://docs.hireotto.com/linkedin-ads/tools-reference
Discover LinkedIn Ads accounts, inspect Campaign Manager, analyze performance, research targeting, manage image assets, and prepare reviewable campaign changes with HireOtto.
Use HireOtto's LinkedIn Ads tools to move from account discovery to reporting, targeting research, image management, and reviewable campaign changes from an MCP-capable AI client.
Start by confirming the ad account, your role, and write capability. Read the current hierarchy before using IDs in later requests. For campaign work, validate first, create in draft, inspect the saved objects, preview the ad in Campaign Manager, and activate only after approval.
LinkedIn Ads is available on the Free trial, Starter, Pro, and Agency plans. Reporting and discovery tools are read-only. Creation, update, image-upload, and authorization tools can save data in HireOtto or LinkedIn. Your LinkedIn role, Page access, account lifecycle, billing state, and HireOtto plan or credits can still limit an otherwise supported action.
## Connect the server
Add this hosted endpoint to a remote MCP-capable client:
```text theme={null}
https://linkedinads.hireotto.com/mcp
```
Complete the HireOtto sign-in, then connect LinkedIn separately. Use the LinkedIn identity that can access the required Campaign Manager ad account. You do not need your own LinkedIn developer application, API key, terminal, or local server.
See the [LinkedIn Ads quickstart](/linkedin-ads/quickstart) for client-specific setup and the [current pricing page](https://hireotto.com/pricing) for plan details.
The default connection is available on every plan. Additional named LinkedIn profiles require Agency or enabled Enterprise access.
## Choose the right tool
| Job | Tool | Read or write |
| ----------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------ |
| Start or replace LinkedIn authorization | `authenticate_linkedin_ads` | Saves a LinkedIn connection in HireOtto; does not change ads |
| Check token and account access | `verify_linkedin_ads_connection` | Read-only |
| Find accessible ad accounts and roles | `list_linkedin_ad_accounts` | Read-only; `refresh=true` refreshes saved account access |
| Read one account, campaign group, ad set, or creative | `list_linkedin_ads_entities` | Read-only |
| Map the complete account hierarchy | `get_linkedin_ads_hierarchy` | Read-only |
| Find valid targeting values or estimate audience size | `discover_linkedin_targeting` | Read-only; criteria building is local |
| Run performance or professional-demographic reporting | `get_linkedin_ads_report` | Read-only; may create a temporary CSV export |
| Select and upload an image interactively | `upload_linkedin_image` | Creates an image asset |
| Upload image bytes from a capable client | `upload_linkedin_image_bytes` | Creates an image asset |
| Find or inspect Media Library images | `list_linkedin_image_assets`, `get_linkedin_image_asset` | Read-only |
| Archive or restore a Media Library image | `update_linkedin_image_asset` | Write |
| Create one campaign group, ad set, or creative | `create_linkedin_ads_entities` | Write unless `validate_only=true` |
| Create a campaign hierarchy in order | `create_linkedin_campaign` | Write unless `validate_only=true` |
| Update campaign entities or delete eligible drafts | `update_linkedin_ads_entities` | Write unless `validate_only=true` |
| Check HireOtto access and usage | `get_billing_status` | Read-only |
HireOtto uses **campaign group** for LinkedIn's campaign-group object and **ad set** for the object that LinkedIn's API calls a campaign. Keep the returned IDs with every recommendation or proposed change.
## Shared inputs and safety defaults
| Input | Required | Default | Meaning |
| --------------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------ |
| `profile_id` | No | `default` | Saved LinkedIn connection; additional named profiles require Agency or enabled Enterprise access |
| `ad_account_id` | Required for account-specific tools | None | Numeric sponsored-account ID; use the value returned by account discovery |
| `validate_only` | No | `false` | Validate the proposed payload without sending the create or update request |
| `include_raw` | No | `false` | Include LinkedIn's raw entity alongside normalized fields for troubleshooting |
IDs can usually be supplied as numeric IDs or full LinkedIn URNs. Prefer IDs returned by HireOtto. For targeting, use the exact URNs returned by targeting discovery; do not invent or loosely translate entity IDs.
`validate_only=true` checks the request shape and supported rules, but it cannot prove that LinkedIn will accept a later write. Permissions, lifecycle rules, account warnings, budgets, dates, Page access, and platform-side validation are still checked when the real request runs.
## Authentication and account access
### `authenticate_linkedin_ads`
Starts LinkedIn OAuth and returns an authorization URL.
| Parameter | Required | Default | Notes |
| ------------ | -------- | --------- | ---------------------------------------------------------- |
| `profile_id` | No | `default` | Named profiles require Agency or enabled Enterprise access |
This connects LinkedIn to HireOtto. It is separate from connecting the MCP server to the AI client. The tool does not create an ad account or change campaigns.
### `verify_linkedin_ads_connection`
Checks the saved member token, Advertising API account access, and token-expiry state without changing LinkedIn Ads.
| Parameter | Required | Default |
| ------------ | -------- | --------- |
| `profile_id` | No | `default` |
Use it after OAuth, after reconnecting, or when account reads begin returning authorization errors. A failed member check or an expired refresh token can require a new authorization.
### `list_linkedin_ad_accounts`
Lists accessible ad accounts and returns the connection state, account ID, name, status, currency when available, the authenticated member's role, and whether the connection can write.
| Parameter | Required | Default | Notes |
| ------------ | -------- | --------- | ----------------------------------------------------------- |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `refresh` | No | `false` | Set to `true` after account creation or a permission change |
Possible onboarding states include:
| State | Meaning |
| ------------------------- | ------------------------------------------------------------------ |
| `not_connected` | The MCP server is connected, but no LinkedIn identity is linked |
| `connected_no_accounts` | LinkedIn is linked, but the identity has no accessible ad accounts |
| `account_lookup_failed` | Authorization exists, but account access could not be checked |
| `connected_with_accounts` | One or more ad accounts were found |
Viewer access is read-only. Write actions require a sufficient ad-account role, and sponsored-content workflows can also require access to the associated LinkedIn Page.
## Read account and campaign structure
### `list_linkedin_ads_entities`
Use this for a focused account or hierarchy read.
| Parameter | Required | Default | Notes |
| -------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Yes | None | `get_ad_account`, `list_campaign_groups`, `get_campaign_group`, `list_ad_sets`, `get_ad_set`, `list_creatives`, or `get_creative` |
| `ad_account_id` | Yes | None | Sponsored-account ID |
| `campaign_group_ids` | No | None | Filter groups or ad sets; exactly one ID for `get_campaign_group` |
| `ad_set_ids` | No | None | Filter ad sets or creatives; exactly one ID for `get_ad_set` |
| `creative_ids` | No | None | Filter creatives; exactly one ID for `get_creative` |
| `statuses` | No | None | Common group/ad-set values include `DRAFT`, `ACTIVE`, and `PAUSED` |
| `names` | No | None | Name filter where supported |
| `intended_statuses` | No | None | Creative status filter |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `include_raw` | No | `false` | Include raw LinkedIn fields |
| `page_size` | No | `100` | Clamped by LinkedIn's endpoint: up to 1,000 ad sets and up to 100 creatives per page |
| `page_token` | No | None | Continue a paged list when LinkedIn returns a token |
The tool uses 2 HireOtto credits after a successful call. ID-based reads can return per-ID errors or statuses; inspect them instead of assuming that every requested entity was found.
### `get_linkedin_ads_hierarchy`
Returns the account, campaign groups, ad sets, and creatives as one tree. Use it for orientation or reconciliation; use the focused entity tool when you need one object or a paged list.
| Parameter | Required | Default | Notes |
| ------------------ | -------- | --------- | ------------------------------------------------------------------- |
| `ad_account_id` | Yes | None | Sponsored-account ID |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `include_archived` | No | `false` | Adds archived entities to the normal active, paused, and draft view |
| `include_raw` | No | `false` | Includes raw LinkedIn payloads |
The hierarchy call uses 5 credits. It retrieves up to 100 creatives per ad set in the current workflow; use focused creative listing and pagination when an ad set can exceed that coverage.
## Discover targeting and estimate audience size
### `discover_linkedin_targeting`
This tool turns marketer-friendly audience ideas into valid LinkedIn targeting values before campaign creation.
| Parameter | Required | Default | Notes |
| -------------------- | ------------------ | --------- | ----------------------------------------------------------------------- |
| `action` | Yes | None | `list_facets`, `search_entities`, `audience_count`, or `build_criteria` |
| `facet` | For entity search | None | Targeting category to search |
| `query` | No | None | Text search within the selected facet |
| `entity_urns` | No | None | Resolve known URNs |
| `included_targeting` | For audience count | None | Friendly include map or targeting object |
| `excluded_targeting` | No | None | Friendly exclusion map or targeting object |
| `locale_language` | No | `en` | Localizes discovery results and supplies ad-set locale metadata |
| `locale_country` | No | `US` | Localizes discovery results and supplies ad-set locale metadata |
| `profile_id` | No | `default` | Saved LinkedIn connection |
Friendly facet keys include `locations`, `companies` or `employers`, `industries`, `job_titles`, `job_functions`, `seniorities`, `skills`, `company_sizes`, `schools`, `groups`, and `languages`.
```json theme={null}
{
"included_targeting": {
"locations": ["urn:li:geo:103644278"],
"seniorities": ["urn:li:seniority:4"]
},
"excluded_targeting": {
"companies": ["urn:li:organization:123456"]
}
}
```
`build_criteria` only converts a friendly map into targeting criteria; it does not validate entities with LinkedIn. `audience_count` validates every included and excluded facet and URN before requesting an estimate. Audience size is a delivery guardrail, not a quality score or reach forecast. LinkedIn requires a minimum eligible audience, while actual reach can be lower.
The tool uses 2 credits after a successful action.
HireOtto adds interface-language targeting only when you explicitly supply `languages` or `interfaceLocales`. An explicit interface locale must contain exactly one value and match the normalized ad-set locale. Use `locations` or `profileLocations` for geography.
## Run LinkedIn Ads reports
### `get_linkedin_ads_report`
Runs performance or professional-demographic reporting across the account, campaign-group, ad-set, or creative level.
| Parameter | Required | Default | Limit or behavior |
| -------------------- | -------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `ad_account_id` | Yes | None | Sponsored-account ID |
| `start_date` | Yes | None | `YYYY-MM-DD` |
| `end_date` | No | None | `YYYY-MM-DD`; specify it for a controlled comparison window |
| `level` | No | `campaign` | `account`, `campaign`, `ad_set`, or `creative` |
| `ids` | No | Whole account | IDs at the selected level |
| `pivots` | No | Level's default pivot | One to three supported LinkedIn pivots |
| `metrics` | No | Common delivery, cost, conversion, and engagement fields | Maximum 20 fields after required report fields are included |
| `time_granularity` | No | `ALL` | `ALL`, `DAILY`, `MONTHLY`, or `YEARLY` |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `output_mode` | No | `summary_and_csv` | `summary`, `summary_and_csv`, or `csv_only`; an invalid value falls back to the default |
| `limit` | No | `50` | Inline rows, 1-5,000 |
| `export_limit` | No | `5,000` | CSV rows, 1-50,000 |
| `export_ttl_minutes` | No | `30` | Link lifetime, 1-1,440 minutes |
Default metrics include `impressions`, `clicks`, `landingPageClicks`, `costInLocalCurrency`, `externalWebsiteConversions`, `likes`, `shares`, and `totalEngagements`, plus `dateRange` and `pivotValues` for interpretation.
Common pivots include `ACCOUNT`, `CAMPAIGN_GROUP`, `CAMPAIGN`, `CREATIVE`, `OBJECTIVE_TYPE`, `SERVING_LOCATION`, `IMPRESSION_DEVICE_TYPE`, and professional-demographic pivots such as `MEMBER_COMPANY`, `MEMBER_INDUSTRY`, `MEMBER_JOB_TITLE`, `MEMBER_JOB_FUNCTION`, `MEMBER_SENIORITY`, `MEMBER_COUNTRY_V2`, and `MEMBER_REGION_V2`.
The report uses 5 credits after a successful call. LinkedIn Ad Analytics does not provide pagination for this workflow. The export and inline limits cap the rows HireOtto returns; they do not create additional rows when LinkedIn returns less data.
Professional-demographic reporting is aggregated and privacy-protected. Small groups can be suppressed, and demographic results can lag standard performance reporting. Missing rows do not mean zero exposure. Some metrics are incompatible with `MEMBER_*` pivots; reduce the metric set or run one demographic pivot at a time when LinkedIn rejects a combination.
Derived rates such as CTR, CPC, CPM, conversion rate, and CPA should be calculated from the returned raw metrics. State the denominator and do not rank entities from a limited preview without checking row coverage.
## Manage image assets
### `upload_linkedin_image`
Opens an interactive file picker in an MCP Apps-capable client and uploads a JPG, PNG, or GIF to LinkedIn. It returns a reusable `urn:li:image:...` value.
| Parameter | Required | Default | Notes |
| --------------------------- | -------- | ---------------------------- | ---------------------------------------------------- |
| `ad_account_id` | Yes | None | Account that will own the image |
| `owner_urn` | No | Resolved from the ad account | Supply only if automatic advertiser resolution fails |
| `asset_name` | No | None | Optional Media Library name |
| `register_in_media_library` | No | `true` | Keep enabled for later discovery and archive/restore |
| `profile_id` | No | `default` | Saved LinkedIn connection |
The upload app works in ChatGPT and Claude web or Desktop when MCP Apps are supported. It does not currently render in Claude Code CLI or the Claude Code VS Code extension.
### `upload_linkedin_image_bytes`
Uploads image bytes without opening a UI. Use it only when the client can read, encode, and pass the original file programmatically.
| Parameter | Required | Default | Notes |
| --------------------------- | -------- | ------------------------- | ----------------------------------------------------------- |
| `ad_account_id` | Yes | None | Account that will own the image |
| `file_name` | Yes | None | File name with extension |
| `content_type` | Yes | None | `image/jpeg`, `image/png`, or `image/gif` |
| `image_base64` | Yes | None | Standard base64 with no data-URL prefix or line breaks |
| `owner_urn` | No | Resolved from the account | Supply only if automatic resolution fails |
| `asset_name` | No | None | Optional Media Library name |
| `register_in_media_library` | No | `true` | Registers the asset for later discovery and archive/restore |
| `profile_id` | No | `default` | Saved LinkedIn connection |
The decoded file limit is 8 MiB. Base64 adds roughly one-third to the payload, and client or model-context limits can be smaller. Do not ask a user to paste base64 into chat, print it, invent it, or split it across calls. If a timed-out upload might have completed, list recent images before retrying to avoid duplicates.
An image upload uses 5 credits after success. It creates an image asset, not a creative, ad set, or campaign.
### `list_linkedin_image_assets` and `get_linkedin_image_asset`
Use listing when the user refers to a recent upload or when an upload result is no longer in context.
| Tool | Parameters | Defaults and limits |
| ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `list_linkedin_image_assets` | `ad_account_id`, `count`, `start`, `media_library_status`, `profile_id` | `count=10`, clamped to 1-1,000; `start=0`; status `ACTIVE`; use `ARCHIVED` or `null` to recover other assets |
| `get_linkedin_image_asset` | `ad_account_id`, `image_urn`, `profile_id` | Exact image URN required |
Listing and getting an image each use 1 credit after success.
### `update_linkedin_image_asset`
Sets `media_library_status` to `ARCHIVED` or `ACTIVE`. Archiving removes the item from the default active listing but does not permanently delete the binary, delete creatives, or pause ads. Only Media Library-registered images are manageable through this tool.
| Parameter | Required | Default |
| ---------------------- | -------- | --------- |
| `ad_account_id` | Yes | None |
| `image_urn` | Yes | None |
| `media_library_status` | Yes | None |
| `profile_id` | No | `default` |
| `validate_only` | No | `false` |
Validation uses 1 credit; the actual archive or restore uses 5. Local validation does not prove the asset belongs to the account or that its processing state permits the change.
## Create campaign entities
### `create_linkedin_ads_entities`
Creates one campaign group, ad set, or creative.
| Parameter | Required | Default | Notes |
| ------------------- | --------------------- | --------- | -------------------------------------------------------------- |
| `action` | Yes | None | `create_campaign_group`, `create_ad_set`, or `create_creative` |
| `ad_account_id` | Yes | None | Sponsored-account ID |
| `fields` | Yes | None | Settings for the selected action |
| `campaign_group_id` | For ad-set creation | None | Existing parent group |
| `ad_set_id` | For creative creation | None | Existing parent ad set |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `validate_only` | No | `false` | Validate without creating the object |
Validation uses 1 credit; a successful create uses 5.
#### Campaign-group fields
`name` is required. Common fields include `status`, `start`, `end`, daily or total budget, `currency_code`, `objective_type`, budget-optimization strategy, and bid strategy. New workflows should normally use `DRAFT` until review is complete.
#### Ad-set fields
An ad set requires a parent campaign group, `name`, targeting, and a budget. Common fields include campaign type, ad format, objective, cost type, bid strategy, optimization goal, daily or total budget, currency, bid amount, dates, locale, audience expansion, offsite delivery, pacing, and political intent.
Important constraints:
* Choose the ad format carefully. LinkedIn fixes formats such as standard update, single video, and carousel when the ad set is created; use a new ad set to change format.
* Sponsored Content, Dynamic Ads, and Lead Gen require an associated advertiser entity. HireOtto normally resolves it from the account.
* Dynamic Ads require both daily and total budgets plus an ad format.
* A total-budget-only ad set requires an end date.
* Connected TV requires offsite delivery.
* Lead Generation cannot enable offsite delivery.
* Use targeting discovery before creation so every included and excluded value is a valid LinkedIn URN.
#### Creative fields
The supported first-class path is a normal single-image Direct Sponsored Content ad. Supply an available `image_urn` plus `commentary`; optionally add `headline`, `landing_page`, `cta_label`, `image_alt_text`, internal `name`, and `intended_status`.
When a landing page is present, the CTA defaults to `LEARN_MORE`. Creation should normally use `DRAFT`. HireOtto builds the advertiser and Direct Sponsored Content context, so do not manually construct advanced inline content for a standard single-image ad.
`validate_only=true` still performs read-only targeting-URN validation for ad sets and availability checks for first-class image creatives. It does not reserve IDs or guarantee that a later write will pass LinkedIn's permission and lifecycle checks.
### `create_linkedin_campaign`
Creates or reuses a campaign group, then creates an ad set and optional creatives in order.
| Parameter | Required | Default | Notes |
| ---------------- | -------- | --------- | -------------------------------------------------------- |
| `ad_account_id` | Yes | None | Sponsored-account ID |
| `ad_set` | Yes | None | Complete ad-set settings |
| `campaign_group` | No | None | Existing `campaign_group_id` or settings for a new group |
| `creatives` | No | None | List of creative objects |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `validate_only` | No | `false` | Validate the hierarchy without creating it |
Validation uses 1 credit; a successful hierarchy create uses 10. Creation defaults to draft behavior.
This workflow is not transactional. If a child object fails, parents already created remain in LinkedIn. Keep every returned ID, inspect `partial_result`, and resume from the failed step with the single-entity tool. Do not rerun the entire hierarchy blindly.
After approval, ask for draft creation explicitly and require the returned campaign-group, ad-set, creative, and image IDs. Read the saved hierarchy back before activation.
## Update campaign entities
### `update_linkedin_ads_entities`
Updates campaign groups, ad sets, or creatives; applies batch updates; updates a full campaign; adds targeting exclusions safely; or deletes eligible draft ad sets and creatives.
| Parameter | Required | Default | Notes |
| --------------- | ------------------------- | --------- | -------------------------------------------------- |
| `action` | Yes | None | Select one supported update or draft-delete action |
| `ad_account_id` | Yes | None | Sponsored-account ID |
| `entity_id` | For single-entity actions | None | Campaign-group, ad-set, or creative ID |
| `updates` | For updates | None | Complete fields for the selected action |
| `profile_id` | No | `default` | Saved LinkedIn connection |
| `validate_only` | No | `false` | Validate without writing |
Supported actions include:
* `update_campaign_group`
* `update_ad_set`
* `add_targeting_exclusions`
* `update_creative`
* `batch_update_ad_sets`
* `batch_update_creatives`
* `update_full_campaign`
* `delete_draft_ad_set`
* `delete_draft_creative`
Validation uses 1 credit; a successful update or eligible draft deletion uses 5.
Use `add_targeting_exclusions` when only adding exclusions. A partial friendly include or exclude map sent through `update_ad_set` can replace the existing targeting configuration. For any broader targeting edit, read the full current targeting, resolve every new entity, estimate the revised audience, and review the complete diff before writing.
LinkedIn enforces lifecycle transitions. Activation can fail when a parent remains in draft, dates are stale, the account cannot serve, the creative is not eligible, or the connected role lacks permission. A validated payload does not override these platform rules.
After any approved write, read the object back and compare the live value with the proposed value. Keep activation separate from budget, targeting, creative, date, and bid changes so each decision remains reviewable.
## Check plan and credits
### `get_billing_status`
Returns the current HireOtto plan, billing or trial period, included and used credits, remaining credits when limited, and feature entitlements. It is read-only and does not consume credits.
The current plan model is:
* Free trial: 200 credits or 14 days, whichever comes first
* Starter: 2,000 credits per month
* Pro: 5,000 credits per month
* Agency: unlimited credits, two included seats, and multiple connected profiles
LinkedIn Ads is included on every tier. When a tool is blocked, check for expired trial or billing periods, inactive billing, exhausted credits, a disabled LinkedIn entitlement, or an Agency-only profile request.
## Credit costs
| Successful action | Credits |
| --------------------------------------------------------- | ------: |
| Focused entity read | 2 |
| Full hierarchy read | 5 |
| Targeting discovery, criteria building, or audience count | 2 |
| LinkedIn Ads report | 5 |
| List or get one image asset | 1 |
| Upload an image | 5 |
| Validate an image archive or restore | 1 |
| Archive or restore an image | 5 |
| Validate one entity create or update | 1 |
| Create or update one entity | 5 |
| Validate a full campaign hierarchy | 1 |
| Create a full campaign hierarchy | 10 |
Authorization, connection verification, account discovery, and billing-status checks are not separately charged in the current workflow. Credits are deducted only after a successful charged action. Agency has unlimited credits, but platform permissions and lifecycle constraints still apply.
## Common failures and recovery
| Failure | What it usually means | What to do |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| No tools appear | The MCP endpoint, client authorization, or cached tool list is incomplete | Confirm the endpoint ends in `/mcp`, finish client OAuth, enable the connection, and refresh or reconnect the client |
| No accounts appear | The LinkedIn identity has no accessible account or access has not refreshed | Verify the login in Campaign Manager and rerun account listing with `refresh=true` |
| Read works but write fails | Viewer or insufficient role, missing Page access, account warning, or lifecycle restriction | Check role, `can_write`, Page access, billing, dates, parent status, and Campaign Manager warnings |
| Empty report | No activity, wrong IDs or dates, incompatible readable scope, privacy suppression, or reporting delay | Confirm the account, entity IDs, complete date window, pivot, and metric compatibility |
| Targeting search is ambiguous | Several LinkedIn entities match the business description | Review names and URNs; never choose an ID from text similarity alone |
| Audience count fails | At least one include or exclude value could not be resolved | Search the failing facet again and rebuild the criteria from returned URNs |
| Image upload fails | Unsupported type, excessive payload, inaccessible file bytes, processing failure, or permission issue | Use JPG, PNG, or GIF; keep decoded bytes under 8 MiB; use the interactive app when possible; list recent assets before retrying |
| Creation partially succeeds | A parent was created before a child failed | Preserve returned IDs, inspect the live hierarchy, and resume only the failed step |
| Update is rejected | The field is immutable, incompatible with the ad format, or blocked by lifecycle rules | Read the object, validate a smaller change, and use a new ad set when the format cannot change |
| CSV link has expired | The requested export lifetime ended | Rerun the same read-only report with a suitable TTL up to 1,440 minutes |
## Current boundaries
* Campaign Manager remains the final place to preview rendering, Page identity, billing, review status, and account warnings.
* HireOtto does not currently create LinkedIn Lead Gen Forms.
* The image-upload workflow does not imply support for video or document-ad uploads.
* Creating a creative does not install or validate the LinkedIn Insight Tag, Google Tag Manager, or the destination page.
* Reporting and demographic data can be delayed, incomplete, or privacy-suppressed.
* `validate_only` reduces avoidable payload errors but does not guarantee a later write.
* Create and update workflows are not substitutes for practitioner approval of objective, budget, targeting, copy, destination, measurement, or activation.
## Recommended operating sequence
1. Connect the server and authorize LinkedIn.
2. List accounts with `refresh=true`; confirm account ID, currency, role, and `can_write`.
3. Read the hierarchy and preserve exact parent and child IDs.
4. Run the smallest report or targeting request that answers the current question.
5. Resolve targeting URNs and estimate audience size before campaign creation or targeting updates.
6. Reuse or upload an image and confirm that LinkedIn reports it as available.
7. Validate the complete proposed configuration.
8. Create new objects as drafts and keep every returned ID.
9. Read the live objects back and preview the creative in Campaign Manager.
10. Verify tracking and activate only after named human approval.
This sequence separates platform access, evidence, construction, and activation. It also gives you a clear recovery point if LinkedIn accepts one step and rejects the next.
## Related documentation
* [Connect LinkedIn Ads](/linkedin-ads/quickstart)
* [HireOtto feature and entitlement matrix](/feature-entitlement-matrix)
* [Troubleshoot HireOtto connections and permissions](/troubleshooting)
* [LinkedIn Ads product page](https://hireotto.com/linkedin-ads-mcp)
* [HireOtto pricing](https://hireotto.com/pricing)
* [LinkedIn reporting API overview](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting)
* [LinkedIn audience-count guidance](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/audience-counts)
* [LinkedIn professional-demographic reporting thresholds](https://www.linkedin.com/help/lms/answer/a421805)
# Manage Google Ads Conversions with AI – Video Walkthrough
Source: https://docs.hireotto.com/manage-google-ads-conversions-with-ai
Review Google Ads conversion tracking, import GA4 events, and create or update conversion actions in Claude with HireOtto.
Review your conversion tracking setup, import eligible GA4 events, and create or update native website conversion actions without navigating through multiple Google Ads screens.
## What this walkthrough covers
* Reviewing auto-tagging and conversion tracking ownership
* Checking whether Google Ads is connected to GA4
* Separating imported GA4 events from events available to import
* Importing a GA4 event as a secondary conversion
* Creating a native website conversion action
* Updating value, optimization, and conversion-window settings
* Making a partial update without changing other fields
# Google Ads Report Output Modes: Summary and CSV
Source: https://docs.hireotto.com/output-modes
Learn when to use summary, summary_and_csv, and csv_only output modes for Google Ads reports, audits, and exports in HireOtto.
***
## The three modes
### `summary` (default)
Returns results inline in your AI client — readable in the conversation, no download required. Limited to 50 rows by default (you can ask for more).
Best for: quick checks, reviewing a handful of campaigns, anything you want to read and act on immediately.
```text theme={null}
Show campaign performance for the last 30 days.
```
### `summary_and_csv`
Returns the inline summary **plus** a signed download link for a CSV file. The inline view gives you a fast read; the CSV has the full export (up to 5,000 rows by default).
Best for: when you want to glance at results in chat and also download the full data for a spreadsheet or report.
```text theme={null}
Pull keyword performance for the last month and also export to CSV.
```
### `csv_only`
Returns only the CSV download link, with minimal metadata in-chat. Nothing gets printed inline.
Best for: automation, large accounts, or any time you're pulling data you'll use elsewhere — the AI client doesn't need to process thousands of rows.
```text theme={null}
Export search terms report for last 30 days to CSV only.
```
***
## CSV download links
CSV links are signed and expire after **30 minutes** by default. If you need more time, ask for a longer TTL:
```text theme={null}
Export campaign performance to CSV with a 2-hour link.
```
The file itself may persist longer on the server, but the link won't work after the TTL. Download it before it expires.
***
## Controlling how many rows you get
**Inline limit** — how many rows appear in the conversation (default: 50). To see more or fewer:
```text theme={null}
Show me the top 10 campaigns by cost — last 30 days.
```
```text theme={null}
Show me all campaigns, no row limit.
```
**Export limit** — how many rows go into the CSV (default: 5,000). For very large accounts:
```text theme={null}
Export up to 10,000 search terms to CSV.
```
Note: the export limit also controls how many rows are fetched from Google Ads, so setting it very high on large accounts can slow down the response.
***
## When to use which mode
| Situation | Mode |
| :------------------------------------------------------------------------------ | :------------------------------ |
| Checking performance on 5–10 campaigns | `summary` |
| Weekly review you'll paste into a report | `summary_and_csv` |
| Daily audit across 50+ accounts via automation | `csv_only` |
| Finding the top 3 wasted search terms to act on now | `summary` |
| Pulling the full search terms list for analysis | `summary_and_csv` or `csv_only` |
| Running a [Make.com](http://Make.com) automation that processes data downstream | `csv_only` |
***
## Specifying output mode in a prompt
You can say it naturally — HireOtto understands intent:
```text theme={null}
Get last month's campaign performance. Export to CSV.
```
```text theme={null}
Pull the search terms report — I just want the CSV, don't show it in chat.
```
```text theme={null}
Show me keyword performance for the last 7 days (top 20 by cost).
```
Or be explicit if you prefer:
```text theme={null}
Get campaign performance for LAST_30_DAYS, output mode: csv_only, export limit 10000.
```
## Used in these workflows
* [Analyze Google Ads performance reports with AI](/guides/reporting)
* [Google Ads Account Audit with AI](/guides/google-ads-account-audit-with-ai)
* [Manage Negative Keywords in Google Ads with AI](/guides/manage-negative-keywords-in-google-ads-with-ai)
* [Manage Performance Max Campaigns with AI](/guides/manage-performance-max-campaigns)
# Connect Google Ads to Claude, ChatGPT, and AI Tools
Source: https://docs.hireotto.com/quickstart
Set up HireOtto’s Google Ads MCP server in under 5 minutes. Connect your AI assistant, authorize Google Ads, and run your first campaign query.
HireOtto is a remote MCP server, so there is nothing to download or install. You add the HireOtto endpoint URL to your AI tool's configuration, authorize your Google Ads account once via OAuth, and then start managing campaigns in plain language. The steps below walk you through the full setup.
For client-specific screenshots and setup details, use the dedicated guide: [Connect HireOtto to Claude, ChatGPT, and Make](/setup/connect-ai-tool).
Your endpoint URL looks like this:
```text theme={null}
https://googleads.hireotto.com/mcp
```
Keep this URL handy — you'll paste it into your AI tool's config in the next step.
Choose your AI tool below and follow the configuration steps.
After saving the config file, restart your AI tool so it picks up the new server.
* **Claude Web** — Settings → Connectors → Add Custom Connector.
* **ChatGPT** — Settings → Apps → Advanced settings → Enable Developer Mode (this is to allow adding custom servers) Once enabled, you'll see a 'Create app' button. Use that, paste the server URL, select `OAuth` as the Authentication and Create.
* [**Make.com**](http://Make.com) — open an AI agent → click '+' icon next to MCP → Add→ select by searching `googleads` . You don't need the server URL here as HireOtto is already integrated with Make - neat right!
Once the server is added, you'll see a Google sign‑in window. This is a quick handshake so HireOtto can recognize your workspace. Simply complete the flow.
HireOtto needs read/write access to your Google Ads account. Initiate a new chat in your AI tool and say something like `Connect Google Ads` or `Authenticate Google Ads.`
Follow the link your assistant provides, sign in with the Google account that has access to your Google Ads account, and grant the requested permissions on the Google consent screen. Select and save the accounts you want to access via HireOtto.
Open a new conversation in your AI tool and send this message:
```text theme={null}
List my Google Ads campaigns
```
Your assistant should respond with a table or list showing your campaigns, their statuses, and their daily budgets — something like:
```text theme={null}
Here are your Google Ads campaigns:
| Campaign | Status | Daily budget | Impressions (7d) |
|------------------------|---------|--------------|-----------------|
| Brand - Search | Enabled | $50.00 | 14,320 |
| Competitor - Search | Enabled | $30.00 | 8,910 |
| Retargeting - Display | Paused | $20.00 | 0 |
```
If you see your campaigns, HireOtto is connected and working. If you see an error, check that you saved the config file correctly and restarted your AI tool.
Once connected, try these prompts to explore what HireOtto can do:
* "What was my total ad spend last week?"
* "Pause all campaigns with a CTR below 1% in the last 30 days"
* "Increase the budget for my Brand campaign by 20%"
* "Add the keyword “best running shoes” as phrase match to my Search campaign with a max CPC of \$1.50"
## Optional: Connect Google Search Console
If you want to analyze organic search data, connect Google Search Console separately. In your AI assistant, ask:
```text theme={null}
Connect my Google Search Console account.
```
HireOtto will return an authentication link. Open it, choose the Google account that has access to your Search Console properties, and approve access.
Then verify the connection:
```text theme={null}
Show me the Search Console sites I have access to.
```
For examples and reporting workflows, see [Google Search Console MCP reporting](/guides/google-search-console).
## What to try next
Once your connection works, try one of these workflows:
* [Pull Google Ads performance reports](/guides/reporting)
* [Run a Google Ads account audit](/guides/google-ads-account-audit-with-ai)
* [Create a Google Search campaign with AI](/guides/create-a-google-ads-campaign-with-ai)
* [Manage negative keywords](/guides/manage-negative-keywords-in-google-ads-with-ai)
# Connect Google Search Console to Claude, ChatGPT, and AI tools
Source: https://docs.hireotto.com/search-console/quickstart
Connect HireOtto to Google Search Console, authorize the right Google login, verify accessible properties, and run a safe first organic-search request.
Connect Search Console in two stages: add HireOtto's Google Ads MCP server to your AI client, then authorize Search Console separately with the Google login that can access your properties. Verify the connection by listing sites before requesting a report or URL inspection.
Search Console access is read-only. HireOtto can retrieve properties, performance data, submitted sitemaps, and URL-indexing information, but it cannot add properties, submit sitemaps, request indexing, or change Search Console settings.
## What you need
* An AI client that supports remote MCP servers over HTTP and OAuth
* A HireOtto trial or paid plan
* A Google login that can open the Search Console property you need
* Permission to the relevant domain property or URL-prefix property
You do not need a Google Cloud project, API key, JSON credentials, terminal, or local server.
Search Console is available now on HireOtto's Free, Starter, Pro, and Agency plans. The trial ends after 14 days or 200 credits, whichever comes first. Starter includes 2,000 monthly credits, Pro includes 5,000, and Agency includes unlimited credits.
## 1. Add the HireOtto connection
Search Console tools currently use HireOtto's Google Ads MCP connection:
```text theme={null}
https://googleads.hireotto.com/mcp
```
If that server is already connected and its tools are visible, continue to the Search Console authorization step. You do not need to add it again.
If it is not connected:
1. Open your AI client's Apps, Connectors, Tools, Integrations, or MCP settings.
2. Add a remote HTTP MCP server.
3. Paste `https://googleads.hireotto.com/mcp`.
4. Complete the HireOtto sign-in.
5. Enable the connection in the current chat or agent.
For current client-specific menus, see [Connect a HireOtto server to an AI client](/setup/connect-ai-tool).
Do not configure HireOtto as a local command or stdio process. It is a hosted remote MCP service.
## 2. Authorize Search Console separately
In the connected AI client, ask:
HireOtto returns a Google authorization link. Open it, choose the Google login that has access to the required Search Console properties, and grant the requested permission.
This step is required even if Google Ads already works through the same HireOtto server. Google Ads and Search Console are separate Google services with separate authorizations.
After Google authorization, complete the HireOtto connection confirmation shown in the browser. HireOtto then attempts to retrieve the sites available to that Google login.
## 3. Verify accessible properties
Return to your AI client and ask:
Use the returned property value exactly in later requests. HireOtto supports both Search Console property formats:
```text theme={null}
sc-domain:example.com
```
```text theme={null}
https://www.example.com/
```
The first is a domain property. The second is a URL-prefix property. A URL-prefix property covers only URLs under that exact protocol and prefix, so `http`, `https`, `www`, and non-`www` variants can be different properties.
Review the returned property and permission level before continuing. HireOtto cannot expand the access granted to the connected Google login.
## 4. Run a small first request
Start with a narrow, completed date range:
Confirm:
* The property is the one you intended to use
* The date range is correct
* The result contains data you recognize
* The dimensions and filters match the question
Then continue to [Google Search Console MCP reporting with HireOtto](/guides/google-search-console) for reporting, exports, filters, URL inspection, sitemaps, fresh data, and paid-and-organic workflows.
## Authentication parameters and defaults
### Connect Search Console
| Parameter | Default | Accepted value | When to use it |
| ------------ | --------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `profile_id` | `default` | A short profile name without `:` | Omit for the normal connection. Agency users can name another profile when authorizing a different Google login. |
Use a named profile only when you need to connect a different Google identity, such as a second agency login. Giving the same Google login another profile name does not reveal additional properties.
Current public plan guidance reserves multiple connected profiles for Agency. Use the default profile on Free, Starter, and Pro.
### List Search Console properties
| Parameter | Default | Accepted value | When to use it |
| ---------------- | --------- | --------------------------------------- | -------------------------------------------------------- |
| `action` | Required | `list_sites` | Lists properties available to the connected Google login |
| `site_url` | Not used | — | Omit when listing properties |
| `inspection_url` | Not used | — | Omit when listing properties |
| `language_code` | `en-US` | A supported language code | Relevant to URL inspection, not property listing |
| `profile_id` | `default` | `default`, or an eligible named profile | Selects the connected Google login |
The property list returns each available `site_url` and the Google permission level associated with it.
## What the connection can access
After setup, HireOtto can read:
* Search Console properties available to the connected Google login
* The permission level returned for each property
* Search performance for supported dimensions and search types
* URL-indexing details available through Google's URL Inspection API
* Submitted sitemaps for a selected property
It cannot:
* Add or verify a Search Console property
* Grant access to another person
* Submit, remove, or modify a sitemap
* Request that Google index or recrawl a URL
* Change canonical, robots, crawl, or indexing settings
* Edit website content or tags
* Retrieve properties the connected Google login cannot access
Search Console access is separate from Google Ads, Tag Manager, and GA4. Connecting one service does not grant access to another.
## Profiles and agency access
The default profile represents the normal connected Google login. Agency supports multiple named profiles for users who manage properties across different Google identities.
A named profile is useful when:
* Different clients grant access to different Google logins
* The required property is absent from the default login
* An agency needs to keep separate client identities explicit
Use clear names such as `client_name_gsc`. Profile names cannot contain `:`.
When switching profiles, list properties again. Do not reuse a `site_url` until you confirm that the selected profile can access it.
## Common setup failures
### The HireOtto connection works, but Search Console asks me to authenticate
The MCP connection and the Search Console authorization are separate. Ask to connect Search Console and complete the newest Google authorization link.
### Google authorization succeeded, but no properties appear
Check that the chosen Google login can open the required property directly in Search Console. A successful authorization proves the identity was connected; it does not guarantee that the identity has access to any property.
If the property belongs to another login, reconnect with the correct Google identity. Agency users can create a separate named profile.
### The wrong property variant appears
Domain and URL-prefix properties are different. List the available properties and copy the returned `site_url` exactly. Confirm protocol, subdomain, and trailing slash for URL-prefix properties.
### I can see a property in Search Console but not through HireOtto
Confirm that the same Google login was authorized in HireOtto. If access was granted recently, reconnect Search Console or list properties again after Google's permission change has propagated.
### The authorization link fails or expires
Ask HireOtto to connect Search Console again and open the newest link. Complete the consent flow in the same browser session, then return to the original AI client.
### HireOtto keeps asking me to reconnect
The Google authorization may have expired or been revoked. A password change or organization security policy can also invalidate access. Reconnect Search Console and retry the property list before running a report.
### No Search Console tools appear
* Confirm that the endpoint is `https://googleads.hireotto.com/mcp`
* Finish the HireOtto sign-in
* Enable the connection in the current chat or agent
* Refresh or rescan the tool list
* Reconnect the MCP server if the client has cached an older tool list
### A named profile is blocked
Multiple connected profiles are an Agency feature in current public plan guidance. Use the default profile or check [HireOtto pricing](https://hireotto.com/pricing).
### The request is blocked after setup
Check the HireOtto trial, credit balance, billing status, and Search Console entitlement. Authentication does not override plan or usage limits.
## Safe verification prompts
### Verify the connected identity
### Confirm a client property
### Test reporting access
### Test URL inspection access
## Disconnect Search Console
To stop using the connection:
1. Disconnect or remove the HireOtto server in your AI client if you no longer need any tools exposed through that server.
2. Revoke HireOtto's Search Console access from your Google Account when you want to remove the Google authorization.
Removing the MCP connection and revoking Google's permission are separate actions.
## Next steps
* [Run Search Console reports and URL inspections](/guides/google-search-console)
* [Review HireOtto plans and credits](/credits-and-billing)
* [Troubleshoot a HireOtto connection](/troubleshooting)
* [Review Search Console product capabilities](https://hireotto.com/search-console-mcp)
# Google Search Console MCP tools reference
Source: https://docs.hireotto.com/search-console/tools-reference
Discover Search Console properties, inspect indexing, list sitemaps, and query organic performance with HireOtto.
Use HireOtto's read-only Search Console tools to find the properties available to your Google login, review submitted sitemaps, inspect Google's indexed version of a URL, and retrieve organic search performance from an MCP-capable AI client.
Search Console tools currently use HireOtto's Google Ads MCP endpoint, but Search Console has its own Google authorization. Connecting Google Ads does not automatically connect Search Console.
```text theme={null}
https://googleads.hireotto.com/mcp
```
| Tool | Use it for |
| -------------------------------- | ------------------------------------------------------------------- |
| `authenticate_search_console` | Start or renew Search Console authorization |
| `search_console_resources` | List properties, list submitted sitemaps, or inspect an indexed URL |
| `get_search_console_performance` | Retrieve clicks, impressions, CTR, and average position |
If you have not connected Search Console yet, follow the [Search Console quickstart](/search-console/quickstart).
## Availability and access
| Item | Current behavior |
| --------------------------------- | ------------------------------------------------- |
| Availability | Available now on Free, Starter, Pro, and Agency |
| Scope | Read-only |
| Default profile | `default` |
| Additional named profiles | Agency, according to current public plan guidance |
| Resource and performance requests | 5 HireOtto credits per successful request |
| Authentication request | Does not retrieve Search Console data |
HireOtto can read properties, permission levels, performance data, submitted sitemaps, and URL-indexing information available to the connected Google login. It cannot add or verify properties, grant access, submit or remove sitemaps, request indexing, run a live URL test, change Search Console settings, or edit a website.
Search Console access follows the connected Google identity. HireOtto cannot reveal a property or URL that the selected Google login is not permitted to access.
## Authentication
### Authenticate Search Console
Starts the separate Google authorization flow for Search Console and returns a link for the user to open.
| Parameter | Required | Default | Accepted value |
| ------------ | -------: | --------- | -------------------------------- |
| `profile_id` | No | `default` | A short profile name without `:` |
Omit `profile_id` for the normal connection. Under current public plan guidance, Agency users can name an additional profile when they need to authorize another Google login.
Connect my Google Search Console account. After I authorize it, list the properties available to the connected Google login and include my permission level for each property.
Authentication can succeed even when the Google login has no Search Console properties. Verify the connection by listing properties before requesting a report or URL inspection.
## Search Console resources
Use the resource tool to list accessible properties, list submitted sitemaps, or inspect Google's indexed version of a URL.
### Parameters
| Parameter | Required | Default | Accepted value |
| ---------------- | ----------: | --------- | ------------------------------------------------------------ |
| `action` | Yes | — | `list_sites`, `list_sitemaps`, or `inspect_url` |
| `site_url` | Conditional | — | A property value returned by `list_sites` |
| `inspection_url` | Conditional | — | A fully qualified URL under `site_url` |
| `language_code` | No | `en-US` | A supported BCP 47 language code for URL-inspection messages |
| `profile_id` | No | `default` | `default` or an eligible named profile |
### `list_sites`
Lists the Search Console properties available to the selected Google login. Each result includes the exact `site_url` and Google's permission level for that property.
Search Console uses two property formats:
```text theme={null}
sc-domain:example.com
https://www.example.com/
```
The first is a domain property. The second is a URL-prefix property. For a URL-prefix property, protocol, subdomain, and trailing slash matter. Copy the returned value exactly into later requests.
List the Search Console properties available to my default profile. Include the exact site\_url and permission level for each property. Do not run a performance report.
### `list_sitemaps`
Lists sitemaps submitted for a selected Search Console property. `site_url` is required.
The response contains the sitemap records returned by Google, which may include submission and download details, status, warnings, errors, and sitemap content summaries. This action does not submit, modify, remove, fetch, or validate a sitemap on the live website.
For Search Console property sc-domain:example.com, list the submitted sitemaps. Summarize their latest submission and download status, warnings, and errors. Do not submit or remove anything.
### `inspect_url`
Returns Google's indexed information for one URL. Both `site_url` and `inspection_url` are required. `inspection_url` must be a complete URL under the selected property.
The summarized response includes:
* Verdict and coverage state
* Robots.txt and indexing states
* Page-fetch state
* Last crawl time
* Google-selected canonical
* User-declared canonical
* Additional URL Inspection details returned by Google
URL inspection reports the version currently known in Google's index. It does not test the live URL, request indexing, recrawl the page, or change canonical and robots settings.
For Search Console property sc-domain:example.com, inspect [https://www.example.com/pricing](https://www.example.com/pricing). Return Google's verdict, coverage state, robots.txt state, indexing state, page-fetch state, last crawl time, and Google-selected versus user-declared canonical. Do not request indexing or change anything.
## Search performance
Use the performance tool for query, page, country, device, date, hour, and search-appearance reporting. It returns clicks, impressions, CTR, and average position for the requested dimensions.
### Required parameters
| Parameter | Description |
| ------------ | ------------------------------------------------------------------------ |
| `site_url` | Exact Search Console property value, preferably copied from `list_sites` |
| `start_date` | Inclusive start date in `YYYY-MM-DD` format |
| `end_date` | Inclusive end date in `YYYY-MM-DD` format |
Search Console interprets reporting dates in Pacific Time. For stable reporting, end the range at yesterday or earlier unless you deliberately want fresh or hourly data.
### Reporting parameters and defaults
| Parameter | Default | Accepted value or range |
| ------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `dimensions` | `["query"]` | Any supported combination of `query`, `page`, `country`, `device`, `date`, `hour`, and `searchAppearance` |
| `search_type` | `web` | `web`, `image`, `video`, `news`, `discover`, or `googleNews` |
| `dimension_filter_groups` | None | A JSON string, one filter-group object, or an array of filter-group objects |
| `aggregation_type` | Google default (`auto`) | `auto`, `byPage`, `byProperty`, or the eligible News Showcase option |
| `data_state` | Finalized data | `final`, `all`, or `hourly_all` |
| `output_mode` | `summary_and_csv` | `summary`, `summary_and_csv`, or `csv_only` |
| `limit` | `50` | 1–5,000 inline rows |
| `export_limit` | `25,000` | 1–25,000 exported rows |
| `export_ttl_minutes` | `30` | 1–1,440 minutes |
| `profile_id` | `default` | `default` or an eligible named profile |
Values outside the supported numeric ranges are normalized to the nearest boundary. An unsupported output mode falls back to `summary_and_csv`.
### Dimensions
| Dimension | Use it to review |
| ------------------ | -------------------------------------------------------------- |
| `query` | Search terms that produced organic impressions or clicks |
| `page` | Landing-page performance |
| `country` | Geographic performance; results use three-letter country codes |
| `device` | `DESKTOP`, `MOBILE`, or `TABLET` performance |
| `date` | Daily trends |
| `hour` | Hourly trends when used with `data_state="hourly_all"` |
| `searchAppearance` | Search-result features available for the selected property |
The order of dimensions determines the order of the grouping keys. More granular combinations produce more rows and can increase Search Console query load.
### Search types
* `web` covers the combined All tab in Google Search.
* `image` covers Image Search.
* `video` covers video search results.
* `news` covers the News tab in Google Search.
* `discover` covers Google Discover.
* `googleNews` covers news.google.com and the Google News app, not the News tab in Google Search.
### Filters
Filter groups use this shape:
```json theme={null}
[
{
"groupType": "and",
"filters": [
{
"dimension": "country",
"operator": "equals",
"expression": "USA"
},
{
"dimension": "query",
"operator": "contains",
"expression": "pricing"
}
]
}
]
```
Supported filter dimensions are `country`, `device`, `page`, `query`, and `searchAppearance`. Supported operators are:
* `equals`
* `contains`
* `notEquals`
* `notContains`
* `includingRegex`
* `excludingRegex`
Only `and` filter groups are supported. `equals` is case-sensitive for page and query filters. `contains` and `notContains` are not case-sensitive. Regex filters use RE2 syntax.
For Search Console property sc-domain:example.com, show organic queries in the United States containing "pricing" for the previous 90 complete days. Use dimensions=\["query"], search\_type="web", country equals USA, and query contains pricing. Return the top 50 rows inline and export up to 25,000 rows to CSV.
### Aggregation
Usually omit `aggregation_type` and let Search Console choose automatically.
* Use `byPage` to aggregate by canonical page URI.
* Use `byProperty` to aggregate at property level.
* Do not use `byProperty` when grouping or filtering by page.
* `byProperty` is not available for Discover or Google News reports.
* The News Showcase aggregation is valid only for eligible News Showcase requests with the required search appearance and search type.
An incompatible aggregation request fails rather than silently changing the requested aggregation.
### Final, fresh, and hourly data
| `data_state` | Behavior |
| ------------------ | --------------------------------------------------- |
| Omitted or `final` | Finalized data only |
| `all` | Includes fresh daily data that may still change |
| `hourly_all` | Includes hourly data; use with the `hour` dimension |
Use finalized data for routine reporting. Treat fresh and hourly rows as directional because Google may still be collecting and processing them.
For Search Console property sc-domain:example.com, show performance by hour for yesterday. Use dimensions=\["hour"], data\_state="hourly\_all", and search\_type="web". Label incomplete data as directional and keep the result inline.
### Output modes
| Mode | Returned output | Best for |
| ----------------- | ---------------------------------------------- | ---------------------------------- |
| `summary` | Inline rows only, capped by `limit` | Quick checks and small comparisons |
| `summary_and_csv` | Inline rows plus a signed CSV link | Most reporting workflows |
| `csv_only` | CSV metadata and link with minimal inline data | Large pulls and spreadsheet work |
CSV links expire after `export_ttl_minutes`. No CSV is created when a report returns zero rows. Rerun the request if a link expires.
HireOtto makes one Search Console request per performance call and can retrieve at most 25,000 rows. Google does not guarantee every possible row; Search Console returns top rows within its internal limits. The tool does not currently expose pagination beyond the first 25,000 rows.
Rows are generally sorted by clicks in descending order. Reports grouped by date are returned chronologically. CTR is returned as a decimal from 0 to 1, and position is the average position supplied by Search Console.
## Practical workflows
### Find organic opportunities for paid search
For Search Console property sc-domain:example.com, retrieve the top non-brand organic queries from the previous 90 complete days with clicks, impressions, CTR, and average position. Then compare those queries with the Google Ads keywords and search terms I can access. Preserve the Search Console and Google Ads metrics separately, identify meaningful coverage gaps, and return recommendations for review. Do not change either platform.
### Review pages by country and device
For Search Console property sc-domain:example.com, show page performance for the previous 28 complete days using dimensions=\["page","country","device"]. Return the top 50 rows inline, export up to 25,000 rows, and summarize material mobile-versus-desktop or market differences without treating low-volume rows as conclusive.
## Common failures
### Search Console is not connected
Run the authentication request and complete the newest Google authorization link. Search Console authorization is separate from the MCP connection and from Google Ads authorization.
### No properties are returned
Confirm that the same Google login can open the required property directly in Search Console. Successful authorization proves that the identity was connected; it does not prove that the identity has access to a property.
### A named profile is blocked
Use the default profile or confirm that the account has multiple-profile access. Current public plan guidance reserves additional named profiles for Agency.
### The property or URL is rejected
List properties again and copy the exact `site_url`. For a URL-prefix property, confirm the protocol, subdomain, and trailing slash. For URL inspection, confirm that the full `inspection_url` belongs to the selected property.
### A report returns no rows
Check the property, date range, search type, dimensions, and filters. A successful empty response can mean there was no matching data, a filter was too narrow, the selected profile cannot access the intended property, or Search Console has not finalized recent data.
### A parameter combination fails
Check for an unsupported dimension or search type, an invalid date, a filter with the wrong shape, or an incompatible aggregation. Avoid `byProperty` when a page dimension or page filter is present.
### A quota error appears
Wait before retrying, shorten the date range, and reduce expensive grouping or filtering by page and query. Repeated large requests for the same data also increase Search Console load.
### The CSV link expired
Rerun the same report and download the new file before its expiry time.
### The results do not match the Search Console interface exactly
Keep the date range, property, search type, filters, dimensions, and aggregation consistent. Search Console may omit anonymized or lower-volume rows, and the API returns top rows rather than guaranteeing every possible row.
## Limits and boundaries
* Search Console dates are inclusive and interpreted in Pacific Time.
* Inline output is limited to 5,000 rows per request.
* CSV output is limited to 25,000 rows per request.
* CSV expiry can be set from 1 minute to 24 hours; the default is 30 minutes.
* Google may return fewer rows than requested.
* Search Analytics quota depends on query load as well as request frequency. Page and query grouping or filtering, especially together over long date ranges, is more expensive.
* Google's URL Inspection quota is separate from Search Analytics quota.
* URL Inspection shows indexed information, not a live-page test.
* Search Console data does not include Google Ads cost or conversion metrics. Keep paid and organic evidence separate when combining the two sources.
## Related guides
* [Connect Google Search Console](/search-console/quickstart)
* [Analyze Search Console performance](/guides/google-search-console)
* [Connect HireOtto to an AI client](/setup/connect-ai-tool)
* [Review plans and credits](/credits-and-billing)
* [Troubleshoot HireOtto connections](/troubleshooting)
## Sources
* [HireOtto Search Console product page](https://hireotto.com/search-console-mcp)
* [HireOtto pricing](https://hireotto.com/pricing)
* [Google Search Analytics query reference](https://developers.google.com/webmaster-tools/v1/searchanalytics/query)
* [Google Search Console API usage limits](https://developers.google.com/webmaster-tools/limits)
* [Google URL Inspection API reference](https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect)
* [Google Sites list reference](https://developers.google.com/webmaster-tools/v1/sites/list)
* [Google Sitemaps list reference](https://developers.google.com/webmaster-tools/v1/sitemaps/list)
# How to Connect HireOtto to Claude, ChatGPT, Make, Grok, or Perplexity
Source: https://docs.hireotto.com/setup/connect-ai-tool
Add the HireOtto servers you need, authorize the relevant Google services, and verify the connection with a practical first request.
# What you need
HireOtto is a hosted remote MCP service. You do not need a Google Cloud project, LinkedIn developer app, API keys, JSON credentials, a terminal, or a local process.
* An AI client or agent that supports remote MCP servers over HTTP and OAuth.
* A HireOtto trial or paid plan.
* A Google login with access to the Google Ads accounts, Tag Manager containers, Search Console properties, or GA4 properties you want to use – and a LinkedIn identity with access to the required LinkedIn Ads accounts when connecting that server.
Add only the servers you need. Each server is a separate MCP connection, while Search Console is currently available through the Google Ads connection.
# Choose the HireOtto server URLs
## Google Ads and Search Console
Use this connection for Google Ads reporting and supported account actions. It also exposes Search Console tools, but Search Console requires its own Google authorization after the server is connected.
```text theme={null}
https://googleads.hireotto.com/mcp
```
* Google Ads: read reporting data and run supported campaign-management actions.
* Search Console: inspect properties, organic performance, URLs, and sitemaps using a separate Google permission.
## Google Tag Manager
Use this connection to inspect Tag Manager accounts, containers, workspaces, tags, triggers, variables, folders, and tag wiring.
```text theme={null}
https://tagmanager.hireotto.com/mcp
```
The current Tag Manager server is read-only. It does not create, edit, delete, or publish container changes.
## Google Analytics 4 – beta
Use this connection for GA4 property discovery, metadata, report compatibility checks, standard reports, comparisons, and basic realtime reporting.
```text theme={null}
https://ga4.hireotto.com/mcp
```
GA4 access is read-only and currently in beta. HireOtto cannot edit GA4 properties or configuration.
## LinkedIn Ads – beta
Use this connection to inspect LinkedIn Ads accounts and hierarchy, run performance and professional-demographic reports, resolve targeting entities, estimate audience size, work with supported images, and prepare supported campaign objects as drafts.
```text theme={null}
https://linkedinads.hireotto.com/mcp
```
LinkedIn Ads is available where access is enabled. Read and write capability depends on the connected ad-account role and, for some sponsored-content workflows, LinkedIn Page permissions.
[LinkedIn Ads quickstart](https://docs.hireotto.com/linkedin-ads/quickstart)
# Connect HireOtto to your AI client
The menu names below reflect the current client interfaces. Admin controls and feature availability can vary by plan or workspace.
## Claude
1. Open Customize → Connectors.
2. Select +, then Add custom connector.
3. Give the connection a clear name, such as HireOtto — Google Ads, and paste the matching server URL.
4. Select Add, then Connect, and complete the authorization prompt.
Claude Free accounts currently support one custom connector. Pro and Max users can add custom connectors directly; Team and Enterprise workspaces have owner-managed setup.
## ChatGPT
1. Open Plugins → '+' and provide the HireOtto server endpoint.
2. Give the connection a clear name, such as HireOtto – Google Ads, and paste the matching server URL.
3. Select Add, then Sign in, and complete the authorization prompt.
## Make AI Agents
1. Open the scenario containing Make AI Agents (New) → Run an agent.
2. From the agent module, select Add MCP.
3. Create a connection with the matching HireOtto server URL.
4. Select only the tools the agent needs, then save the connection and the agent.
5. Test the agent in Make before using it in a live scenario.
Limiting enabled MCP tools keeps the agent’s tool list clearer and can reduce unnecessary model usage.
## Grok, Perplexity, or another remote MCP client
1. Open the client’s MCP or tools settings.
2. Create a remote HTTP MCP connection and paste the matching HireOtto server URL.
3. Use OAuth if the client asks for an authentication method.
4. Complete the authorization prompt, enable the server, and confirm that its tools are visible.
HireOtto is hosted remotely, so do not configure it as a local command or stdio process.
# Complete the platform connection
Connecting the MCP server and connecting the marketing platform are two separate steps. First your AI client connects to HireOtto. Then a HireOtto authentication tool connects the specific Google or LinkedIn service and saves the access granted by that identity.
## Google Ads
1. Ask: “Connect my Google Ads account.”
2. Open the authorization link returned by HireOtto.
3. Choose a Google login with access to the required Google Ads account or MCC, grant permission, and select the accounts HireOtto should save.
4. Return to the AI client and ask: “List my accessible Google Ads accounts.”
## Google Search Console
1. In the Google Ads HireOtto connection, ask: “Connect my Google Search Console account.”
2. Open the authorization link and choose a Google login that can access the required Search Console properties.
3. Grant the Search Console permission, then ask: “List the Search Console properties I can access.”
Connecting Google Ads does not automatically grant Search Console access. Google treats them as separate services and permissions.
## Google Tag Manager
1. Ask: “Connect my Google Tag Manager account.”
2. Open the authorization link and choose a Google login with access to the required Tag Manager accounts and containers.
3. Grant read-only Tag Manager access, then ask: “List my Tag Manager accounts and containers.”
## Google Analytics 4
1. Ask: “Connect my Google Analytics account.”
2. Open the authorization link and choose a Google login with access to the required GA4 properties.
3. Grant read-only Analytics access, then ask: “List my GA4 accounts and properties.”
## LinkedIn Ads
* Ask: “Connect my LinkedIn Ads account.”
* Open the authorization link and sign in with the LinkedIn identity that can access the required ad account.
* Grant the requested permissions, then ask: “List the LinkedIn Ads accounts I can access, including my role and write capability.”
Viewer access supports read-only work. Creating or changing ads requires a sufficient ad-account role, and some sponsored-content workflows also require access to the associated LinkedIn Page.
# Verify the connection
Use a small read request before starting a longer workflow. A successful response confirms both the MCP connection and the platform authorization.
* Google Ads: “List my accessible accounts.”
* Search Console: “Show the Search Console properties I can access.”
* Tag Manager: “List my Tag Manager accounts and web containers.”
* GA4: “List my GA4 accounts and properties.”
* LinkedIn Ads: “List the LinkedIn Ads accounts I can access, including my role and write capability.”
For Google Ads, ask for an account-specific read next, such as “List the enabled campaigns in account 1234567890.” Review the returned account name and ID before requesting any change.
# Plans, profiles, and access
* The free trial, Starter, Pro, and Agency plans include supported core access across Google Ads, Tag Manager, Search Console, GA4 and LinkedIn Ads beta.
* The trial ends after 14 days or 200 credits, whichever comes first.
* Starter includes 2,000 credits per month; Pro includes 5,000 credits per month; Agency includes unlimited credits.
* Agency is required for audits, multiple connected Google profiles, team billing, and additional seats.
* Connecting another profile means authorizing a different Google login. Giving the same login another nickname does not expand its account access.
HireOtto can access only the accounts, containers, and properties available to the Google login or LinkedIn identity you authorize. It does not bypass platform roles or permissions.
# Common setup problems
## The server is connected, but no tools appear
* Confirm that the endpoint ends with /mcp and matches the intended HireOtto server.
* Complete the client-level OAuth prompt, then rescan or refresh the server tools.
* Enable the connector or app in the current chat or agent.
* Restart or reconnect the client if its MCP tool list is cached.
## The tool asks you to authenticate again
* Run the relevant connect prompt and open the newest authorization link.
* Finish the Google or LinkedIn consent flow in the same browser session and return to the original AI client.
* If the connection was revoked or the Google password or security policy changed, reconnect the service.
## No accounts, containers, or properties appear
* Confirm that the connected Google or LinkedIn login can open the required resource directly in Google’s interface.
* For Google Ads, refresh accessible accounts after Google grants or changes access.
* For nested Google Ads manager structures, connect a Google login with direct access to the relevant inner MCC when the account is not discoverable from the existing profile.
* On Agency, use a distinct profile name when connecting another Google login.
* For LinkedIn Ads, confirm that the same LinkedIn identity can open the ad account in Campaign Manager and inspect the returned role and write capability.
## A client menu does not match this guide
MCP client interfaces change frequently. Look for Apps, Connectors, Tools, Integrations, or MCP settings, then add a remote HTTP server with OAuth. If the client does not support remote MCP or OAuth, it cannot complete the hosted HireOtto connection.
# Security and control
* HireOtto uses OAuth; you do not paste Google or LinkedIn passwords, API keys, or refresh tokens into the conversation.
* Google Ads supports both read workflows and supported account actions. Review important or bulk changes before they are applied.
* Tag Manager and GA4 are read-only in their current releases.
* Search Console uses its own Google permission and is limited to the resources available to that Google login.
* LinkedIn Ads supports read workflows and selected draft-first actions where access is enabled. Write capability depends on the connected ad-account role and LinkedIn Page permissions.
* Disconnect the app in your AI client or revoke the relevant Google or LinkedIn authorization when access is no longer needed.
# Next steps
After the verification request succeeds, continue with the guide or tools reference for the server you connected. Start with a read workflow, confirm the account or property, and move to reviewable actions only when the server supports them.
If setup fails, go to [Troubleshooting](/troubleshooting).
# Review a GTM container inventory and tag wiring with HireOtto
Source: https://docs.hireotto.com/tag-manager/container-inventory
Inspect live or workspace GTM configuration, trace tags to firing and blocking triggers, and export a review-ready inventory without changing the container.
Use HireOtto to turn a Google Tag Manager container into a readable inventory of tags, triggers, variables, folders, and tag-to-trigger relationships. The workflow is read-only: it cannot create, edit, version, or publish anything in GTM.
Start with the live published container when you need to understand what is currently configured for production. Inspect a workspace only when you intentionally want to review draft or unpublished configuration.
> The inventory explains configuration. It does not prove that a tag fired in a browser, that a consent state allowed it, or that the destination received data. Use GTM Preview mode and live browser QA for runtime validation.
## What this workflow helps you answer
* Which tags, triggers, variables, built-in variables, and folders exist?
* Which firing triggers are attached to each tag?
* Which blocking triggers can prevent a tag from firing?
* Which tags are paused or have no firing trigger attached?
* Which important measurement IDs, event names, conversion IDs, or labels appear in the configuration?
* Is the review based on the live published version or an unpublished workspace?
* Should the result stay in the conversation or move to a CSV for deeper analysis?
## Before you start
You need:
* A connected HireOtto Google Tag Manager server at `https://tagmanager.hireotto.com/mcp`.
* A Google login that can already access the required GTM account and container.
* The GTM account ID and internal numeric container ID. The public `GTM-XXXXXXX` identifier is not used as `container_id`.
* A workspace ID only when you want to inspect a specific workspace.
Tag Manager inspection is available on Free, Starter, Pro, and Agency. Free, Starter, and Pro use the `default` Google profile. Agency supports additional named Google profiles. Normal trial, billing, entitlement, credit, and Google permission checks still apply.
If you have not connected Tag Manager yet, follow the [GTM quickstart](https://docs.hireotto.com/tag-manager/quickstart).
## Choose the correct source
| Source | What it represents | Use it when | Workspace ID |
| ----------- | ----------------------------------------------------- | ---------------------------------------------------------- | ------------ |
| `live` | The currently published container version | You are reviewing production configuration | Not accepted |
| `workspace` | Draft or unpublished configuration in a GTM workspace | You are reviewing work before it is versioned or published | Optional |
`live` is the default. A live request cannot be combined with `workspace_id`.
When `source="workspace"` and no workspace ID is supplied, HireOtto prefers a workspace named `Default Workspace`. If it is unavailable, HireOtto uses the first accessible workspace. Supply the ID when the exact workspace matters.
Do not describe workspace inventory as production state. A workspace can contain changes that visitors do not receive.
## Run a container inventory
For a normal production review, ask:
```text theme={null}
Inspect the live published configuration for GTM account 123456 and internal container 789012.
Summarize its tags, firing and blocking triggers, variables, folders, paused state,
and important measurement parameters. Include a CSV export. Do not change anything.
```
For unpublished work, ask:
```text theme={null}
Inspect workspace 7 in GTM account 123456 and internal container 789012.
Identify tags with no firing trigger, paused tags, blocking triggers, and configuration
that needs human review. Use summary output only. Do not publish anything.
```
## Parameters and defaults
| Parameter | Required | Default | Accepted values and behavior |
| -------------------- | -------: | ----------------- | ------------------------------------------------------------------------------------------------------ |
| `account_id` | Yes | — | GTM account ID. |
| `container_id` | Yes | — | Internal numeric GTM container ID, not the public `GTM-*` ID. |
| `workspace_id` | No | — | Used only with `source="workspace"`. |
| `source` | No | `live` | `live` or `workspace`. Other values are rejected. |
| `profile_id` | No | `default` | Selects the connected Google profile. Non-default profiles require Agency. |
| `include_raw` | No | `false` | Adds Google’s underlying entity fields. Leave disabled for normal marketer-facing reviews. |
| `output_mode` | No | `summary_and_csv` | `summary`, `summary_and_csv`, or `csv_only`. Unsupported values fall back to `summary_and_csv`. |
| `limit` | No | `50` | Maximum inline tag-wiring entries. Range: 1–5,000. It does not reduce the normalized entity inventory. |
| `export_limit` | No | `5000` | Maximum flattened CSV rows. Range: 1–50,000. |
| `export_ttl_minutes` | No | `30` | Signed CSV-link lifetime. Range: 1–1,440 minutes. |
## What the inventory returns
### Source context
The response identifies the GTM account and container and labels the result as `live` or `workspace`.
A live inventory includes available published container-version metadata. A workspace inventory includes the selected workspace details.
Always verify this context before interpreting the configuration.
### Entity counts and normalized inventory
The response includes counts and normalized lists for:
* Workspaces
* Tags
* Triggers
* User-defined variables
* Built-in variables
* Folders
Normalized tag details can include the tag type, paused state, folder, trigger IDs, and important parameters such as measurement IDs, event names, conversion IDs, or conversion labels where present.
`include_raw=false` is the recommended default. Enable raw fields only when the normalized view cannot answer a specific question.
### Joined tag wiring
The tag-wiring view joins each tag to:
* Its firing triggers
* Human-readable trigger-condition summaries
* Its blocking triggers
* Its folder
* Its paused state
* Selected important parameters
* A plain-language summary of when the tag is configured to fire and when it can be blocked
Built-in All Pages, Consent Initialization, and Initialization triggers are recognized in the wiring view when Google represents them as system trigger IDs.
A missing firing trigger is a review signal, not an automatic error. Confirm the tag’s purpose and inspect the configuration in GTM before deciding what to change.
## Review the inventory step by step
### 1. Confirm the account, container, and source
Check that the returned account ID, internal container ID, public GTM ID from the earlier container lookup, and source match the property you intended to review.
Do not continue from a plausible-looking container name alone.
### 2. Scan the counts
Use the counts to orient the review:
* An unexpectedly empty live container may not have a usable published version.
* A workspace with many more entities than expected may contain unfinished work.
* Very low trigger or variable counts can indicate a simple implementation, not necessarily a problem.
Counts tell you where to inspect. They do not establish tracking quality.
### 3. Trace each important tag
For every conversion, analytics, remarketing, and consent-related tag, check:
* Is it paused?
* Which firing triggers are attached?
* What conditions do those triggers use?
* Are blocking triggers attached?
* Which measurement or conversion identifiers appear?
* Is it organized in the expected folder?
Start with commercially important outcomes such as lead submissions, purchases, bookings, phone calls, and qualified funnel events.
### 4. Review exceptions
Create a review queue for:
* Tags with no firing trigger
* Paused tags that may still be expected
* Very broad firing conditions
* Blocking conditions that may prevent intended measurement
* Duplicate-looking tags or destination identifiers
* Unfamiliar custom HTML
* Naming or folder organization that makes ownership unclear
Treat these as questions for investigation. Do not label a tag broken from configuration evidence alone.
### 5. Check variables and folders
Variables help explain how identifiers, event values, URLs, selectors, and other settings are supplied to tags and triggers. Folders help identify ownership and organization.
The inventory lists these entities, but the flattened CSV focuses on tag-to-trigger relationships. Use the normalized response when the complete variable or folder inventory matters.
### 6. Move large reviews to CSV
Use CSV when the container is too large for a useful conversational review or when you want to filter by tag type, paused state, trigger role, folder, or important parameters.
One tag can produce several CSV rows because firing and blocking relationships are flattened. A tag with no attached firing or blocking trigger produces a row with trigger role `none`. Therefore, CSV row count can be higher than tag count.
## Output modes
| Mode | Inline response | CSV | Best for |
| ----------------- | ------------------------------------------------------------ | --------------------------- | ----------------------------------------------- |
| `summary` | Full normalized inventory plus tag wiring limited by `limit` | No | Focused reviews inside the conversation |
| `summary_and_csv` | Full normalized inventory plus limited inline tag wiring | Yes, when wiring rows exist | Default review with a downloadable working file |
| `csv_only` | IDs, source, counts, and export metadata | Yes, when wiring rows exist | Large containers and spreadsheet analysis |
The `limit` parameter affects only inline tag wiring. It does not truncate the normalized lists of tags, triggers, variables, built-in variables, folders, or workspaces.
`export_limit` applies after the relationships are flattened. Check the returned total, inline, CSV, and exported row counts to see whether the response or export was limited.
## Practical review patterns
### Find tags without a firing trigger
```text theme={null}
Inspect the live container. List every tag with no firing trigger attached.
For each one, show its tag type, paused state, folder, and important parameters.
Treat the result as a review queue, not proof that the tag is broken.
```
### Review Google Ads and GA4 measurement wiring
```text theme={null}
Inspect the live container and isolate Google Ads conversion, remarketing, Google tag,
GA4 configuration, and GA4 event tags. Show their identifiers, event names, firing
conditions, blocking conditions, paused state, and folders. Flag ambiguous wiring for
human review. Do not change GTM.
```
### Prepare a pre-publish workspace review
```text theme={null}
Inspect workspace 7. Summarize its tag wiring and identify paused tags, tags without
firing triggers, broad trigger conditions, blocking triggers, duplicate-looking
identifiers, and custom HTML that needs manual inspection. Label the result unpublished.
```
### Export a large container
```text theme={null}
Inspect the live container using csv_only. Export up to 20,000 flattened wiring rows
and keep the link available for 60 minutes. Report the tag count, total wiring count,
exported row count, and whether the export was limited.
```
## Read and write scope
| Workflow | Current support |
| ------------------------------------------------------------------ | --------------- |
| List and inspect accounts, containers, workspaces, and entities | Read |
| Inspect live published configuration | Read |
| Inspect unpublished workspace configuration | Read |
| Export flattened tag wiring | Read/export |
| Create or edit tags, triggers, variables, or folders | Not supported |
| Create versions, resolve workspace changes, or publish a container | Not supported |
HireOtto cannot bypass the permissions of the connected Google login. It also cannot apply a recommended repair. Make and publish any approved changes in Google Tag Manager.
## Limits and interpretation
* **Configuration is not runtime evidence.** The inventory cannot prove that a browser loaded GTM, a trigger activated, consent allowed a tag, or a destination recorded data.
* **Live and workspace are different views.** The workflow does not automatically compare them. Run both explicitly when you need a side-by-side review.
* **Inline wiring can be limited.** Increase `limit` or use CSV for large containers.
* **Exports expire.** Regenerate a signed link after its requested TTL instead of reusing the old URL.
* **No wiring rows means no CSV export.** Use the normalized entity inventory to understand an empty or unusual result.
* **Permissions shape the result.** Missing resources can reflect the selected Google profile’s access.
* **Usage rules still apply.** Inventory is a deeper request than account or container listing. Starter and Pro use monthly credits; Agency includes unlimited credits.
* **Google API limits can cause transient failures.** Retry later when a request is rate-limited rather than treating it as a container problem.
## Common failures
### Tag Manager is not connected
Run the Tag Manager authentication request, open the newest authorization link, complete Google authorization and HireOtto consent, then list accounts again.
### The account or container is missing
Open GTM using the same Google login and confirm that the resource is visible. Verify that `container_id` is Google’s internal numeric container ID. Use the container lookup workflow when you only know the public `GTM-*` identifier.
### The live inventory fails
A live request requires an available published container version. List workspaces and inspect a workspace instead when appropriate, but label the result as unpublished configuration.
### The workspace request fails
Set `source="workspace"`. Do not combine `workspace_id` with `source="live"`. If the workspace was renamed or removed, list current workspaces and select the current ID.
### The wrong workspace was selected
When a workspace ID is omitted, HireOtto chooses `Default Workspace` when available and otherwise uses the first accessible workspace. Supply the exact ID when that fallback is not acceptable.
### A named profile is blocked
Use `default` on Free, Starter, or Pro. Additional named Google profiles require Agency. Confirm the profile spelling and reconnect the intended Google identity when necessary.
### The CSV link expired or the export is shorter than expected
Run the inventory again with a suitable `export_ttl_minutes` value. Compare total wiring rows with exported rows and increase `export_limit` within the supported range when needed.
### The inventory looks correct but tracking is still missing
Move to runtime validation. Check the deployed GTM identifier, consent behavior, browser requests, GTM Preview mode, destination diagnostics, and the actual conversion journey. Configuration inspection alone cannot establish that measurement works.
## Recommended workflow
1. List accounts and confirm the intended account ID.
2. List containers and match the public `GTM-*` ID to the internal container ID.
3. Inspect `source="live"` first for production-state questions.
4. Inspect a specific workspace only when unpublished work matters.
5. Review tag wiring, important parameters, paused state, variables, and folders.
6. Export large relationship sets to CSV.
7. Turn anomalies into a human review queue.
8. Validate firing behavior with GTM Preview mode and live browser QA.
9. Make and publish approved changes in Google Tag Manager.
## Related documentation
* [Connect Google Tag Manager to HireOtto](https://docs.hireotto.com/tag-manager/quickstart)
* [Google Tag Manager MCP tools reference](https://docs.hireotto.com/tag-manager/tools-reference)
* [HireOtto plans and credits](https://hireotto.com/pricing)
# Connect Google Tag Manager to Claude, ChatGPT, and AI tools
Source: https://docs.hireotto.com/tag-manager/quickstart
Connect HireOtto’s Google Tag Manager MCP server to inspect the accounts, containers, workspaces, tags, triggers, variables, folders, and tag wiring available to your Google login.
## **What you need**
* An AI client that supports remote HTTP MCP servers and OAuth, such as Claude, ChatGPT, Make, Grok, or another compatible client.
* A HireOtto trial or paid plan. Tag Manager inspection is available on Free, Starter, Pro, and Agency.
* A Google login that can already open the Tag Manager accounts and containers you want to inspect.
You do not need a Google Cloud project, API key, JSON credential file, terminal, or local server.
## **Connect the MCP server**
Add a new remote MCP connection in your AI client and use:
```text theme={null}
https://tagmanager.hireotto.com/mcp
```
Name the connection something clear, such as **HireOtto — Tag Manager**. Choose OAuth if the client asks for an authentication method, complete the HireOtto sign-in, and enable the server for the current chat or agent.
Client menus change over time. Look for **Apps**, **Connectors**, **Tools**, **Integrations**, or **MCP**. Configure HireOtto as a remote HTTP server, not a local command or stdio process.
## **Authorize Google Tag Manager**
Connecting the MCP server and connecting Google Tag Manager are two separate steps. Seeing HireOtto’s tools confirms the first connection only.
1. Ask your AI client: *“Connect my Google Tag Manager account.”*
2. Open the authorization link returned by HireOtto.
3. Choose the Google login that has access to the required GTM accounts and containers.
4. Grant the requested read-only Tag Manager permission.
5. Accept HireOtto’s Terms of Use and Privacy Policy to finish the connection. Product-update emails remain optional.
6. Close the confirmation window and return to your AI client.
HireOtto requests Google’s read-only Tag Manager scope together with basic identity permissions used to identify the connected Google login. It stores the resulting connection so it can refresh access when needed. You never paste a Google password, access token, or refresh token into the conversation.
## **Verify the connection**
Start with a small read request:
List my Google Tag Manager accounts and the web containers inside each one. Include the account ID, container ID, public GTM ID, container name, and usage context.
A successful response confirms that both connections work: your AI client can reach HireOtto, and HireOtto can read Tag Manager using the Google identity you authorized.
Check that the returned account, container name, and public GTM-\* ID match the property you intended to connect before moving to a larger review.
## **Default and named profiles**
The authentication action accepts one optional parameter:
| Parameter | Required | Default | Use |
| :---------- | :------- | :------ | :------------------------------------------------------------------------------------- |
| profile\_id | No | default | Labels the connected Google login so it can be selected in later Tag Manager requests. |
Free, Starter, and Pro use the default profile. Agency supports multiple connected Google profiles. When you need another Google login on Agency, use a distinct, recognizable profile name such as client-mcc-west or agency-ops.
A profile name is only a label. Giving the same Google login a different name does not expose additional GTM accounts or containers. A profile name also cannot contain a colon (:).
## **What you can inspect**
After authentication, HireOtto can read:
* Accessible Tag Manager accounts and containers
* Container lookup by public GTM-\* ID or supported destination ID
* Workspaces
* Tags, firing triggers, blocking triggers, and trigger conditions
* User-defined and built-in variables
* Folders
* Live published container inventory or a selected workspace inventory
* Structured tag-wiring summaries and CSV exports
The server can also scan public website HTML for GTM, GA4, Google Ads, forms, booking tools, consent signals, and related tracking clues. That scan is read-only and separate from GTM authorization. It inspects static HTML, so it cannot prove that interaction-based tags fire correctly on JavaScript-rendered pages.
## **Read and write scope**
| Workflow | Current support |
| :--------------------------------------------------- | :---------------------- |
| List and inspect GTM configuration | Read |
| Review live or workspace tag wiring | Read |
| Export inventory to CSV | Read/export |
| Scan a public website for tracking signals | Read-only external scan |
| Create or edit tags, triggers, variables, or folders | Not supported |
| Create container versions or publish a container | Not supported |
HireOtto’s OAuth permission and current tools are read-only. Any change to a GTM container must still be reviewed and made in Google Tag Manager.
## **Useful first requests**
### **Find the right container**
List my Tag Manager accounts and web containers. Show the account ID, container ID, public GTM ID, container name, domains, and a direct Tag Manager link where available.
### **Inspect the live container**
Inspect the live published setup for GTM-XXXXXXX. Summarize tags, firing and blocking triggers, important parameters, variables, folders, and anything that needs a closer human review. Do not change anything.
### **Review an unpublished workspace**
List the workspaces in this container. Then inspect the workspace I select and explain how its tag wiring differs from what I should verify in Preview mode. Do not publish anything.
A workspace can contain unpublished changes and may not match what visitors currently receive. Use the live source for production-state reviews; choose a workspace only when you intentionally want to inspect draft configuration.
## **Common setup problems**
### **The server connects, but no Tag Manager tools appear**
* Confirm the endpoint is exactly [https://tagmanager.hireotto.com/mcp](https://tagmanager.hireotto.com/mcp).
* Complete the AI client’s HireOtto OAuth flow.
* Enable the connector in the current chat or agent.
* Refresh or reconnect the server if the client cached its tool list.
### **HireOtto says Tag Manager is not connected**
Run the connect prompt again, open the newest authorization link, and finish both Google authorization and the final HireOtto consent step. Returning to the chat before completing the final step can leave the platform connection unfinished.
### **No accounts or containers appear**
* Open Google Tag Manager directly with the same Google login and confirm the resource is visible there.
* Reconnect using the Google identity that actually has access.
* If you need a second Google login, use a separate named profile on Agency.
* Remember that HireOtto cannot bypass Google’s account and container permissions.
### **Access worked earlier but now fails**
Google access may need to be reauthorized after a revoked grant, password or security-policy change, missing refresh permission, or expired connection. Reconnect Tag Manager and retry the same small account-list request.
### **A named profile is rejected**
Non-default profiles require Agency or Enterprise access. Use default on other plans, and remove any colon from the profile name.
### **The request is blocked by the plan or credits**
Tag Manager inspection is available across plans, but the free trial ends after 14 days or 200 credits, whichever comes first. Starter and Pro use monthly credits; Agency includes unlimited credits. Expired access, inactive billing, exhausted credits, or a disabled entitlement can block a request.
## **Next step**
Once the account and container are verified, continue with the Tag Manager tools reference or the container inventory and tag-wiring guide. For a first review, inspect the live published container and keep the request read-only.
# Google Tag Manager MCP tools reference
Source: https://docs.hireotto.com/tag-manager/tools-reference
Use HireOtto’s Google Tag Manager MCP tools to find accessible GTM resources, inspect a live container or workspace, understand how tags and triggers are wired, export that inventory, and scan public website HTML for tracking signals.
## **Before using the tools**
Connect the remote MCP server, then run authenticate\_tag\_manager to authorize a Google login with access to the required Tag Manager accounts and containers. The [Tag Manager quickstart](https://docs.hireotto.com/tag-manager/quickstart) covers the complete connection flow.
Free, Starter, Pro, and Agency include Tag Manager inspection. Free, Starter, and Pro use one default Google profile. Agency supports multiple connected Google profiles. Normal trial, credit, billing, entitlement, and Google permission checks still apply.
## **Tool summary**
| Tool | Use it for | Changes GTM? |
| :----------------------------- | :--------------------------------------------------------- | :----------- |
| authenticate\_tag\_manager | Connect or reconnect a Google login | No |
| list\_gtm\_accounts | List GTM accounts visible to the connected login | No |
| list\_gtm\_containers | List containers under one GTM account | No |
| lookup\_gtm\_container | Resolve a public GTM or destination ID to a container | No |
| list\_gtm\_workspaces | List workspaces inside a container | No |
| get\_gtm\_container\_inventory | Inspect live or workspace configuration and tag wiring | No |
| scan\_website\_tracking | Scan public HTML for tracking and conversion-point signals | No |
| get\_billing\_status | Check plan, credits, access period, and entitlements | No |
## **authenticate\_tag\_manager**
Returns a Google authorization link. Open it, choose the Google identity that can access the required GTM resources, grant read-only Tag Manager permission, and finish the HireOtto consent step.
| Parameter | Required | Default | Description |
| :---------- | :------- | :------ | :----------------------------------------------------------------------------------------------------------- |
| profile\_id | No | default | Labels the connected Google login. Non-default profiles require Agency. A profile ID cannot contain a colon. |
Authentication does not modify GTM. The tool starts the authorization flow and returns the link that the user must complete.
### **Example**
## **list\_gtm\_accounts**
Lists every Tag Manager account visible to the selected Google profile. Use it as the first verification request after authentication.
| Parameter | Required | Default | Description |
| :----------- | :------- | :------ | :---------------------------------------------------------------------------------------- |
| profile\_id | No | default | Selects the connected Google profile. |
| include\_raw | No | false | Includes Google’s underlying response fields in addition to HireOtto’s normalized fields. |
The normalized response includes the account ID, name, path, share information, and account-level metadata where Google provides it.
### **Example**
## **list\_gtm\_containers**
Lists the containers under a selected GTM account.
| Parameter | Required | Default | Description |
| :----------- | :------- | :------ | :---------------------------------------------------- |
| account\_id | Yes | — | GTM account ID. A full account path is also accepted. |
| profile\_id | No | default | Selects the connected Google profile. |
| include\_raw | No | false | Adds Google’s underlying fields. |
The normalized response includes each container’s internal ID, public GTM-\* ID, name, domains, usage context, Tag Manager URL, path, and fingerprint where available.
### **Example**
## **lookup\_gtm\_container**
Resolves a public tracking identifier to the matching GTM container available to the connected Google profile. This is useful when a website scan finds an ID but you do not know its account or internal container ID.
| Parameter | Required | Default | Description |
| :-------------- | :---------- | :------ | :------------------------------------------------- |
| tag\_id | Conditional | — | Public Tag Manager ID such as GTM-ABC1234. |
| destination\_id | Conditional | — | Supported Google destination ID such as a G-\* ID. |
| profile\_id | No | default | Selects the connected Google profile. |
| include\_raw | No | false | Adds Google’s underlying fields. |
Provide tag\_id or destination\_id. If neither is supplied, the request is rejected locally.
### **Example**
## **list\_gtm\_workspaces**
Lists the workspaces inside a selected container. Use this before inspecting unpublished configuration.
| Parameter | Required | Default | Description |
| :------------ | :------- | :------ | :--------------------------------------------------- |
| account\_id | Yes | — | GTM account ID. |
| container\_id | Yes | — | Internal GTM container ID, not the public GTM-\* ID. |
| profile\_id | No | default | Selects the connected Google profile. |
| include\_raw | No | false | Adds Google’s underlying fields. |
The response includes workspace IDs, names, descriptions, paths, fingerprints, and Tag Manager URLs where available.
### **Example**
## **get\_gtm\_container\_inventory**
Returns a normalized view of tags, triggers, variables, built-in variables, folders, and joined tag wiring for either the live published container or a workspace.
Use source="live" when you want to understand what the published container currently serves. Use source="workspace" when reviewing draft or unpublished configuration.
| Parameter | Required | Default | Accepted values and behavior |
| :------------------- | :------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id | Yes | — | GTM account ID. |
| container\_id | Yes | — | Internal GTM container ID. |
| workspace\_id | No | — | Used only with source="workspace". If omitted for a workspace request, HireOtto prefers “Default Workspace,” then falls back to the first available workspace. |
| source | No | live | live or workspace. A workspace ID cannot be combined with live. |
| profile\_id | No | default | Selects the connected Google profile. |
| include\_raw | No | false | Adds Google’s underlying entity data. Leave off for normal marketer-facing reviews. |
| output\_mode | No | summary\_and\_csv | summary, summary\_and\_csv, or csv\_only. Unsupported values fall back to summary\_and\_csv. |
| limit | No | 50 | Inline tag-wiring rows. Range: 1–5,000. This does not reduce the normalized entity inventory. |
| export\_limit | No | 5000 | Maximum flattened CSV rows. Range: 1–50,000. |
| export\_ttl\_minutes | No | 30 | How long the signed CSV link remains available. Range: 1–1,440 minutes. |
### **What the inventory returns**
* Counts for tags, triggers, variables, built-in variables, and folders
* The selected workspace or published container-version metadata
* Normalized tag details, including type, paused state, folder, and important parameters
* Firing and blocking triggers with condition summaries
* A plain-language wiring summary for each tag
* Optional raw entity fields
* Optional flattened CSV export
CSV rows represent tag-to-trigger relationships. A single tag can produce several rows when it has multiple firing or blocking triggers, so the export row count can be higher than the tag count.
### **Output modes**
| Mode | Inline response | CSV | Best for |
| :---------------- | :----------------------------------------------- | :-------------------------- | :---------------------------------------------- |
| summary | Inventory plus limited inline tag wiring | No | Smaller reviews inside the conversation |
| summary\_and\_csv | Inventory plus limited inline tag wiring | Yes, when wiring rows exist | Default review with a downloadable working file |
| csv\_only | Identifiers, source, counts, and export metadata | Yes, when wiring rows exist | Large containers or spreadsheet analysis |
### **Examples**
## **scan\_website\_tracking**
Scans public website HTML for tracking identifiers and likely conversion points. The tool starts from the supplied URL, uses sitemap discovery when possible, and falls back to links found on the homepage. It prioritizes pages such as contact, booking, demo, pricing, checkout, and confirmation pages.
This tool requires a connected HireOtto server and eligible plan access, but it does not require a Google Tag Manager platform connection because it reads publicly served HTML.
| Parameter | Required | Default | Accepted values and behavior |
| :--------------- | :------- | :------ | :----------------------------------------------------------------------------------------------------------------------------- |
| url | Yes | — | Public HTTP or HTTPS website URL. A missing scheme is treated as HTTPS. |
| max\_pages | No | 6 | Maximum automatically selected pages. Range: 1–10. |
| additional\_urls | No | None | Force-includes pages discovery may miss, such as an unlinked thank-you page. The final deduplicated scan is capped at 10 URLs. |
| timeout\_seconds | No | 10 | Per-request timeout. Range: 3–30 seconds. |
### **Signals returned**
* GTM container IDs and install-loader signals
* GA4 measurement IDs, Google Ads conversion IDs, and legacy Universal Analytics IDs
* Forms, telephone links, email links, iframes, and recognized form or booking providers
* Consent-management and JavaScript-framework signals
* HTTP status, final URL after redirects, page-level errors, and a cross-page summary
* Warnings for inconsistent GTM IDs or suspected duplicate installations
### **Important limitation**
The scan reads static HTML. It does not execute the page like a browser, click elements, submit forms, enter consent states, or prove that a tag fired. Client-rendered content and interaction-triggered tags can be missed. Treat the result as discovery evidence and follow it with GTM Preview mode and live browser QA before declaring a tracking setup correct or broken.
### **Example**
## **get\_billing\_status**
Returns the current HireOtto plan, billing state, access period, credits included and used, remaining credits where applicable, entitlement flags, and available upgrade links.
This tool has no parameters and does not consume or modify GTM data.
### **Example**
## **Shared behavior and limits**
* **Read-only:** No current tool creates, edits, deletes, versions, or publishes GTM entities.
* **Google permissions:** Results are limited to resources visible to the selected Google login.
* **Profiles:** default is used when profile\_id is omitted. Non-default profiles require Agency.
* **Raw data:** include\_raw=false is the recommended default. Enable it only when normalized fields are insufficient.
* **IDs:** Account, container, and workspace tools use Google’s internal numeric IDs. A public GTM-\* ID is accepted by the lookup tool, not as container\_id.
* **Exports:** Inventory CSV links are signed and expire after the requested TTL. Regenerate an expired export instead of reusing the old URL.
* **Credits:** Listing and lookup requests are lighter than a full inventory. Website-scan usage scales with pages scanned. Agency includes unlimited credits.
## **Common failures**
### **Tag Manager is not connected**
Run authenticate\_tag\_manager, open the newest link, finish Google authorization and HireOtto consent, then retry list\_gtm\_accounts.
### **The selected profile does not exist**
Use default, or reconnect the intended Google login with the exact named profile on Agency.
### **An account, container, or workspace is missing**
Confirm that the selected Google login can open the resource directly in Tag Manager. Check that you used the internal numeric ID in the correct field. HireOtto cannot bypass Google permissions.
### **The live inventory fails**
A live request requires an available published container version. If the container has no usable live version, list workspaces and inspect a workspace instead, clearly labeling it as unpublished configuration.
### **The workspace request fails**
Use source="workspace". Do not combine workspace\_id with source="live". If the chosen workspace no longer exists, list workspaces again and use the current ID.
### **The website scan misses a form or tag**
Check for JavaScript-framework signals, consent-gated tags, embedded applications, authentication requirements, or interaction-based loading. Add known confirmation pages explicitly, then verify behavior in a real browser and GTM Preview mode.
### **A request is blocked before reaching Google**
Expired trial access, inactive billing, exhausted credits, a disabled entitlement, or use of an Agency-only named profile can block the request. Run get\_billing\_status for the current state.
## **Recommended review sequence**
1. List accounts and choose the correct account ID.
2. List containers and verify the public GTM-\* ID.
3. Inspect the live container inventory first.
4. List and inspect a workspace only when unpublished work matters.
5. Scan the public website to compare served identifiers with GTM configuration.
6. Use GTM Preview mode and browser QA for firing behavior.
# Fix HireOtto MCP Connection Issues
Source: https://docs.hireotto.com/troubleshooting
Troubleshoot server connections, Google and LinkedIn authorization, missing resources, permission errors, empty reports, and partial campaign creation.
# Start here
First identify which layer failed:
* The AI client cannot connect to the HireOtto MCP server.
* The server is connected, but the marketing platform is not authorized.
* Authorization succeeded, but the expected account or property is missing.
* The resource is visible, but the connected role cannot perform the requested action.
* The platform accepted the request but returned no data or rejected a field, lifecycle transition, or creative.
Read the returned error before retrying. Repeating the same request unchanged rarely fixes a permission, identifier, or platform-validation problem.
# Error during tool execution
## Symptom
Several unrelated tools begin returning a generic execution error at the same time.
## Fix
* Disconnect and reconnect the HireOtto connector or app in the AI client.
* Enable the connector again in the current chat or agent.
* Retry one small read request.
If only one action fails while other tools still work, treat it as a tool- or platform-specific error instead of a stale client session.
# MCP server not connecting
Confirm that you added the correct remote HTTP endpoint and that it ends with /mcp:
* Google Ads and Search Console — [https://googleads.hireotto.com/mcp](https://googleads.hireotto.com/mcp)
* Google Tag Manager — [https://tagmanager.hireotto.com/mcp](https://tagmanager.hireotto.com/mcp)
* Google Analytics 4 — [https://ga4.hireotto.com/mcp](https://ga4.hireotto.com/mcp)
* LinkedIn Ads — [https://linkedinads.hireotto.com/mcp](https://linkedinads.hireotto.com/mcp)
Common problems include a hostname typo, a missing s in https, a trailing slash, configuring HireOtto as a local or stdio server, or not enabling the connector in the current conversation.
## The server is connected, but no tools appear
* Complete the client-level OAuth prompt.
* Rescan or refresh the server tools.
* Enable the connector or app in the current chat or agent.
* Restart or reconnect the client if its MCP tool list is cached.
# Authentication errors
## Symptom
The response says authorization is required, not authenticated, or returns a new authorization link.
## Fix
* Ask to connect the relevant Google or LinkedIn product.
* Open the newest authorization link in the same browser session.
* Sign in with an identity that can already access the required resource.
* Complete consent and return to the original AI client.
* Run a small account or property list before starting a longer workflow.
If access was revoked or the platform login or security policy changed, reconnect the service.
# Google Ads accounts are missing
Completing Google OAuth and saving selected Google Ads accounts are separate steps. Re-authenticate, select the accounts HireOtto should save, and confirm the selection before returning to the AI client.
Other checks:
* Confirm the same Google login can open the account in Google Ads.
* Refresh accessible accounts after Google grants or changes access.
* If a client account is available only through a deeper manager hierarchy, connect a Google login with direct access to the relevant inner MCC or account.
* Use a distinct profile name only when connecting a different Google login; renaming the same login does not expand access.
# LinkedIn Ads accounts are missing
Confirm that the same LinkedIn identity can open the ad account in Campaign Manager. Then reconnect LinkedIn Ads and ask:
List the LinkedIn Ads accounts I can access, including my role and write capability.
If the account still does not appear:
* Check that LinkedIn Ads access is enabled for the HireOtto account.
* Reconnect with the LinkedIn identity that has direct access to the ad account.
* Confirm the account is active and visible in Campaign Manager.
* Ask for the account list again after a role or access change.
# Insufficient permissions or access denied
## Google Ads
Read-only access supports reporting. Creating or changing campaigns normally requires Standard or Admin access. Google can still reject an operation because of account standing, policy state, campaign type, or unsupported settings.
## LinkedIn Ads
Viewer access supports read-only work. Creating or changing ads requires a sufficient ad-account role. Inspect the role and write capability returned for the selected account before retrying.
## I can read LinkedIn Ads but cannot create a creative
Direct Sponsored Content and other sponsored-content workflows may also require access to the associated LinkedIn Page. Confirm Page permission, ad-account role, image eligibility, destination, call to action, and supported format in Campaign Manager.
# Reports are empty
A valid empty response does not always indicate a broken connection. Check:
* The account, campaign-group, ad-set, or creative IDs.
* The date window and whether the selected objects delivered during that period.
* Whether the connected role can access the requested data.
* Whether the chosen metrics are compatible with the requested reporting pivot.
For LinkedIn professional demographics, allow for reporting delay and privacy suppression. Small groups may not appear, and the returned rows are directional rather than exhaustive.
# Campaign or draft creation fails
## Google Ads
Check billing, policy warnings, suspension state, the connected role, required fields, and supported campaign settings. If a campaign exists but a child object failed, inspect and clean up or resume from the failed step instead of recreating everything blindly.
## LinkedIn Ads
Validate the objective, account currency, budget, dates, targeting, audience size, format, Page identity, image, destination, copy, call to action, alt text, and approval state. Create new objects as DRAFT.
LinkedIn campaign creation is multi-step. A campaign group or ad set can remain after a later creative step fails. Inspect the returned IDs, confirm what exists in Campaign Manager, and resume from the failed step. Do not rerun the entire workflow blindly and create duplicates.
## A LinkedIn status change or update is blocked
LinkedIn lifecycle rules can block edits even when OAuth is valid. Retrieve the current object and status, make sure the transition is supported, and apply only the intended field change. For company exclusions, use an additive exclusion workflow so existing targeting is not accidentally replaced.
# Related setup pages
[Connect HireOtto to an AI client](https://docs.hireotto.com/setup/connect-ai-tool)
[LinkedIn Ads quickstart](https://docs.hireotto.com/linkedin-ads/quickstart)
# Still stuck?
Email [suyash@hireotto.com](mailto:suyash@hireotto.com) with:
* The HireOtto server name.
* The AI client you are using.
* The approximate time of the issue.
* The non-sensitive portion of the exact error.
* What you were trying to do and the relevant account or property ID.
Do not send OAuth tokens, passwords, or other secrets.