Skip to content

start_scan

Start a free scan.

Start a free ScanFree scan of one website. Local types (local_service, local_storefront, local_professional) need `city`. Pass 1 to 10 `questions` a customer would ask an AI (no business name); if you omit them you get 12 suggestions and must call again. Needs a verified account; uses one of the monthly free scans (shared with the website).

Who can use it

Access
Any verified account. Uses one of the free scans of the month, shared with the website.
Scope
scan:write
Changes anything
Yes.

Inputs

NameTypeRequiredValues and limits
urlstringYesThe business website, for example example.com
site_typestringYeslocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
citystringNoCity and state for local types, e.g. Boise, Idaho
questionsarray of stringNo1 to 10 items

What it answers

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

FieldMeaning
statusrunning when the scan started; queued when free scans are busy (it runs by itself); needs_questions when you passed no questions.
scan_idThe scan, for get_scan and explain_result.
estimated_secondsAbout how long it takes.
report_urlThe report page (the person signs in to see it).
suggestionsWith needs_questions: twelve questions to choose from. Call again with up to ten of them in questions.
position, eta_secondsWith queued: the place in the queue and an estimate.
messageWhat to do next, in one sentence.

Errors

statusWhat it means
invalid_inputThe address is refused (not a public website, or a kind of site we don't check), site_type isn't one of the list, too many questions, or city is missing for a local type.
invalid_questionsSome questions won't make AI list businesses, or aren't allowed (for example they name the business). problems says which, by number.
verify_emailThe account hasn't confirmed its email. link goes to sign-in.
limit_reachedNo free scans left this month. account (action get) says when they reset.
already_runningA scan of this site is running already; scan_id is that scan.
daily_limitToday's free scans are used up for everyone. Try tomorrow.
limitedToo many scans from this network, or too many suggestion runs today.
needs_reviewThis scan waits for a person at ScanFree to look at it first.
pausedFree scans are paused for now.
forbiddenThe account is blocked, or the credential lacks scan:write.
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": "start_scan",
    "arguments": {
      "url": "example.com",
      "site_type": "local_service",
      "city": "Boise, Idaho",
      "questions": [
        "Who is a good plumber in Boise?",
        "Best emergency plumber near Boise"
      ]
    }
  }
}
The answer (structured content)
{
  "status": "running",
  "scan_id": "00000000-0000-4000-8000-000000000001",
  "estimated_seconds": 30,
  "report_url": "https://app.scanfree.dev/scan/00000000-0000-4000-8000-000000000001",
  "message": "Call get_scan with this scan_id (wait_seconds up to 25) until status is complete."
}