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:readfor reading; each write action's scope is below.- Changes anything
- Its write actions do; see below.
Actions
Pass one in action. Without it: list.
| action | Scope | What it does |
|---|---|---|
list | scan:read | Every phrase with its id, state and age. |
history | scan:read | One phrase (phrase_id) per scheduled check and AI: named in how many runs. |
keywords | scan:read | The keyword package's Google search data, while that add-on is on sale. |
add | scan:write | A write action: the description above says what it changes. |
replace | scan:write | A write action: the description above says what it changes. |
retire | scan:write | A write action: the description above says what it changes. |
set_keywords | scan:write | A write action: the description above says what it changes. |
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
action | string | No | list, history, keywords, add, replace, retire, set_keywords. Default list |
order_id | string | Yes | An order id from get_dashboard |
phrase_id | string | No | For history, replace, retire, set_keywords: a phrase id from action list |
text | string | No | 0 to 300 characters. For add and replace: the new phrase |
keywords | array of string | No | at most 1000 items. For set_keywords |
limit | integer | No | 1 to 1000. For keywords: cap on each list (default 100) |
confirm_token | string | No | Only 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.
| Field | Meaning |
|---|---|
phrases | list: phrase_id, text, kind, state, added_on, retired_on, age_days. phrases_bought and in_use count them. |
phrase, ais, checks | history: the phrase, the AIs, and per check the cells per AI (named_runs of answered_runs, best_position). Counts, never a trend line. |
keywords, related | keywords: 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
| status | What it means |
|---|---|
invalid_input | order_id isn't an order id. Take one from get_dashboard. |
not_found | No order with that id on this account. |
invalid_input | history without phrase_id, or an action that isn't in the list. |
not_found | No such phrase on that order. |
not_available | keywords while the keyword package isn't on sale. |
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": "phrases",
"arguments": {
"action": "list",
"order_id": "00000000-0000-4000-8000-000000000002"
}
}
}{
"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
}
]
}