Instructions for Claude & other LLM callers

You have access to the AgenticSEO MCP server (also reachable as a REST API at /v1/*).
Use it to run SEO + AI-visibility analyses and to read AI Visibility scores for the
company or client your bearer token is bound to.

TOOLS AVAILABLE
- discover_site(url, max_urls?, async?)             → list every reachable page on a site
- analyze_site({url|discovery_id, select|urls|max_pages, brand_name?}) → enqueue a report
- get_job_status(job_id)                            → poll until status="done" (yields report_id)
- get_report(report_id)                             → full per-page report
- get_llms_txt(report_id)                           → site-wide llms.txt text (covers the FULL
                                                     discovered URL set, not just the deep-analyzed
                                                     subset — safe to publish as-is)
- list_reports(limit?, brand?, host?)               → recent reports visible to this token
- get_visibility_scores(brand?, host?)              → latest AI visibility rollup + DIAGNOSTICS
- analyze_ai_visibility(url, ...)                   → COLD-START: URL → prompt-rank snapshot in one call
                                                      Pass { async: true } for brand-new brands to avoid the
                                                      150s client idle timeout — returns { job_id } immediately.
- get_analyze_visibility_status(job_id)             → poll async analyze_ai_visibility jobs every ~5s until
                                                      status="done"; response includes result + company_id.
- enable_visibility_monitoring(company_id, cadence?)→ turn on scheduled recomputes for a company
- get_visibility_trend(company_id, window_days?)    → time-series + deltas + new/lost competitors
- list_prompts(company_id?|brand?|host?, limit?, enabled_only?) → tracking prompts + latest run per prompt
- get_prompt_history(prompt_id, window_days?, limit?) → per-prompt run history for charting change over time
- list_prompt_page_mappings(company_id?|brand?|host?, limit?, only_gaps?, only_covered?, min_score?)
                                                     → for every tracked prompt, best existing page + relevance score
                                                       (mirror image of gap-pages — ranks brand's pages by real prompt demand)
- get_prompt_page_mapping(prompt_id)                → single prompt's best-page mapping (drill-in)
- get_ai_crawler_access(url)                        → standalone Layer 3 audit: /robots.txt allow/deny for every
                                                     tracked AI crawler + copy-paste fix snippet. No prior report needed.
- get_gsc_performance({company_id?|brand?|host?, days?}) → REAL Google Search Console numbers for the company:
                                                      clicks, impressions, CTR, impression-weighted avg position,
                                                      daily trend, previous-window comparison, and the top 25
                                                      queries + pages ranked by IMPRESSIONS (surfaces page-two
                                                      near-misses). Measured Google data, not an estimate.
                                                      Available on every tier, no scope, no credit cost.
- list_gsc_properties({company_id?|brand?|host?})   → verified Search Console properties covering the company's
                                                      site + which one is currently bound.
- select_gsc_property({site_url, company_id?})      → bind one property (must be from list_gsc_properties).
                                                      Requires scope analyze.
- draft_faqs_for_gaps(prompts?, limit?, refresh?)   → draft copy-paste FAQ Q&A pairs for tracked-prompt content gaps.
                                                     Cached; only spends AI credits on new prompts or when refresh=true.
                                                     Requires scope faq:draft.
- publish_faq_to_target(prompts, target?)           → forward cached FAQ drafts to a connected downstream target
                                                     (Quid today, more adapters coming). Never invents content.
                                                     Requires scope faq:publish.
- list_publish_targets()                            → list downstream targets available to publish_faq_to_target.
- list_competitors(company_id?|brand?|host?)        → list tracked competitors (source: "auto" | "manual").
- discover_competitors({company?, persist?, replace?}) → re-run auto discovery. Preview by default; persist=true
                                                     writes new suggestions (requires competitors:write).
                                                     replace=true prunes stale auto entries — manual are preserved.
- add_competitors({competitors:[{name, domain?}], company?}) → add user-picked competitors (source="manual").
                                                     Requires scope competitors:write.
- remove_competitors({ids?|names?, company?})       → soft-delete competitors so future runs ignore them.
                                                     Requires scope competitors:write.
- run_prompts_now({company_id|brand|host, window_days?}) → headless re-score: fans out every enabled tracked
                                                      prompt and computes a fresh visibility rollup. Returns
                                                      score_id, computed_at, data_ready. Requires scope analyze.
- get_run_status({company_id|brand|host})           → poll latest score + in-flight/complete run counts. Use to
                                                      wait for run_prompts_now to land before reading scores.
- generate_benchmark_ideas({company_id|url|host|brand, metrics?, style?}) →
                                                      Gemini-backed idea generator for the four benchmark metrics
                                                      (brand_mention, domain_citation, share_of_voice,
                                                      prompt_win_rate). Returns 5–7 grounded, prioritised
                                                      recommendations per requested metric. style="neutral" strips
                                                      TGF/Market Engineering framing for white-label; default
                                                      style="finn". Safe to call in a loop after
                                                      get_visibility_scores whenever a metric looks weak.

HEADLESS RE-SCORE FLOW (no UI needed)
After analyze_ai_visibility (or any time the user wants fresh numbers) call
run_prompts_now({company_id}). It runs synchronously (30–120s on large sets)
and, on return, get_visibility_scores / get_visibility_trend reflect the new
run. For a non-blocking pattern, kick off run_prompts_now on a background
task and poll get_run_status until data_ready:true.

HOW BUYER PROMPTS ARE GENERATED (what to tell end users)
When a client asks "how are you coming up with the buyer prompts?", the answer is:
  1. We read the website the client (or the OEM caller) supplied and take a compact
     snapshot of what each page is about (topic, product names, primary domain).
  2. We combine that with the company brief on file (industry, audience, value
     proposition, focus keywords, tone) and the tracked-competitor list.
  3. That context is sent to our AI, which returns a de-duplicated set of
     buyer-intent prompts across awareness, consideration, and decision stages —
     anchored to what the site actually sells, not generic keyword bait.
     Existing tracked prompts are excluded so nothing repeats.
  4. When only the website is available (no brief yet), the crawl alone is enough
     to seed a first prompt set. Filling in the brief and competitors sharpens
     subsequent generations.

FORCE RECOMPUTE ON DEMAND (the "Run prompts & recompute" equivalent)
Use this any time you want fresh AI-visibility numbers without waiting for the
monthly schedule — e.g. after the client publishes a fix, ships new pages, or
updates FAQs. This is the headless equivalent of the "Run prompts & recompute"
button in the app UI.

  1. analyze_ai_visibility({ brand | host | company_id })
       Seeds or refreshes the company, competitors, and prompt matrix. Idempotent
       on repeat calls — safe to call every time. On timeout, fall back to
       resolve_company({ url }) to recover the company_id, then continue.
  2. run_prompts_now({ company_id })
       Fans out every enabled tracked prompt to the LLMs and triggers a fresh
       visibility rollup. Returns { score_id, computed_at, data_ready }.
  3. Poll get_run_status({ company_id }) every 5s until data_ready:true.
       Typical 30–120s; large prompt sets can take up to ~5 min. Give up after
       ~6 min and surface the partial result — the run keeps completing server-side.
  4. get_visibility_scores({ company_id })
       Read the fresh scorecard: presence %, share-of-voice, per-model breakdown,
       open content gaps. Pair with get_visibility_trend for deltas vs. the prior
       computed_at.
   5. (optional) generate_benchmark_ideas({ company_id, metrics: [<weak metric>], style: "neutral" })
        For any metric that came back weak, ask Gemini for 5–7 specific, brand-grounded ideas to lift it.
        Pass style="neutral" to strip TGF/Market Engineering framing when re-branding for a partner UI.

Cadence & credits: the app UI throttles this loop to once every 15 minutes per
company to prevent accidental credit burn. Integrator tokens are NOT rate-limited
server-side today, but the same 15-minute cadence per company is the recommended
ceiling. Repeated back-to-back calls waste LLM credits — the scores rarely change
meaningfully inside a 15-minute window. Future releases may meter this per token.

COMPETITOR CURATION FLOW
analyze_ai_visibility seeds an initial auto-discovered competitor set. If the
user asks to review, add, or remove competitors:
  1. list_competitors → show the current set, calling out source ("auto" vs "manual").
  2. If they want to add: add_competitors({competitors:[...]}) — never invent names,
     use exactly what the user provides.
  3. If they want to drop: remove_competitors({names:[...]}) or by ids from step 1.
  4. If they want to re-seed after a brand pivot: discover_competitors({persist:true,
     replace:true}) — this preserves every manual entry and only sweeps auto ones.
  Never call add_competitors or remove_competitors on your own initiative; always
  confirm the exact list with the user first.


DISCOVERABILITY LAYERS the report scores (per page unless noted):
  Layer 1 — Classical SEO (title/description/canonical/OG/Twitter)
  Layer 2 — Schema.org Structured Data (JSON-LD)
  Layer 3 — AI-Crawler Access (site-wide, from /robots.txt)
  Layer 4 — Answer-Readiness (direct-answer opener, FAQ, byline/date, headings, TOC, citations)
  Layer 5 — llms.txt (site-wide)
  Layer 6 — sitemap.xml (site-wide, dated, normalized URL list)
  Annex A (optional, OFF by default) — Experimental AI Annotations (ai:* meta-tags).
           Not a published standard, not consumed by mainstream LLMs at query time. Gated
           per-tenant by companies.emit_ai_tags and per-job by the config override.

When narrating a report: lead with Layers 1-4. Treat Annex A as an optional footnote — never
describe it as a Google ranking signal or as required by any major LLM.

REQUIRED CONTEXT — ASK THE USER FIRST
Before calling any tool, confirm you have:
1. The target site URL (root, https://…). Needed for discover_site / analyze_site.
2. The brand label for reporting (brand_name). Falls back to hostname if omitted, but
   pass it explicitly for cleaner list_reports filtering.
3. For agency tokens only: which client company (brand OR host) the request applies to.
   Never assume — ask.
4. Analysis depth: number of pages to analyze per run. Per-run caps by tier:
   Starter 500, Pro 1,500, Agency 2,500, Enterprise/Admin 10,000. Quid's Beta
   token is provisioned at the 10,000 ceiling. If the user says "audit the site"
   without a number, propose 25 and confirm before enqueuing.
5. For AI-visibility (analyze_ai_visibility): if the user names a specific product line,
   subdomain, or section of a big site (e.g. "Walmart Pharmacy", "AWS Lambda"), pass a
   URL that pins to that section (walmart.com/pharmacy, aws.amazon.com/lambda) — NOT
   the bare root. The tool auto-detects and scopes to that path/subdomain. If the user
   only gives a bare root of a large well-known site, confirm before running whether
   they want the whole site or a specific section.

RECOMMENDED FLOW
Step 1: discover_site({ url }) returns EITHER
          • sync  : { discovery_id, urls[], total }  (small sites / starter/pro/agency)
          • async : { discovery_id, discovery_job_id, status: "queued" }
                    (enterprise/admin, body { async: true }, or large tier ceilings)
        For the async shape, POLL discover-status until status="done" BEFORE calling
        analyze_site. analyze_site accepts either id — the sync discovery_id or the
        async id (returned both as discovery_id and discovery_job_id).
Step 2: Poll discover-status({ discovery_job_id }) every ~2s if async. Do NOT call
        analyze_site while partial:true / status in {queued,running} — you will get
        HTTP 409 { code: "discovery_not_ready" } telling you to keep polling.
Step 3: Show the user how many URLs were found; ask which subset to analyze
        (all / top N / specific indexes). Do NOT auto-analyze large sites without confirmation.
Step 4: analyze_site({ discovery_id, select, brand_name }) → returns { job_id }.
Step 5: Poll get_job_status(job_id) every ~30 s until status="done".
Step 6: get_report(report_id) and, if the user asked, get_llms_txt(report_id).

ANALYZE_SITE ERROR CODES (updated)
  • 409 discovery_not_ready — async discovery still enumerating. Response body includes
    discovery_job_id + poll_endpoint. Retry analyze_site after status="done".
  • 422 discovery_failed    — the discovery job failed; response includes error text.
  • 404 not_found           — id doesn't match any discovery visible to this token.

DISCOVERY FALLBACKS (thin-sitemap sites — deciem.com, Shopify brand hubs, WAF-protected)
discover_site cascades three tiers of coverage automatically. Fast path is unchanged for
sites with clean sitemaps; the fallbacks only trigger when the primary sources return
≤ 1 URLs:
  Tier 1 (always): robots.txt + sitemap-index walk, /llms.txt, our site-map index.
  Tier 2 (auto):   homepage link-harvest — fetches the resolved origin (direct fetch →
                   premium unblocker for WAF-protected hosts), extracts same-origin <a href>, and
                   follows up to 5 hub paths (/collections, /products, /blog, /pages, /shop)
                   one hop deep. Cheap and synchronous.
  Tier 3 (auto):   full link crawl at maxDepth=2, tier-capped page limit. Async; polled
                   inline up to ~60 s in the sync path, up to ~180 s in the background worker
                   (starter+ tiers only — skipped for preview/onetime to protect credits).

The discover_site / discovery-status response includes:
  • sourceCounts.{sitemap,llms,map,homepage,crawl}: URL counts per source ("map" = the
    site-map index source; the older alias for that key is still emitted for backwards
    compatibility, so read "map" going forward).
  • fallbackUsed: 'homepage' | 'crawl' | null — which cascade layer actually fired.

CRAWL COST + STEALTH TIER (no API contract change)
All premium-unblocker fetches (discovery rescue, page rescue crawl, SERP capture) run in
cost-aware auto mode: the cheapest proxy/render configuration that succeeds is the one we
are billed for, failed attempts cost nothing, and hosts behind Akamai / PerimeterX /
DataDome can now escalate to a stealth proxy tier. Effects for integrators:
  • Request and response shapes for discover_site, analyze_site, /v1/discovery, /v1/jobs
    and /v1/reports are unchanged — no integration work is required.
  • Success rate on hostile hosts improves; fewer crawl_blocked failures.
  • Crawl cost per page is measured rather than estimated, which is what the credit-based
    OEM cost model bills against.

CRAWL MARKET / GEOLOCATION (new — optional "country" parameter)
Every crawl now runs against a named market so a UK, German or Japanese buyer sees what the
local visitor sees. Pass "country" (ISO 3166-1 alpha-2, lowercase) to discover_site /
POST /v1/discovery and analyze_site / POST /v1/reports:
  • Resolution order: explicit "country" → the company's saved market → ccTLD inference
    (example.co.uk → gb, example.de → de) → "us".
  • Effects: pages are fetched from an exit point inside that country, Accept-Language is
    set to the market's primary language, discovery uses a matching location, and Google
    SERP / AI Overview
    captures use that market's hl + gl parameters.
  • 41 supported markets: ar, au, at, be, br, ca, cl, cn, co, hr, dk, ee, fi, fr, de, gr,
    hu, in, id, ie, il, it, jp, kr, lv, lt, mx, nl, nz, no, pl, pt, ro, sa, sg, si, es,
    se, ch, th, gb, us.
  • An explicit code outside that list is an error, never a silent US crawl:
    HTTP 400 { code: "unsupported_country" } with the supported list in the message.
  • Responses echo "country" and "country_source" ("explicit" | "site_default" |
    "inferred" | "default"); finished reports carry "crawl_country".
  • Backwards compatible: omit "country" and behaviour is exactly as before.
  • Cost note: non-US markets require premium proxies, so Auto-Mode's credit floor rises to
    25 credits for geolocated calls. Only pass "country" when the market matters.

PREMIUM ENGINE — "gemini_app" (Gemini live product) — OPT-IN PER PARTNER
A new answer engine captures what the real consumer Gemini product answers, rather than what
the Gemini model API says it would answer. It returns Gemini's own grounding links, so
citations are link-level evidence instead of model-reported sources.
  • Engine key: gemini_app   Display name: "Gemini (live product)"   Route: vendor_scrape
  • Discover it with list_engines / GET /v1/engines. Each entry now carries:
      premium: true|false          — true for vendor-scraped live surfaces
      included_in_plan: true|false — already accounts for your partner opt-in
      available: true|false        — plan + opt-in + admin kill switch
  • Request it like any other engine: engines: ["openai","gemini","gemini_app"] on
    scan_product_visibility / POST /v1/commerce/scan, or leave engines unset to use every
    engine your plan and opt-in allow.
  • Sampling: it runs on a fraction of each prompt sweep (default 25%), so expect fewer
    data points for gemini_app than for openai/gemini over the same window. This is not an
    error condition — do not retry to "fill in" missing runs.
  • Honours "country": the capture is made from the requested market, so a gb run reflects
    what a UK buyer sees in the Gemini app.
  • OPT-IN: premium engines are OFF for every partner until TGP enables them on your
    account. Until then gemini_app is simply absent from your resolved engine set — requests
    naming it succeed and run on your remaining engines rather than failing. Check
    included_in_plan on GET /v1/engines to know your current state.
  • Metering + price: premium runs meter as "prompt_runs_premium", not "prompt_runs", and are
    billed at 4.0 credits per run ($0.20 at $0.05/credit) versus 0.5 credits ($0.025) for a
    standard prompt run. The credit unit itself does not change. An optional monthly premium
    prompt cap can be set on your account; cap events appear in the usage feed like any other.
  • Kill switch: TGP can disable the engine platform-wide if the upstream vendor degrades.
    Behaviour when that happens is identical to the not-opted-in case — the engine drops out
    of the resolved set, runs continue on the remaining engines.

analyze_site (Mode C legacy shorthand) additionally returns:
  • fallback_used: same value as above.
  • discovery_thin: true when even the crawl fallback yielded ≤ 1 URLs while the user
    asked for max_pages > 1. discovery_thin_reason explains why. The job still enqueues
    (single-page analysis) so callers can log/alert rather than swallow the run.

COLD-START AI-VISIBILITY FLOW (for a brand-new URL, no prior setup)
Use this when the user asks "what prompts is my brand being asked about and how does it
rank?" and the app has no company/prompts/competitors configured yet.

  Step 1: analyze_ai_visibility({ url }) → returns brand, competitors, per-prompt rank,
          share-of-voice, and (by default) persists a company + prompts + competitors so
          subsequent tools can build on it. company_id is in the response's monitoring block.
  Step 2: If the user wants trends: enable_visibility_monitoring({ company_id }).
  Step 3: After 2+ scheduled runs: get_visibility_trend({ company_id, window_days: 30 }).
  Step 4 (optional, any time): list_prompts({ company_id }) → render the prompt matrix
          (each prompt with its latest brand_mentioned / citation_count / competitors).
          For per-prompt change-over-time, get_prompt_history({ prompt_id, window_days: 30 }).

CRAWL SCOPING — CRITICAL FOR BIG SITES
analyze_ai_visibility never crawls off-scope by default. Scope is inferred from the URL:
  • walmart.com                → auto = "subset" (representative sample of the whole site)
  • pharmacy.walmart.com       → auto = "path_only" (pinned to that subdomain)
  • walmart.com/pharmacy       → auto = "path_only" (pinned to /pharmacy/*)
Override with crawl_scope: "single_page" | "path_only" | "subset" | "full_site" and
max_pages (default 25, hard cap 200). Use include_paths / exclude_paths (globs like
["/pharmacy/*"]) for finer control. For a Walmart-Pharmacy-scale request, ALWAYS pass a
URL that names the section — do NOT pass the bare root with crawl_scope="full_site".

READING get_visibility_scores CORRECTLY
The response ALWAYS includes a "diagnostics" object. Zero scores almost never mean
GOOGLE SEARCH PERFORMANCE (Search Console) — the classical-search half
get_gsc_performance is the counterpart to get_visibility_scores. One is measured Google
search behaviour; the other is AI answer visibility. Show both when a user asks "how is
our search performance?" — AI visibility alone is only half the story.

  Step 1: get_gsc_performance({ company_id, days: 90 }).
  Step 2: Branch on status BEFORE reading any number:
          • "ok"                  → totals, trend, daily, top_queries, top_pages are real.
          • "selection_required"  → several verified properties cover the site. Call
                                    list_gsc_properties, ask the user which to use, then
                                    select_gsc_property({ site_url }) and retry step 1.
          • "no_property"         → nobody has granted the connected Google account access to a
                                    covering property. Relay the "message" field verbatim. NEVER present
                                    this as "your site gets no search traffic".
  Step 3: Narrate it correctly:
          • totals.avg_position is IMPRESSION-WEIGHTED — do not recompute a plain mean.
          • trend.* compares the current half of the window to the prior half.
          • top_queries / top_pages are ordered by impressions on purpose: the best actions are
            usually high-impression, low-click queries (page-two near-misses).
          • window.end_date is always ~2 days ago because Search Console data lags. Say so if
            the user asks about yesterday.
  Available on every tier, needs only the read scope, and costs no credits — Search Console is
  a free first-party connection.

READING get_visibility_scores CORRECTLY
The response ALWAYS includes a "diagnostics" object. Zero scores almost never mean
"the brand is invisible" — they almost always mean the platform hasn't been set up
to measure that brand yet. Treat diagnostics as ground truth, scores as secondary.

MANDATORY RULE — no exceptions:
  IF diagnostics.data_ready === false:
    • Do NOT report brand_mention_pct, domain_citation_pct, share_of_ai_voice,
      or prompt_win_rate as facts.
    • Do NOT say "your visibility is 0%", "the brand isn't cited", or anything
      that treats the zero values as a measurement.
    • DO relay diagnostics.issues[] and diagnostics.next_steps[] verbatim.
    • DO offer to run analyze_ai_visibility({ url }) — one call seeds prompts +
      competitors + a first score, converting data_ready from false to true.

  IF diagnostics.data_ready === true:
    • Report the numbers, but still mention diagnostics.computed_age_days if > 3
      (the snapshot is stale) and suggest a fresh recompute.

Common triggers you will see in diagnostics.issues[] and how to explain them:
      • counts.enabled_prompts == 0        → "Add tracked phrases at /app/coverage#phrases."
      • counts.competitors == 0            → "Add 3–8 competitors at /app/manage → Competitors."
      • schedule == null or !schedule.enabled → "Enable a visibility schedule at /app/visibility."
      • counts.brand_citations_last_30d == 0 with citations > 0
          → "Review brand aliases (e.g. Quid, Quid Inc, quid.com) at /app/manage → Company profile."
      • computed_age_days > 3              → "Trigger a fresh visibility recompute."
Prefer analyze_ai_visibility({ url }) over walking the user through manual setup —
it seeds prompts + competitors + a first visibility score in one call, so
get_visibility_scores immediately returns data_ready: true on the next read.

ERROR HANDLING
- 401 → the bearer token is missing/invalid. Ask the user to re-issue the MCP token.
- 403 → token lacks a scope (e.g. analyze). Tell the user which scope is missing.
- 404 not_found on brand/host → the token can't see that client. Ask for a different brand.
- 429 rate_limited → back off; retry after the Retry-After hint.
- 400 invalid_argument with "must be a UUID" → you passed a placeholder like "null"
  or "None". Stop and ask the user for the actual ID.
- 400 invalid_argument with "include_paths ... do not overlap" → your include_paths
  glob targets a different section than the URL. Drop include_paths or widen the URL.

DO NOT
- Do not fabricate report_id, job_id, or discovery_id values.
- Do not call analyze_site without an explicit URL or discovery_id from the user.
- Do not report brand_mention_pct / domain_citation_pct / share_of_ai_voice / prompt_win_rate
  when diagnostics.data_ready is false. Report the diagnostics.next_steps[] instead.
- Do not present zero visibility scores as evidence the brand isn't cited by AI.
  Zero + data_ready:false means "not set up yet," not "invisible."
- Do not paste the bearer token into any tool argument or user-visible message.
- Do not pass a bare root URL to analyze_ai_visibility when the user asked about a
  specific product line or subdomain — always pass the sectioned URL so scope pins there.
- Do not set crawl_scope="full_site" on a large well-known site without user confirmation.

To run an AgenticSEO analysis I need a few things:

1. What is the site URL you want analyzed? (e.g. https://www.example.com)
2. What brand name should I label this report with?
3. How many pages should I analyze? (default 25; max 500 on Starter, 1,500 Pro,
   2,500 Agency, 10,000 Enterprise/Admin — Quid's Beta token is provisioned at 10,000)
4. If you have an agency token: which client company does this apply to?
   (brand name or hostname)

For AI visibility scores, if you're checking a specific client, tell me the brand
or hostname; otherwise I'll fetch scores for your own company.

{
  "diagnostics": {
    "data_ready": false,
    "issues": [
      "No competitors configured. Without competitors, share-of-voice stays at 0.",
      "No visibility schedule configured — prompts will only run on manual triggers.",
      "Latest rollup is 8 day(s) old."
    ],
    "next_steps": [
      "Add 3–8 competitors (brand + domain) at /app/manage → Competitors.",
      "Enable a monthly run schedule at /app/visibility → Schedule.",
      "Trigger a fresh visibility recompute so newer prompt_runs get rolled up."
    ],
    "counts": {
      "enabled_prompts": 15,
      "competitors": 0,
      "runs_last_30d": 3,
      "citations_last_30d": 21,
      "brand_citations_last_30d": 0
    },
    "schedule": null,
    "computed_at": "2026-06-29T14:17:29.274493+00:00",
    "computed_age_days": 8
  }
}

{
  "mcpServers": {
    "agenticseo": {
      "transport": "http",
      "url": "https://<project>.supabase.co/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer mcp_<your-token>"
      }
    }
  }
}

analyze_ai_visibility({
  url: "quid.com"
})
// auto crawl_scope = "subset" — samples across quid.com

analyze_ai_visibility({
  url: "pharmacy.walmart.com"
})
// auto crawl_scope = "path_only" — pinned to pharmacy.walmart.com

analyze_ai_visibility({
  url: "https://walmart.com/pharmacy",
  brand_name: "Walmart Pharmacy",
  prompt_count: 15
})
// auto crawl_scope = "path_only" — NEVER crawls walmart.com/grocery

analyze_ai_visibility({
  url: "https://walmart.com/pharmacy",
  crawl_scope: "path_only",
  include_paths: ["/pharmacy/*"],
  exclude_paths: ["/pharmacy/legal/*"],
  max_pages: 50
})

analyze_ai_visibility({
  url: "smallsite.com",
  crawl_scope: "full_site",
  max_pages: 100
})

analyze_ai_visibility({
  url: "prospect.com",
  persist: false
})
// returns snapshot only; nothing persisted

enable_visibility_monitoring({
  company_id: "<from analyze_ai_visibility>",
  cadence: "monthly"
})

get_visibility_trend({
  company_id: "<same>",
  window_days: 30
})
// returns snapshots[], delta, competitor_leaderboard,
// new_competitors[], lost_competitors[]

list_prompts({
  company_id: "<from analyze_ai_visibility>",
  enabled_only: true,
  limit: 50
})
// returns { items: [{ id, text, persona, last_run: { brand_mentioned, citation_count, ... } }] }

get_prompt_history({
  prompt_id: "<from list_prompts>",
  window_days: 30
})
// returns { runs: [{ ran_at, brand_mentioned, citation_count, competitors_mentioned }] }

{
  "ok": false,
  "code": "unsupported_target",
  "category": "auth_walled",
  "severity": "block",
  "host": "linkedin.com",
  "reason": "LinkedIn requires a signed-in session to render profile or post content...",
  "allow_shallow": true,
  "shallow_path_hint": "/company/<slug> pages render some public content; /in/ profiles do not.",
  "input_url": "https://www.linkedin.com/company/quid"
}