Skip to content

explain_result

Explain a result in plain words.

The story of a finished scan (scan_id) or of a paid order's check (check_id): how often AI named the business, then the one thing to do with why, where and its evidence tag, and for a paid check the rest of the list. read_out is written for you to read to the person as it is. Read-only.

Who can use it

Access
Free for a finished scan; a paid order for a check.
Scope
scan:read
Changes anything
No. Read-only.

Inputs

NameTypeRequiredValues and limits
scan_idstringNoA finished scan of this account
check_idstringNoA finished check of a paid order (from get_matrix or check_status)

What it answers

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

FieldMeaning
kindfree_scan or paid_check.
headlineOne sentence with the counts, for example how many answers named the business.
one_thingThe one thing to do: action, why, where, evidence (its label), effort and, when there is one, evidence_note (the limit of that evidence).
what_to_doPaid checks: the full list, each item shaped like one_thing.
named, answers, named_most_insteadFree scans: the counts, and who was named most instead.
read_outPlain text written to be read to the person as it is: the one thing first.
report_url, results_urlThe page with everything.

Errors

statusWhat it means
invalid_inputNeither scan_id nor check_id was given.
not_foundNo such scan or check on this account.
not_readyIt hasn't finished. Poll get_scan or check_status first.
not_availableThat check isn't a scheduled one; read it with get_matrix.
failedThe scan has no answers to explain.
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": "explain_result",
    "arguments": {
      "scan_id": "00000000-0000-4000-8000-000000000001"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "kind": "free_scan",
  "scan_id": "00000000-0000-4000-8000-000000000001",
  "headline": "AI named Example Plumbing in 2 of 12 answers.",
  "named": 2,
  "answers": 12,
  "named_most_instead": {
    "name": "Another Plumber Co",
    "answers": 5
  },
  "one_thing": {
    "action": "Add your service area and prices to your home page",
    "why": "…",
    "where": "Your home page",
    "evidence": "Seen in our data",
    "effort": "An hour"
  },
  "read_out": "AI named Example Plumbing in 2 of 12 answers.\n…",
  "report_url": "https://app.scanfree.dev/scan/00000000-0000-4000-8000-000000000001"
}