Tool reference
Detect keyword cannibalization
Queries more than one of the site's own pages competes for, read from two sources.
Tool name: detect_keyword_cannibalization
Cost: Free - not billed, and does not draw on a plan quota.
Read-only
This tool only reads. It never creates or changes anything, so an assistant may call it without asking you first.
Queries more than one of the site's own pages competes for, read from two sources. The search data alone cannot answer this: both engines show one result per site, so the page that loses every time draws no impressions and is invisible in every feed - and that settled case is the damaging one. So each query gets a verdict on a four-rung ladder, and the rung says what you may do about it. confirmed: two or more pages really did draw impressions, listed with each one's share of them, so a consolidation has a survivor to keep - pattern says whether they surfaced together (co_occurring) or never on the same day (alternating, the engine still choosing). possible: one page ranks and a URL in the site's own sitemap matches the query on slug and title tokens - that page was never read, so open the URL in sitemapCandidates and decide; this is the ceiling of what the tool can claim about it. none: one page ranks and nothing else in the sitemap targets the query - the query is clear, and it is safe to optimize that page. unknown: no usable sitemap inventory, or one a walk truncated, so absence proves nothing. rows carries the confirmed and possible queries; verdicts counts every rung including the cleared ones, and inventory says how complete and how old the page list behind them is. Pass query to get one query's row on whatever rung it lands.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
site | string | Yes | The site to look up, as a bare domain ("example.com") or a URL - scheme, www., path and trailing slash are all stripped. Must resolve to a workspace the caller owns; call list_sites first if unsure of the exact domain. |
windowDays | integer | No | Length of the current window, in days. Defaults to 28. |
to | string | No | Last day of the current window (YYYY-MM-DD). Defaults to the most recent date either engine has data for. |
minImpressions | integer | No | Minimum window impressions for a page to count as competing for the query - keeps one stray impression from making a healthy query look contested. Defaults to 10. |
query | string | No | Ask about one query only, and return its row whatever verdict it gets - including none and unknown, which the unfiltered response only counts. |
limit | integer | No | Maximum rows to return, sorted by relevance. Defaults to 50. |
searchVertical | "web" | "image" | "video" | No | Which Google search vertical to read: web (default), image, or video. Google-only - Bing Webmaster Tools does not split verticals on any traffic endpoint, so anything other than 'web' returns Google alone, with Bing excluded and declared in unsupportedInputs. A null or absent Bing figure then means 'not measurable', never 'zero'. Defaults to "web". |
Full input JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"site": {
"type": "string",
"minLength": 1,
"description": "The site to look up, as a bare domain (\"example.com\") or a URL - scheme, www., path and trailing slash are all stripped. Must resolve to a workspace the caller owns; call list_sites first if unsure of the exact domain."
},
"windowDays": {
"default": 28,
"description": "Length of the current window, in days.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 365
},
"to": {
"description": "Last day of the current window (YYYY-MM-DD). Defaults to the most recent date either engine has data for.",
"type": "string"
},
"minImpressions": {
"default": 10,
"description": "Minimum window impressions for a page to count as competing for the query - keeps one stray impression from making a healthy query look contested.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"query": {
"description": "Ask about one query only, and return its row whatever verdict it gets - including `none` and `unknown`, which the unfiltered response only counts.",
"type": "string",
"minLength": 1
},
"limit": {
"default": 50,
"description": "Maximum rows to return, sorted by relevance.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 500
},
"searchVertical": {
"default": "web",
"description": "Which Google search vertical to read: web (default), image, or video. Google-only - Bing Webmaster Tools does not split verticals on any traffic endpoint, so anything other than 'web' returns Google alone, with Bing excluded and declared in `unsupportedInputs`. A null or absent Bing figure then means 'not measurable', never 'zero'.",
"type": "string",
"enum": ["web", "image", "video"]
}
},
"required": ["site"]
}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)$"
},
"searchVertical": {
"type": "string",
"enum": ["web", "image", "video"]
},
"currentWindow": {
"type": "object",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
},
"required": ["start", "end"],
"additionalProperties": false
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"query": {
"type": "string"
},
"verdict": {
"type": "string"
},
"evidence": {
"type": "string"
},
"pageCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalClicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"page": {
"type": "string"
},
"google": {
"anyOf": [
{
"type": "object",
"properties": {
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"measuredDays": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"clicks",
"impressions",
"position",
"measuredDays"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"bing": {
"anyOf": [
{
"type": "object",
"properties": {
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"measuredDays": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"clicks",
"impressions",
"position",
"measuredDays"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"totalClicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressionShare": {
"type": "number"
}
},
"required": [
"page",
"google",
"bing",
"totalClicks",
"totalImpressions",
"impressionShare"
],
"additionalProperties": {}
}
},
"google": {
"type": "object",
"properties": {
"attached": {
"type": "boolean"
},
"pageCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"multiPageDays": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["attached", "pageCount", "multiPageDays"],
"additionalProperties": {}
},
"bing": {
"type": "object",
"properties": {
"attached": {
"type": "boolean"
},
"pageCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"multiPageDays": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["attached", "pageCount", "multiPageDays"],
"additionalProperties": {}
},
"sitemapCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"page": {
"type": "string"
},
"url": {
"type": "string"
},
"lastmod": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"matchedTokens": {
"type": "array",
"items": {
"type": "string"
}
},
"coverage": {
"type": "number"
},
"titleMatched": {
"type": "boolean"
}
},
"required": [
"page",
"url",
"matchedTokens",
"coverage",
"titleMatched"
],
"additionalProperties": {}
}
}
},
"required": [
"query",
"verdict",
"evidence",
"pageCount",
"totalClicks",
"totalImpressions",
"pages",
"google",
"bing",
"sitemapCandidates"
],
"additionalProperties": {}
}
},
"inventory": {
"type": "object",
"properties": {
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"usable": {
"type": "boolean"
},
"fetchedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"pageCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"indexedPageCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"truncated": {
"type": "boolean"
},
"siteUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"usable",
"pageCount",
"indexedPageCount",
"truncated"
],
"additionalProperties": {}
},
"verdicts": {
"type": "object",
"properties": {
"confirmed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"possible": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"none": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"unknown": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"inventoryTested": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"queriesExamined": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"confirmed",
"possible",
"none",
"unknown",
"inventoryTested",
"queriesExamined"
],
"additionalProperties": {}
},
"unsupportedInputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"engine": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reason": {
"type": "string"
}
},
"required": ["field", "reason"],
"additionalProperties": {}
}
},
"lastSyncedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"site",
"workspaceId",
"searchVertical",
"currentWindow",
"rows",
"inventory",
"verdicts",
"unsupportedInputs"
],
"additionalProperties": false
}Get the pages that rank for one query
The pages of the site that surfaced for a specific query, per engine, over the window.
Find decaying pages or queries
Pages or queries in *sustained* decline across several whole periods - not a window-over-window drop, which cannot tell a decline from a bad month.