Skip to content

phrases

Phrases of an order.

The phrases a paid order tracks. Reads (scan:read): list, every phrase with its id, state and age; history (phrase_id), that phrase per check and AI; keywords, the keyword package's Google data while that add-on is on sale. Writes (scan:write): add (text) uses a free slot; replace (phrase_id, text) retires one and adds another; retire⚠ (phrase_id) frees a slot, history kept; set_keywords (keywords; with phrase_id, up to 3 related Google keywords for that phrase, without it, the keyword package's own list). ⚠ answers needs_confirmation with a summary and a confirm_token. Show the summary to the person first, and only if they agree call again with the same arguments plus confirm_token (works once, for 10 minutes).

Who can use it

Access
A paid order. keywords needs the keyword package.
Scope
scan:read for reading; each write action's scope is below.
Changes anything
Its write actions do; see below.

Actions

Pass one in action. Without it: list.

actionScopeWhat it does
listscan:readEvery phrase with its id, state and age.
historyscan:readOne phrase (phrase_id) per scheduled check and AI: named in how many runs.
keywordsscan:readThe keyword package's Google search data, while that add-on is on sale.
addscan:writeA write action: the description above says what it changes.
replacescan:writeA write action: the description above says what it changes.
retirescan:writeA write action: the description above says what it changes.
set_keywordsscan:writeA write action: the description above says what it changes.

Inputs

NameTypeRequiredValues and limits
actionstringNolist, history, keywords, add, replace, retire, set_keywords. Default list
order_idstringYesAn order id from get_dashboard
phrase_idstringNoFor history, replace, retire, set_keywords: a phrase id from action list
textstringNo0 to 300 characters. For add and replace: the new phrase
keywordsarray of stringNoat most 1000 items. For set_keywords
limitintegerNo1 to 1000. For keywords: cap on each list (default 100)
confirm_tokenstringNoOnly for a ⚠ action, on the second call: the confirm_token from the first answer, after the person agreed

What it answers

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

FieldMeaning
phraseslist: phrase_id, text, kind, state, added_on, retired_on, age_days. phrases_bought and in_use count them.
phrase, ais, checkshistory: the phrase, the AIs, and per check the cells per AI (named_runs of answered_runs, best_position). Counts, never a trend line.
keywords, relatedkeywords: Google figures (monthly searches in the US, cost per click, competition, difficulty 0 to 100, your Google position), dated. Google search, never added to an AI figure.

Errors

statusWhat it means
invalid_inputorder_id isn't an order id. Take one from get_dashboard.
not_foundNo order with that id on this account.
invalid_inputhistory without phrase_id, or an action that isn't in the list.
not_foundNo such phrase on that order.
not_availablekeywords while the keyword package isn't on sale.
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": "phrases",
    "arguments": {
      "action": "list",
      "order_id": "00000000-0000-4000-8000-000000000002"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "order_id": "00000000-0000-4000-8000-000000000002",
  "phrases_bought": 10,
  "in_use": 10,
  "phrases": [
    {
      "phrase_id": "00000000-0000-4000-8000-000000000005",
      "text": "emergency plumber boise",
      "kind": "generic",
      "state": "active",
      "added_on": "2026-10-18",
      "retired_on": null,
      "age_days": 34
    }
  ]
}