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
| Name | Type | Required | Values and limits |
|---|---|---|---|
site_id | string | Yes | A site id from sites or get_dashboard |
view | string | Yes | competitors, directory, reviews, checks |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
competitors view | from_free_scans (scans, answers and named_instead with answer counts) and tracked (your tracked competitors). |
directory view | counts (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 view | rows: name, you, named_in_answers (out of answers_in_check), google_reviews, google_rating. Counts and dates only, never review text. |
checks view | From 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
| status | What it means |
|---|---|
invalid_input | site_id isn't a site id. Take one from sites (action list) or get_dashboard. |
not_found | No site with that id on this account. |
invalid_input | view must be competitors, directory, reviews or checks. |
forbidden | The 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 error | An 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.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "site_insights",
"arguments": {
"site_id": "00000000-0000-4000-8000-000000000004",
"view": "competitors"
}
}
}{
"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": "…"
}