Explain a query's SERP
Fetch this query's Google SERP **live** and diff it against the newest SERP stored for this workspace.
Tool name: explain_query_serp
Cost: Paid on every call - a live DataForSEO SERP fetch, billed per call rather than served from cache, and capped per workspace per day. The response reports what it cost.
Writes data - confirmation required
This tool creates or changes data. It is not annotated readOnlyHint, so
your MCP client prompts you before it runs, and the server asks for an
explicit confirmation describing exactly what will change. Declining cancels
the call cleanly.
Fetch this query's Google SERP live and diff it against the newest SERP stored for this workspace. This is the answer to the case that diagnose_traffic_losses reports as case C - impressions fell while the ranking held - because search console can see the rank but never what else is on the page: an AI overview that appeared above the results, new entrants that pushed the fold down, or a competitor whose rewritten title now answers the question outright.
This costs money on every call. It is a paid DataForSEO fetch, not a cached read, and it is capped per workspace per day. Run diagnose_traffic_losses first and use this on the queries it flags, rather than sweeping a keyword list.
baselineCapturedAt: null means nothing was stored to compare against, so every movement list is empty for want of a baseline - do not report that as 'nothing changed'. A baseline exists from the next weekly capture onward. isTracked: false means the query is outside the workspace's weekly capture set (its top ~100 queries by impressions), so this call is the only observation of it so far. Movement is reported over the top 10 only, which is the depth captured.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
site | string | Yes | Domain or URL, e.g. example.com. |
query | string | Yes | The search query to fetch a SERP for. |
Full input JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"site": {
"type": "string",
"minLength": 1,
"description": "Domain or URL, e.g. `example.com`."
},
"query": {
"type": "string",
"minLength": 1,
"description": "The search query to fetch a SERP for."
}
},
"required": ["site", "query"]
}Response
Full output JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"site": {
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"query": {
"type": "string"
},
"capturedAt": {
"type": "string"
},
"baselineCapturedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"baselineSource": {
"type": "string",
"enum": ["weekly_capture", "explain", "campaign", "none"]
},
"isTracked": {
"type": "boolean"
},
"aiOverview": {
"type": "object",
"properties": {
"presentBefore": {
"type": "boolean"
},
"presentNow": {
"type": "boolean"
},
"citesUs": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": ["presentBefore", "presentNow", "citesUs"],
"additionalProperties": {}
},
"features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"presentBefore": {
"type": "boolean"
},
"presentNow": {
"type": "boolean"
}
},
"required": ["type", "presentBefore", "presentNow"],
"additionalProperties": {}
}
},
"ourPosition": {
"type": "object",
"properties": {
"positionBefore": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"positionNow": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"metaTitleBefore": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metaTitleNow": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"urlBefore": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"urlNow": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"positionBefore",
"positionNow",
"metaTitleBefore",
"metaTitleNow",
"urlBefore",
"urlNow"
],
"additionalProperties": {}
},
"enteredTop10": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"domain": {
"type": "string"
},
"position": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"metaTitle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": ["url", "domain", "position", "metaTitle"],
"additionalProperties": {}
}
},
"leftTop10": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"domain": {
"type": "string"
},
"position": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"metaTitle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": ["url", "domain", "position", "metaTitle"],
"additionalProperties": {}
}
},
"movedInTop10": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"domain": {
"type": "string"
},
"positionBefore": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"positionNow": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"metaTitleBefore": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metaTitleNow": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"url",
"domain",
"positionBefore",
"positionNow",
"metaTitleBefore",
"metaTitleNow"
],
"additionalProperties": {}
}
},
"resultTypeMix": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"countBefore": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"countNow": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["type", "countBefore", "countNow"],
"additionalProperties": {}
}
},
"costUsd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"unsupportedInputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"engine": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reason": {
"type": "string"
}
},
"required": ["field", "reason"],
"additionalProperties": {}
}
}
},
"required": [
"site",
"workspaceId",
"query",
"capturedAt",
"baselineCapturedAt",
"baselineSource",
"isTracked",
"aiOverview",
"features",
"ourPosition",
"enteredTop10",
"leftTop10",
"movedInTop10",
"resultTypeMix",
"costUsd",
"unsupportedInputs"
],
"additionalProperties": false
}