250-Point Audit Engine — Documentation

Complete reference for setup, usage, MCP configuration, scoring methodology, and export formats.

Quick Start

The audit engine is a single HTML file with zero dependencies. No build step, no backend, no npm install.

# Run locally
git clone https://github.com/itallstartedwithaidea/google-ai-agent-audit-engine.git
cd google-ai-agent-audit-engine
open app.html

# Or use the hosted version
https://ahmeego.com/tools/audit-engine/app.html

Architecture

The tool runs entirely in the browser. API keys are stored in your browser's localStorage — they never leave your machine and are never sent to any server except the API endpoints you configure.

Data Flow

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Service APIs   │───▶│  Audit Engine    │───▶│  Strategy Gen   │
│  (via MCP/Keys) │    │  (250 Scoring)   │    │  (30/60/90)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
       ▲                       │                       │
       │                       ▼                       ▼
┌──────┴──────────┐    ┌──────────────────┐    ┌─────────────────┐
│  MCP Servers    │    │  Local Storage   │    │  Export (JSON/   │
│  (Claude Code)  │    │  (Browser)       │    │  CSV/MD/HTML)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Service Connectors

Each connector unlocks specific audit categories. The tool works with any combination — you can run a full manual audit with zero connections.

Connector	Audit Categories Unlocked	API Required
Google Ads API	Foundation, Architecture, Keywords, Creative, Bidding, Audiences, Competitive, Cross-Channel	Developer Token + OAuth
GA4 Admin API	Audiences, Tracking, Cross-Channel	Property ID + OAuth
GTM API	Tracking & Measurement	Account/Container ID + OAuth
Search Console	Keywords, Competitive, Cross-Channel	Site URL + OAuth
PageSpeed Insights	Landing Pages	Free API Key
Merchant Center	Architecture, Cross-Channel	Merchant ID + OAuth
Meta Marketing	Cross-Channel	Access Token + Ad Account ID
Microsoft Ads	Cross-Channel	Customer ID + OAuth
Semrush / SpyFu	Competitive Intelligence	API Key

MCP Server Configuration

MCP (Model Context Protocol) servers allow Claude Code, Claude Desktop, and other AI agents to run the audit autonomously. Each server exposes tools that map directly to audit categories.

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads-audit": {
      "command": "npx",
      "args": ["-y", "@googleadsagent/google-ads-mcp-server"],
      "env": {
        "GOOGLE_ADS_DEV_TOKEN": "your-dev-token",
        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_CUSTOMER_ID": "123-456-7890"
      }
    },
    "ga4-audit": {
      "command": "npx",
      "args": ["-y", "@googleadsagent/ga4-mcp-server"],
      "env": {
        "GA4_PROPERTY_ID": "properties/123456789",
        "GOOGLE_ACCESS_TOKEN": "your-access-token"
      }
    },
    "pagespeed-audit": {
      "command": "npx",
      "args": ["-y", "@googleadsagent/pagespeed-mcp-server"],
      "env": {
        "PAGESPEED_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code Setup

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "google-ads-audit": {
      "command": "npx",
      "args": ["-y", "@googleadsagent/google-ads-mcp-server"]
    }
  }
}

MCP Tools Reference

Server	Tool	Description
google-ads	get_account_settings	Account config, linking, auto-apply settings
google-ads	get_conversion_actions	All conversions with configuration
google-ads	get_campaign_structure	Full hierarchy with settings, budgets, bids
google-ads	get_keyword_report	Keywords with QS, match types, metrics
google-ads	get_search_terms	Search terms with waste identification
google-ads	get_audience_lists	All segments with sizes and recency
google-ads	get_ad_creative	RSAs, extensions, PMax assets + strength
google-ads	get_auction_insights	Competitive metrics across campaigns
google-ads	get_recommendations	Recommendations with auto-apply status
google-ads	get_change_history	Recent changes with attribution
google-ads	get_bidding_diagnostics	Smart bidding signals and learning
google-ads	get_budget_report	Budget utilization, pacing, IS data
ga4	get_property_config	Property settings and linking
ga4	get_event_mapping	Event config and conversion status
ga4	get_audience_definitions	GA4 audiences for import
pagespeed	run_pagespeed_audit	Core Web Vitals + Lighthouse
pagespeed	get_mobile_usability	Mobile performance metrics

Scoring Methodology

Each of the 250 audit points is scored on a 0-4 scale with a weight multiplier (1-3).

Score	Rating	Criteria	Strategy Phase
0	Critical Fail	Not implemented; causing harm or data loss	Days 1-7 emergency
1	Below Standard	Partially implemented; significant gaps	Days 1-30 foundation
2	Meets Baseline	Implemented but not optimized	Days 31-60 optimization
3	Best Practice	Fully optimized per current standards	Days 61-90 maintain
4	Industry Leading	Advanced implementation exceeding standards	Days 61-90 iterate

Account Health Index = (Sum of weighted scores) / (Sum of maximum weighted scores) × 100

Audit Categories

#	Category	Points	Primary Connector
1	Account Foundation & Settings	25 points (1-25)	Google Ads
2	Campaign Architecture & Structure	30 points (26-55)	Google Ads
3	Keyword & Search Term Strategy	30 points (56-85)	Google Ads + Search Console
4	Ad Creative & Messaging	30 points (86-115)	Google Ads
5	Bidding & Budget Strategy	25 points (116-140)	Google Ads
6	Audience Strategy & Data	30 points (141-170)	Google Ads + GA4
7	Landing Pages & Post-Click	25 points (171-195)	PageSpeed + Google Ads
8	Tracking & Measurement	30 points (196-225)	GA4 + GTM + Google Ads
9	Competitive & Market Intelligence	15 points (226-240)	Google Ads + Semrush
10	Cross-Channel Integration	10 points (241-250)	All platforms

Export Formats

JSON (Full Data)

Complete audit data including scores, notes, auto-detected findings, and metadata. Use for importing into other tools, tracking progress over time, or programmatic analysis.

CSV (Spreadsheet)

All 250 items with scores, weights, categories, and notes. Opens directly in Excel, Google Sheets, or any spreadsheet tool for further analysis.

Markdown (Report)

Formatted report with category scores, item-level findings, and strategy. Paste into Notion, Confluence, or any Markdown-compatible system.

Strategy Generation

The 30/60/90 strategy is auto-generated from audit scores:

Days 1-30 (Foundation): All items scored 0-1 (Critical Fail and Below Standard). These represent foundational issues that must be fixed before optimization work can be effective.

Days 31-60 (Optimization): All items scored 2 (Meets Baseline). These represent areas meeting minimum standards but leaving performance on the table.

Days 61-90 (Accelerate): All items scored 3-4 (Best Practice and Leading). These shift to maintenance, iteration, and expansion.

Every strategy action traces back to a specific audit item number, making the recommendation fully accountable and verifiable.

Analysis Protocols

The audit engine follows enterprise-grade analysis protocols from the Google Ads Agent v10.0 architecture:

Context Efficiency Protocol (CEP)

Before deep analysis, the AI asks targeted questions to minimize unnecessary data pulls and focus on what matters:

Tier	Questions	When
1. Identity	Which account? Which campaigns? Which ad groups?	Always
2. Scope	ENABLED only? Date range? Min spend threshold?	Analysis tasks
3. Advisory	What KPIs drive decisions? Conservative or aggressive? Constraints?	Recommendations

6-Tier Filter Priority System

Every data query applies filters in strict order for maximum efficiency:

TIER 1: IDENTITY  → customer_id / account name
TIER 2: STATUS    → ENABLED, PAUSED (exclude REMOVED)
TIER 3: TYPE      → campaign type, match type, device
TIER 4: DATE      → date range (default LAST_30_DAYS)
TIER 5: METRICS   → cost_min, conversions_min (dollars)
TIER 6: SHAPING   → limit, sort_by, detail_level

Top-Down Reporting

Analysis always starts at the account level and drills down on request — never starting with details:

Account Summary → Offer drill-down options → Apply filters → Validate completeness
"These 10 campaigns represent 85% of total spend."

Performance Benchmarks

Metric	Critical	Needs Work	Good	Excellent
Search CTR	<1%	1-3%	3-6%	>6%
Quality Score	<4	4-5	6-7	8-10
Search IS	<20%	20-50%	50-80%	>80%
Conversion Rate	<1%	1-3%	3-5%	>5%
Budget Lost IS	>30%	15-30%	5-15%	<5%
Wasted Spend	>30%	15-30%	5-15%	<5%

Anomaly Detection Thresholds

Signal	Threshold	Action
Spend spike	>50% WoW	Investigate immediately
CTR crash	>40% drop WoW	Check ads and keywords
CPA 3x above target	300% of goal	Conversion tracking or targeting issue
IS drop	>20% decline	Budget or competition shift
QS drop to <4	Below 4	Landing page or ad relevance issue

Safety Rules

The engine follows strict safety protocols for any recommendations:

• Never recommend budget increases >20% without validated conversion tracking

• Never recommend Smart Bidding without 30+ monthly conversions (tCPA) or 50+ (tROAS)

• Never recommend enabling paused campaigns without fixing root cause first

• Always show current vs. proposed values for any change recommendation

• Always quantify impact in dollars

Beyond the Audit — Meet Buddy

Capability	Audit Engine	Buddy
Score 250 audit points	✅	—
Generate strategy document	✅	—
Pull live Google Ads data	✅	✅
Ongoing strategic conversations	—	✅
Pause/enable campaigns live	—	✅
Update budgets live	—	✅
Multi-account management	—	✅
Scan pages for tracking	✅	✅
Web search for intelligence	—	✅
Write ad copy	—	✅
Competitor analysis	Via SearchAPI	✅ (real-time)

Talk to Buddy →

Privacy & Security

Contributing

This is an open-source project. Contributions welcome:

• Vertical experts: Add industry-specific scoring profiles and calibration data

• Platform specialists: Update audit items as Google Ads features evolve

• Developers: Extend connectors for additional platforms

• Practitioners: Share anonymized benchmark data to improve scoring

View on GitHub →