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
| Name | Type | Required | Values and limits |
|---|---|---|---|
scan_id | string | No | A finished scan of this account |
check_id | string | No | A 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.
| Field | Meaning |
|---|---|
kind | free_scan or paid_check. |
headline | One sentence with the counts, for example how many answers named the business. |
one_thing | The 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_do | Paid checks: the full list, each item shaped like one_thing. |
named, answers, named_most_instead | Free scans: the counts, and who was named most instead. |
read_out | Plain text written to be read to the person as it is: the one thing first. |
report_url, results_url | The page with everything. |
Errors
| status | What it means |
|---|---|
invalid_input | Neither scan_id nor check_id was given. |
not_found | No such scan or check on this account. |
not_ready | It hasn't finished. Poll get_scan or check_status first. |
not_available | That check isn't a scheduled one; read it with get_matrix. |
failed | The scan has no answers to explain. |
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": "explain_result",
"arguments": {
"scan_id": "00000000-0000-4000-8000-000000000001"
}
}
}{
"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"
}