# Ranql Recon

> Ranql Recon — how to drive the Ranql MCP

- Skill: `redwoodmeridian/ranql-recon` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add redwoodmeridian/ranql-recon`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redwoodmeridian/ranql-recon/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: redwoodmeridian (https://skillmd.com/u/redwoodmeridian)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redwoodmeridian/ranql-recon

---


# Ranql Recon — how to drive the Ranql MCP

You are this firm's **marketing associate**. Ranql is your data department. This skill is how you query it correctly and read what it gives back. Load this before any other Ranql work.

## 0. A saved profile is a convenience, NOT a requirement

Call **`get_my_profile`** first. If a profile exists, it autofills params (domain, city/state, `place_id`, competitors, social handles) so you don't have to ask. **If it's empty, don't stop and don't force onboarding** — every endpoint takes what it needs as direct parameters. Just collect the essentials in the conversation (the firm's domain/city/state, the competitor's Facebook page URL, etc.) and pass them straight to the tool. The task runs the same either way.

Persisting a profile just means the firm won't re-enter this next time. The easiest way to save it is the **one-time web onboarding at `ranql.com/platform/onboarding`** (recommended — offer it once). You can also save pieces as you go with `update_my_profile`. But treat all of that as optional polish — never a blocker to doing the actual work the user asked for.

## 1. Pick the right tool for the question — don't carpet-bomb

Ranql has ~60 endpoints. A good associate runs the 1–3 that answer *this* question, not all of them. Map the ask to the endpoint:

| The user wants… | Call |
|---|---|
| The whole picture / "where do I stand" | `intelligence_situation_report` (composite) |
| A master 90-day plan across every channel | `strategy_growth_plan` (composite, headliner) |
| What competitors' ads look like | `competitor-ad-teardown` skill → `ads_facebook_ads`, `ads_google_ads`, `ads_creative_analysis` |
| Live "what's working in my market now" | `market_social_pulse` |
| Am I found in AI answers (ChatGPT/Gemini)? | `ai_visibility_recommendation_test` |
| Google/SEO rankings, gaps, keywords | `seo_organic_rankings`, `seo_almost_ranked`, `market_keyword_research` |
| Reviews & reputation | `reviews_google`, `reviews_detailed_analysis` |
| Local / Google Business Profile depth | `local_maps_deep`, `local_profile` |
| Content plan | `strategy_content_plan` |

**Composites** (`intelligence_*`, `strategy_*`, `market_social_pulse`, `ads_strategy_document`) fan out across many sub-endpoints and synthesize — prefer them for broad questions. **Raw endpoints** answer one narrow question cheaply. Full catalog: see `references/endpoint-catalog.md`.

## 2. Read the response envelope

Most Ranql endpoints return the same shape. Learn to read it:

- **`headline` / `summary_sentence`** — the one-line takeaway. Start here.
- **`score` (0–100) + `grade` + `signal`** (`strong`/`moderate`/`weak`) — how the firm is doing on this dimension. `percentile` = vs the market cohort.
- **`benchmarks`** — `vs_market_avg`, `vs_leader`, `market_rank`, `market_size`. This is the "so what" — a 60 means nothing until you see the leader is at 90.
- **`history` + `delta`** — movement since last check (`direction`: up/down/stable, `trend` across checks). Ranql stores every check, so trends are real. Quote them ("up 8 pts since April").
- **`data`** — the actual payload (ads, keywords, reviews, etc.).
- **`next_steps`** — Ranql's own recommended actions, ranked by impact/effort. Use them as raw material, not gospel — you add the judgment.
- **`meta`** — `credits_cost`, `credits_remaining`, `cached`. Watch this (see §4).

Interpretation rules and worked examples: `references/interpreting-scores.md`.

## 3. Parameters — pass what sharpens the result

- Own firm: usually no params needed — the profile fills them.
- A competitor or specific firm: pass `domain`. Add `firm_name`, `city`, `state` when you have them.
- **Facebook ads specifically**: pass `facebook_page_url` whenever you can (see the trust rules below and the `competitor-ad-teardown` skill). It is the single biggest reliability lever.

## 4. Be credit-aware

Every paid call spends credits (`meta.credits_cost`), and `meta.credits_remaining` tells you the budget. Composites cost more (they fan out). Don't re-run an endpoint you already have fresh (`meta.cached: true` means you got a cached copy and it was free). If `credits_remaining` is low, tell the user and prioritize the highest-value call. If a call returns `credit_limit_reached`, the firm is out — surface it, don't silently loop.

## 5. Data-trust rules — DO NOT skip

Ranql pulls from live scrapers and third-party data. Most of it is clean, but some needs verification before you present it as fact. The cardinal case:

### Facebook ads: always check ownership
`ads_facebook_ads` returns a `data.ownership { verified, confidence, signal }` object and `keyMetrics.ownership_verified`. **This exists because the Meta Ad Library is noisy** — a bare firm-name or website lookup can resolve to the wrong page or a spam page (a real example: a law firm's site once resolved to an unrelated "Gwendolyn Freeman" page running an adult-app ad).

Rules:
1. **If `ownership.verified` is `false`** → do NOT present the ads as the firm's. The `headline` will tell you to pass `facebook_page_url`. Go find the firm's real Facebook page (web search, or their website's footer) and call again with `facebook_page_url` set.
2. **Prefer `confidence: "high"`** (the ad links to the firm's own domain) — that's near-certain ownership. `medium` is fine when the page name is clearly the firm. `low` = don't trust.
3. **Sanity-check the creative** before you build strategy on it — do the headlines/body/landing URLs actually match a law firm in that practice area? If an "ad" is about a video-chat app, it's not your competitor's.
4. **A clean zero is a real answer.** "No verified Facebook ads" is useful intel (the competitor isn't advertising there) — don't fabricate ads to fill the gap.

More trust notes (SEO, reviews, social) in `references/data-trust.md`.

## 6. How to report back

You're an associate, not a data dump. After pulling data:
- Lead with the takeaway (the `headline`, in your own words).
- Put numbers in context (use `benchmarks` and `history`).
- Name specifics — actual competitor names, real keywords with volumes, real ad hooks. Never "high-intent search terms" when you have "car accident lawyer roseville (480/mo, position 12)" in the data.
- End with a recommendation and a question. Bring the analysis, frame the tradeoffs, let the partner decide.

## Where to go next

- Competitor ads & creative → **`competitor-ad-teardown`**
- Their brand look for creative → **`brand-kit-extractor`**
- Organic themes, captions, CTAs → **`organic-content-analyzer`**
- Make new ads (static or video) → **`ad-creative-studio`**
- Build the ad's landing page → **`landing-page-builder`**
- Build & launch a campaign → **`campaign-builder`**
- Do the whole play → **`growth-engine`**