---
name: aeoforge-audit-refresh
description: Use when auditing existing web pages for AEO readiness, comparing articles head-to-head, refreshing stale content, or running competitive analysis against competitor URLs. Triggers on content audit, page comparison, outdated content, content freshness, competitive gap analysis.
---

## Overview

Audit any URL, compare two pieces of content, or generate a refresh plan — the Analyze and Maintain phase of AEOForge. These tools handle the full content improvement lifecycle from assessment through actionable update plans. For a single-call audit+refresh, use `aeo_workflow_audit_improve` instead of chaining `aeo_audit` → `aeo_refresh` manually.

## Mandatory First Steps (do these BEFORE any tool call)

1. Call `aeo_account` (or `GET /api/v1/me`) — verify auth, check credits and tier
2. Call `GET /api/v1/onboard` — receive full product context, scoring rubric, and workflow guidance
3. **Read the onboard response fully** — it contains the scoring dimensions and weights that audit and compare tools evaluate against

## When to Use

- Auditing an existing page for AEO readiness
- Comparing two articles for competitive analysis
- Refreshing stale or outdated content
- Running competitive gap analysis against rivals
- Building a content improvement backlog

## Quick Reference

| Tool | Credits | Purpose |
|------|---------|---------|
| `aeo_audit` | 5 | Deep AEO audit of a URL or markdown with scoring and recommendations |
| `aeo_compare` | 3 | Head-to-head comparison of two content pieces with gap analysis |
| `aeo_refresh` | 8 | Generate a structured update plan for stale content |
| `aeo_workflow_audit_improve` | 5-13 | Single-call audit + conditional refresh workflow |

## Core Patterns

- Use `targetKeyword` on audit for competitive research context; omit for standalone page assessment
- Compare returns `marginOfVictory` — useful for prioritizing which gaps to close first
- Refresh returns `confidenceLevel` — high means the update plan is grounded in strong research
- Check `content_is_fresh` before implementing — content may already be adequate
- URL inputs get JSON-LD detection automatically; markdown inputs don't
- Standard workflow: Audit → Compare → Refresh (assess, benchmark, then plan improvements)
- Pass audit results into compare for richer competitive context
- Use `aeo_score` (free) as a quick pre-check before spending 5cr on a full audit

## Common Mistakes

- Auditing without keyword — misses competitive context and SERP positioning data
- Comparing markdown vs URL — inconsistent JSON-LD detection skews structured data scoring
- Running refresh on already-fresh content — wastes 8cr when `content_is_fresh` is true
- Ignoring `hallucinatedKeywords` in cluster results that feed into audit planning
- Not checking `researchAvailable` in audit response — if false, competitive recommendations are limited
- Running compare on identical content — returns zero-value results, wastes 3cr