Get Peec's opportunity-scored action recommendations for improving brand visibility in AI search engines. **Always call with `scope=overview` first** to see which slices have the biggest opportunity, then drill down into `owned`, `editorial`, `reference`, or `ugc` with the surfaced url_classification or domain.
## Required parameters (read before calling)
Every call must include:
- `project_id` — the project to analyze.
- `scope` — one of `overview` | `owned` | `editorial` | `reference` | `ugc`. **Start with `scope=overview`.**
Recommended:
- `start_date` and `end_date` (ISO YYYY-MM-DD). Optional — if omitted, defaults to the last 30 days (today − 30d to today). Prefer a 30-day window unless the user asks for a different one.
Per-scope extras (the call will fail without them):
- `scope=owned` → `url_classification` is **required** (e.g. "LISTICLE").
- `scope=editorial` → `url_classification` is **required** (e.g. "LISTICLE").
- `scope=reference` → `domain` is **required** (e.g. "wikipedia.org").
- `scope=ugc` → `domain` is **required** (e.g. "reddit.com", "youtube.com").
- `scope=overview` → no extras beyond the base params.
Use this tool whenever the user asks for recommendations, next steps, what to do, how to improve, "what actions should I take", or any "based on this data, what should I do?" question. Never invent SEO advice.
## Two-step workflow
**Step 1 — `scope=overview`:** returns opportunity rollups grouped by `action_group_type` × (`url_classification` | `domain`). These are *navigation metadata*, NOT the recommendations themselves. Use them to find which slices have the largest gap.
**Step 2 — drill down:** for each high-opportunity slice, call again with the matching scope (`owned` | `editorial` | `reference` | `ugc`) to get the actual textual recommendations (the `text` column, often with markdown links to examples or targets).
Mapping — how to turn an overview row into the follow-up call:
- `action_group_type=OWNED`, `url_classification=X` → call `scope=owned, url_classification=X`.
- `action_group_type=EDITORIAL`, `url_classification=X` → call `scope=editorial, url_classification=X`.
- `action_group_type=REFERENCE`, `domain=Y` → call `scope=reference, domain=Y`.
- `action_group_type=UGC`, `domain=Y` → call `scope=ugc, domain=Y`.
Worked example — overview returns a row `{action_group_type: "UGC", domain: "youtube.com", opportunity_score: 0.30, ...}`. Follow up with `scope=ugc, domain="youtube.com"` and you get rows like `{text: "Contact [AutoPedia](https://...). Ask them for a collaboration.", group_type: "UGC", domain: "youtube.com", opportunity_score: 3, ...}`.
## Response shape
Returns columnar JSON: `{columns, rows, rowCount}`. Each row is an array of values matching column order.
**`scope=overview` columns:**
- `action_group_type`: OWNED | EDITORIAL | REFERENCE | UGC
- `url_classification`: populated for OWNED / EDITORIAL rows (e.g. "LISTICLE", "ARTICLE", "COMPARISON"). `null` for REFERENCE / UGC.
- `domain`: populated for REFERENCE / UGC rows (e.g. "youtube.com", "wikipedia.org"). `null` for OWNED / EDITORIAL.
- `opportunity_score`: continuous. **Use this to sort and rank** — it's the reliable ordering signal.
- `relative_opportunity_score`: 1–3 tier (1=Low, 2=Medium, 3=High). **Use this to label** strength in prose. Too coarse to sort by.
- `gap_percentage`, `coverage_percentage`, `used_ratio`, `used_total`: supporting stats.
Exactly one of `url_classification` / `domain` is populated per overview row — that's the value to pass to the follow-up call.
**`scope=owned | editorial | reference | ugc` columns:**
- `text`: the recommendation string; may include markdown links.
- `group_type`: OWNED | EDITORIAL | REFERENCE | UGC.
- `url_classification`: e.g. "LISTICLE" (may be null).
- `domain`: e.g. "youtube.com" (may be null).
- `opportunity_score`: continuous — sort/rank by this.
- `relative_opportunity_score`: 1–3 tier — label strength with this (1=Low, 2=Medium, 3=High).
## Presenting results
After overview + drill-downs, pick the shape that fits:
- **Strong signal** (top slice's `opportunity_score` is clearly ahead AND its drill-down returned 2+ rows whose `text` contains a markdown link): one sentence of reasoning tied to the user's question (call out the biggest lever), then 2-3 named slices with 2-3 bullets pulled verbatim from the drill-down `text`.
- **Moderate signal**: compact list, one sentence per slice, bullets only where drill-down returned specific targets.
- **Low signal** (overview empty or top `opportunity_score` very low): single line, e.g., "Top opportunity: {slice} (Low). Low signal this period; prompts need a few more daily cycles to stabilize."
## Display conventions — never use raw enum keys in user-facing prose
**Group type** (`action_group_type` / `group_type`) — humanize (Title Case):
- `OWNED` → "Owned" (content on your own domains)
- `EDITORIAL` → "Editorial" (third-party editorial coverage — news, blogs, reviews)
- `REFERENCE` → "Reference" (reference sources like Wikipedia)
- `UGC` → "UGC" (user-generated content — Reddit, YouTube, forums; keep as acronym)
- `OTHER` → "Other"
**URL classification** (`url_classification`) — humanize to lowercase; pluralize naturally when the sentence calls for it:
- `HOMEPAGE` → "homepage"
- `CATEGORY_PAGE` → "category page"
- `PRODUCT_PAGE` → "product page"
- `LISTICLE` → "listicle"
- `COMPARISON` → "comparison page"
- `PROFILE` → "profile"
- `ALTERNATIVE` → "alternative"
- `DISCUSSION` → "discussion"
- `HOW_TO_GUIDE` → "how-to guide"
- `ARTICLE` → "article"
- `OTHER` → "other"
**Opportunity strength** — lead with a **Low / Medium / High** label derived from `relative_opportunity_score` (round to nearest integer, clamp to [1, 3]):
- 1 → "Low"
- 2 → "Medium"
- 3 → "High"
Sort and rank by `opportunity_score` (continuous). **Verbalize** strength with the Low/Medium/High tier above. The raw `opportunity_score` is optional supporting context in parens — never the headline number.
**Gap percentage** (`gap_percentage`, 0–1 ratio) — lead with a plain-language qualifier; the raw % can follow in parens when useful:
- ≥0.90 → "nearly all missing"
- 0.60–0.89 → "wide gap"
- 0.30–0.59 → "partial gap"
- <0.30 → "narrow gap"
**Example of the preferred style** (follow this phrasing):
> The biggest lever is Owned listicles — High, nearly all missing (100%). Build listicle-style pages on yourbrand.com that target "best X" queries.
>
> Secondary: YouTube UGC (Medium, wide gap), Reddit UGC (Medium, partial gap), Editorial listicles (Medium, nearly all missing). Full list: https://app.peec.ai/actions.
Close with one line: "Secondary opportunities: {slice} ({Low|Medium|High}), {slice} ({Low|Medium|High}). Full list: https://app.peec.ai/actions."
Use the drill-down `text` field as the source of truth. Never invent recommendations, targets, or names. Sort by `opportunity_score`; label strength via `relative_opportunity_score`.