Skip to content

site_insights

Competitors, directories, reviews, site checks.

For one of your sites (site_id). view competitors: who AI named instead in your free scans, with answer counts, and your tracked competitors. directory: the places worth being listed for your kind of business, each linked from your site, mentioned in answers, or no link found (never "not listed"). reviews: Google review counts and ratings for you and the businesses AI named, from a paid check of a local business (never review text). checks: the site's checks from its newest paid check (Can AI reach you, the facts AI can read such as prices shown on your site), each with what we found, why it matters and its evidence tag. Read-only.

Who can use it

Access
Any of your sites. reviews needs a paid check of a local business.
Scope
scan:read
Changes anything
No. Read-only.

Inputs

NameTypeRequiredValues and limits
site_idstringYesA site id from sites or get_dashboard
viewstringYescompetitors, directory, reviews, checks

What it answers

Every answer has status and, where useful, message in plain words.

FieldMeaning
competitors viewfrom_free_scans (scans, answers and named_instead with answer counts) and tracked (your tracked competitors).
directory viewcounts (places, linked_from_your_site, mentioned_in_answers) and places, each linked, mentioned or no_link. We can't see listings, so never "not listed".
reviews viewrows: name, you, named_in_answers (out of answers_in_check), google_reviews, google_rating. Counts and dates only, never review text.
checks viewFrom the newest paid check's crawl: checked_on, summary and lines, each with key, group, label, status (pass, partial, fail, check or info), evidence (what we found), why, evidence_tag (Official, Seen in our data, Likely, Info only) and, on a partial or fail, fix, effort and impact. prices_shown is the line for prices shown on the site, for every kind of site, tagged Likely. Empty lines with a message before any paid check.

Errors

statusWhat it means
invalid_inputsite_id isn't a site id. Take one from sites (action list) or get_dashboard.
not_foundNo site with that id on this account.
invalid_inputview must be competitors, directory, reviews or checks.
forbiddenThe credential lacks the tool's scope, or an agent's owner has no ScanFree account yet (the owner signs in on the website once).
Input validation errorAn argument doesn't match the schema below. The call fails with MCP error -32602, naming the field.

Errors before the tool runs (a missing key, too many requests) are on the MCP page.

Example

Example shape; values are illustrative.

The call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "site_insights",
    "arguments": {
      "site_id": "00000000-0000-4000-8000-000000000004",
      "view": "competitors"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "site_id": "00000000-0000-4000-8000-000000000004",
  "view": "competitors",
  "from_free_scans": {
    "scans": 2,
    "answers": 24,
    "named_instead": [
      {
        "name": "Another Plumber Co",
        "answers": 9
      }
    ]
  },
  "tracked": [],
  "orders": [],
  "note": "…"
}