seo/META_DESCRIPTION_GUIDE.md

Meta Description Generation Guide

AI-powered meta description generation and optimization for WordPress posts.

Overview

The meta description generator uses AI to create SEO-optimized meta descriptions for your blog posts. It can:

• Generate new meta descriptions for posts without them
• Improve existing meta descriptions that are poor quality
• Optimize length (120-160 characters - ideal for SEO)
• Include focus keywords naturally
• Add call-to-action elements when appropriate

Usage

Generate for All Posts

# Generate meta descriptions for all posts
./seo meta_description

# Use a specific CSV file
./seo meta_description output/all_posts_2026-02-16.csv

Generate Only for Missing Meta Descriptions

# Only generate for posts without meta descriptions
./seo meta_description --only-missing

Improve Poor Quality Meta Descriptions

# Only regenerate meta descriptions with poor quality scores
./seo meta_description --only-poor

# Limit to first 10 poor quality meta descriptions
./seo meta_description --only-poor --limit 10

Dry Run Mode

Preview what would be processed:

./seo meta_description --dry-run
./seo meta_description --dry-run --only-missing

Command Options

Option	Description
--only-missing	Only generate for posts without meta descriptions
--only-poor	Only generate for posts with poor quality meta descriptions
--limit <N>	Limit number of posts to process
--output, -o	Custom output file path
--dry-run	Preview without generating
--verbose, -v	Enable verbose logging

How It Works

1. Content Analysis

The AI analyzes:

• Post title
• Content preview (first 500 characters)
• Excerpt (if available)
• Focus keyword (if specified)
• Current meta description (if exists)

2. AI Generation

The AI generates meta descriptions following SEO best practices:

• Length: 120-160 characters (optimal for search engines)
• Keywords: Naturally includes focus keyword
• Compelling: Action-oriented and engaging
• Accurate: Clearly describes post content
• Active voice: Uses active rather than passive voice
• Call-to-action: Includes CTA when appropriate

3. Quality Validation

Each generated meta description is scored on:

• Length optimization (120-160 chars = 100 points)
• Proper ending (period = +5 points)
• Call-to-action words (+5 points)
• Overall quality (minimum 70 points to pass)

4. Output

Results are saved to CSV with:

• Original meta description
• Generated meta description
• Length of generated meta
• Validation score (0-100)
• Whether length is optimal
• Whether it's an improvement

Output Format

The tool generates a CSV file in output/:

output/meta_descriptions_20260216_143022.csv

CSV Columns

Column	Description
post_id	WordPress post ID
site	Site name
title	Post title
current_meta_description	Existing meta (if any)
generated_meta_description	AI-generated meta
generated_length	Character count
validation_score	Quality score (0-100)
is_optimal_length	True if 120-160 chars
improvement	True if better than current
status	Generation status

Examples

Example 1: Generate All Missing Meta Descriptions

# Export posts first
./seo export

# Generate meta descriptions for posts without them
./seo meta_description --only-missing

Output:

Generating AI-optimized meta descriptions...
  Filter: Only posts without meta descriptions
Processing post 1/45
✓ Generated meta description (score: 95, length: 155)
...

✅ Meta description generation completed!
  Results: output/meta_descriptions_20260216_143022.csv

📊 Summary:
  Total processed: 45
  Improved: 42 (93.3%)
  Optimal length: 40 (88.9%)
  Average score: 92.5
  API calls: 45

Example 2: Fix Poor Quality Meta Descriptions

# Only improve meta descriptions scoring below 70
./seo meta_description --only-poor --limit 20

Example 3: Test with Small Batch

# Test with first 5 posts
./seo meta_description --limit 5

Example 4: Custom Output File

./seo meta_description --output output/custom_meta_gen.csv

Meta Description Quality Scoring

Scoring Criteria

Criteria	Points
Optimal length (120-160 chars)	100
Too short (< 120 chars)	50 - (deficit)
Too long (> 160 chars)	50 - (excess)
Ends with period	+5
Contains CTA words	+5

Quality Thresholds

• Excellent (90-100): Ready to use
• Good (70-89): Minor improvements possible
• Poor (< 70): Needs regeneration

CTA Words Detected

The system looks for action words like:

• learn, discover, find, explore
• read, get, see, try, start
• and more...

Best Practices

Before Generation

1. Export fresh data - Ensure you have latest posts

   ./seo export
   

2. Review focus keywords - Posts with focus keywords get better results

3. Test with small batch - Try with --limit 5 first

During Generation

1. Monitor scores - Watch validation scores in real-time
2. Check API usage - Track number of API calls
3. Use filters - Target only what needs improvement

After Generation

1. Review results - Open the CSV and check generated metas
2. Manual approval - Don't auto-publish; review first
3. A/B test - Compare performance of new vs old metas

Integration with WordPress

Manual Update

1. Open the generated CSV: output/meta_descriptions_*.csv
2. Copy generated meta descriptions
3. Update in WordPress SEO plugin (RankMath, Yoast, etc.)

Automated Update (Future)

Future versions may support direct WordPress updates:

# Not yet implemented
./seo meta_description --apply-to-wordpress

API Usage & Cost

API Calls

• Each post requires 1 API call
• Rate limited to 2 calls/second (0.5s delay)
• Uses Claude AI via OpenRouter

Estimated Cost

Approximate cost per 1000 meta descriptions:

• ~$0.50 - $2.00 depending on content length
• Check OpenRouter pricing for current rates

Monitoring

The summary shows:

• Total API calls made
• Cost tracking (if enabled)

Troubleshooting

No Posts to Process

Problem: "No posts to process"

Solutions:

1. Export posts first: ./seo export
2. Check CSV has required columns
3. Verify filter isn't too restrictive

Low Quality Scores

Problem: Generated metas scoring below 70

Solutions:

1. Add focus keywords to posts
2. Provide better content previews
3. Try regenerating with different parameters

API Errors

Problem: "API call failed"

Solutions:

1. Check internet connection
2. Verify API key in .env
3. Check OpenRouter account status
4. Reduce batch size with --limit

Rate Limiting

Problem: Too many API calls

Solutions:

1. Use --limit to batch process
2. Wait between batches
3. Upgrade API plan if needed

Comparison with Other Tools

Feature	This Tool	Other SEO Tools
AI-powered	✅ Yes	⚠️ Sometimes
Batch processing	✅ Yes	✅ Yes
Quality scoring	✅ Yes	❌ No
Custom prompts	✅ Yes	❌ No
WordPress integration	⚠️ Manual	✅ Some
Cost	Pay-per-use	Monthly subscription

Related Commands

• seo export - Export posts for analysis
• seo analyze - AI analysis with recommendations
• seo seo_check - SEO quality checking

See Also

• README.md - Main documentation
• ENHANCED_ANALYSIS_GUIDE.md - AI analysis guide
• EDITORIAL_STRATEGY_GUIDE.md - Content strategy

---

Made with ❤️ for better SEO automation