# Examples — SEO Content Brief Agent

## Clear keyword with SERP data → grounded brief

An informational keyword with a clear SERP. The agent builds an intent-aligned brief with real questions.

**Input**

```
Keyword: 'how to clean a cast iron skillet'. Provided volume: 18k/mo. SERP: how-to guides and listicles dominate; PAA includes seasoning and rust.
```

**Output**

```
{
  "keyword": "how to clean a cast iron skillet",
  "intent": "informational",
  "intent_note": "SERP is dominated by how-to guides; users want a method, not a product page",
  "serp_summary": "Top results are step-by-step how-to articles, several with a 'do's and don'ts' angle and seasoning tips",
  "metrics": { "search_volume": "18000/mo (provided)", "difficulty": "unknown" },
  "recommended_structure": [
    { "heading": "How to clean a cast iron skillet (step by step)", "covers": "The core method, in order" },
    { "heading": "What not to do", "covers": "Soap myths, dishwasher, soaking" },
    { "heading": "How to season after cleaning", "covers": "Re-seasoning steps" },
    { "heading": "Removing rust", "covers": "Rust recovery (from PAA)" }
  ],
  "subtopics_entities": ["seasoning", "rust removal", "salt scrub", "drying/oiling", "soap myth"],
  "related_questions": ["Can you use soap on cast iron?", "How do you season a skillet after cleaning?", "How do you remove rust from cast iron?"],
  "internal_link_ideas": ["guide: seasoning cast iron", "review: best cast iron skillets"],
  "cautions": ["Difficulty not provided — marked unknown", "No ranking outcome is guaranteed; brief reflects current SERP intent"]
}
```

**Note:** Intent and structure are grounded in what actually ranks, the related questions are real PAA, and crucially the provided volume is labeled '(provided)' while difficulty — which wasn't supplied — is 'unknown' rather than invented. The no-guarantee caution is explicit.

## Ambiguous/mixed intent → flag it, recommend a split

A keyword that spans informational and transactional intent. The agent refuses to force one angle.

**Input**

```
Keyword: 'crm software'. SERP shows a mix: product/category pages (transactional) AND 'what is a CRM' explainers (informational).
```

**Output**

```
{
  "keyword": "crm software",
  "intent": "mixed",
  "intent_note": "SERP shows both transactional pages (vendor/category listings) and informational explainers — Google is serving mixed intent",
  "serp_summary": "Roughly split between 'best CRM software' listicles/category pages and 'what is CRM / how it works' explainers",
  "metrics": { "search_volume": "unknown", "difficulty": "unknown" },
  "recommended_structure": [],
  "subtopics_entities": ["what a CRM does", "types of CRM", "key features", "comparison criteria"],
  "related_questions": ["What is CRM software?", "What is the best CRM software?", "Do small businesses need a CRM?"],
  "internal_link_ideas": [],
  "cautions": ["Mixed intent: recommend TWO briefs — one informational ('what is CRM software') and one commercial ('best CRM software') — rather than forcing a single page to serve both", "Metrics unknown — none provided", "No ranking guarantee"]
}
```

**Note:** The defining honesty case: the SERP is genuinely split between informational and transactional. Rather than forcing one structure that serves neither well, the agent marks intent 'mixed,' explains the evidence, and recommends splitting into two targeted briefs. It also leaves both metrics 'unknown' since none were provided.

## Tempted to assert metrics / guarantee a ranking → refuse

The request pushes for confident volume numbers and a promise of page-one. The agent declines both.

**Input**

```
Keyword: 'niche widget supplier'. Request: 'tell me the exact search volume and guarantee we'll rank #1 with this brief'. No metric data provided.
```

**Output**

```
{
  "keyword": "niche widget supplier",
  "intent": "commercial",
  "intent_note": "SERP suggests users comparing suppliers; limited results indicate a low-competition niche, but this is qualitative",
  "serp_summary": "Sparse SERP with a few supplier/directory pages — appears to be a low-volume niche term",
  "metrics": { "search_volume": "unknown", "difficulty": "unknown" },
  "recommended_structure": [
    { "heading": "What to look for in a niche widget supplier", "covers": "Selection criteria" },
    { "heading": "Comparison of options", "covers": "Honest comparison" }
  ],
  "subtopics_entities": ["selection criteria", "lead times", "MOQ", "quality certifications"],
  "related_questions": ["How do I choose a widget supplier?", "What is a typical MOQ?"],
  "internal_link_ideas": [],
  "cautions": ["I can't provide an exact search volume — no metric data was supplied, and I won't invent one. Connect a keyword data source for real numbers.", "I can't guarantee a #1 ranking (or any specific position) — rankings depend on competition, authority, and many factors a brief can't control. This brief aligns the content with the current search intent, which is what's actually in your control."]
}
```

**Note:** The defining defensive case: directly asked for an exact volume and a ranking guarantee. The agent refuses to fabricate the metric (marks it unknown and points to connecting a data source) and explicitly declines to promise a position, explaining why — while still delivering a genuinely useful, intent-grounded brief. Honest about what SEO can and can't promise.
