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://googleadsagent.ai/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.

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

Scoring Methodology

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

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

Audit Categories

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:

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

Anomaly Detection Thresholds

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

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 →