> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rankforce.co/llms.txt
> Use this file to discover all available pages before exploring further.
# SEO Optimization Agent: automatic on-page SEO fixes
> Rankforce's SEO Optimization Agent audits meta titles, descriptions, headings, internal links, and image alt text — then applies precise, approved fixes.
The SEO Optimization Agent is Rankforce's core on-page engine. It crawls every page of your site on a configurable schedule, identifies exactly what is holding your content back from ranking, and proposes precise, explainable fixes — from rewriting a weak meta title to threading a missing internal link into an existing paragraph. You stay in control: every recommendation is transparent, and nothing changes on your live site until you approve it.
## What the agent audits
The SEO Optimization Agent checks five categories of on-page signals during every crawl.
Detects titles that are too short, too long, missing the primary keyword, duplicated across pages, or poorly structured for click-through.
Flags missing, truncated, duplicate, or low-CTR descriptions and rewrites them to include target keywords and a natural call to action.
Identifies missing H1s, multiple H1s on a single page, keyword-absent headings, and heading hierarchy violations.
Finds pages with too few inbound links, detects orphaned content, and suggests contextually relevant anchor-text links within existing copy.
Audits every image for missing or generic alt attributes and generates descriptive, keyword-aware replacements.
## How crawling works
When you connect your site to Rankforce, the agent performs an initial full-site crawl to establish a baseline. After that, it runs incremental crawls on the schedule you set — as frequently as daily or as infrequently as weekly. Each crawl compares the current state of every page against the baseline and against Rankforce's continuously updated ranking-signal model.
The agent analyzes several layers of signals during each crawl:
* **SERP data** — live rankings, featured-snippet winners, and People Also Ask questions for your target keywords
* **Competitor benchmarks** — the title, heading, and link patterns of pages currently outranking yours
* **Site-wide patterns** — duplicate metadata, internal link equity distribution, and crawl-depth bottlenecks
* **Plugin field state** — the current values stored in Yoast, Rank Math, or AIOSEO (see [SEO plugin integration](#seo-plugin-integration))
The agent never modifies your site during a crawl. All proposed changes are queued in your Recommendations inbox and applied only after you approve them.
## Types of fixes the agent generates
### Meta title rewrites
The agent rewrites meta titles that are missing the primary keyword, are outside the 50–60 character optimal range, or share the same wording as another page on your site.
**Example — before:** `Welcome to Our Blog | Acme`\
**Example — after:** `B2B SaaS Marketing Blog: Strategy, Tactics & Guides | Acme`
### Meta description rewrites
Descriptions are rewritten to include the primary keyword naturally, stay within 130–155 characters, and contain a concrete value proposition that encourages clicks.
**Example — before:** `Read our latest articles on marketing.`\
**Example — after:** `Explore proven B2B SaaS marketing strategies — from demand generation to product-led growth. Updated weekly with actionable guides and real-world examples.`
### Heading restructures
The agent proposes heading changes to fix hierarchy issues (e.g., an H3 with no parent H2), add missing primary or secondary keywords to headings, and break up walls of text with subheadings.
**Example — before:** A 1,400-word article with a single H1 and no H2s.\
**Example — after:** H1 retained; four H2s inserted at logical section breaks, each incorporating a secondary keyword phrase.
### Internal link insertions
The agent identifies sentences in existing content where a contextual link to another page on your site would be natural, and suggests the exact anchor text and destination URL.
**Example:** In a paragraph discussing "email deliverability," the agent suggests adding an internal link to your `/guides/email-warm-up` page using the anchor text "email warm-up."
### Image alt text generation
Every image with a missing, empty, or placeholder alt attribute (`alt=""`, `alt="image"`) receives a proposed replacement that describes the image accurately and, where appropriate, incorporates a keyword phrase.
**Example — before:** `alt="DSC_4821.jpg"`\
**Example — after:** `alt="Marketing team reviewing a B2B SaaS content calendar on a whiteboard"`
## Configuring the SEO agent
### Enable or disable the agent
You can toggle the SEO Optimization Agent on or off from **Settings → Agents → SEO Optimization**. Disabling the agent pauses all future crawls and freezes the Recommendations inbox — existing approved changes are not rolled back.
### Set crawl frequency
Navigate to **Settings → Agents → SEO Optimization** and click **Crawl Schedule**.
Select **Daily**, **Every 3 days**, or **Weekly**. Larger sites with frequent content updates benefit from daily crawls; smaller, slower-moving sites can use weekly.
Optionally restrict crawls to a specific time window (e.g., 02:00–04:00 UTC) to avoid any performance impact during peak traffic hours.
Click **Save**. To run a crawl right now outside the schedule, click **Run crawl now**.
### Exclude URLs from crawling
If certain pages should never be audited (staging paths, gated member areas, campaign landing pages under active A/B tests), add them to the exclusion list.
Go to **Settings → Agents → SEO Optimization → Exclusions**.
Enter exact URLs or wildcard patterns. For example, `/staging/*` excludes all paths beginning with `/staging/`.
Click **Save exclusions**. Excluded pages are removed from the current queue and will not appear in future Recommendations.
Use exclusions sparingly. Excluding a page prevents the agent from surfacing SEO issues that may be costing you rankings. If a page is genuinely live and indexable, it's usually worth auditing.
## SEO plugin integration
Rankforce reads from and writes to the three most widely used WordPress SEO plugins: **Rank Math**, **Yoast SEO**, and **All in One SEO (AIOSEO)**. The agent automatically detects which plugin is active on your WordPress site during initial connection.
### How the agent reads plugin fields
During each crawl, the agent reads the SEO fields managed by your active plugin — including meta title, meta description, focus keyword, and robots directives — for every page on your site. No additional configuration is required; Rankforce detects the active plugin automatically and reads its stored values.
### How the agent writes approved changes
When you approve a meta title or description recommendation, Rankforce writes the updated value directly to your SEO plugin using the same integration path the plugin itself uses. This means:
* Your SEO plugin's dashboard continues to show accurate, up-to-date values
* No duplicate or conflicting meta tags are introduced
* The change is visible in your plugin immediately after approval
If you have **both** Yoast and Rank Math active simultaneously, Rankforce will prompt you to designate one as the primary plugin during onboarding. Running two SEO plugins at once can cause duplicate meta tags and is generally not recommended.
### Framer sites
On Framer, the agent reads and writes SEO fields through the Rankforce Framer plugin, which surfaces title and description controls for every page. Heading structure and alt text are updated via direct CMS field edits that sync back to your published site automatically.
## Reviewing and approving recommendations
All proposed changes appear in the **Recommendations** inbox at **SEO → Recommendations**.
Each card shows the page URL, the change type (e.g., "Meta title rewrite"), the current value, the proposed value, and the agent's reasoning — including the specific signal that triggered the suggestion.
Click **Approve** to apply the change immediately, **Edit** to modify the proposed value before applying, or **Reject** to dismiss the recommendation. Rejected recommendations can be retrieved from **Recommendations → Rejected** at any time.
Use the checkbox selector to approve or reject multiple recommendations at once. Bulk actions are available when all selected items are the same change type.
After approval, Rankforce confirms the write succeeded and logs the change in **History**. You can undo any applied change from the History view within 30 days.
In **Full Autopilot** mode, the agent applies recommendations automatically without requiring your approval. You still receive a daily digest email summarizing every change made. You can switch modes at any time under **Settings → Agents → SEO Optimization → Mode**.
Supervised mode sits between Manual and Full Autopilot. The agent queues recommendations as normal, but automatically applies any change that falls below a configurable risk threshold — for example, fixing a missing alt text attribute is low-risk and will be applied automatically, while restructuring an H1 on a high-traffic page is flagged for your explicit review. You set the risk threshold in **Settings → Agents → SEO Optimization → Supervised Mode Settings**.