Analyze branded vs non-branded search
Splits the window's Google + Bing queries into branded and non-branded demand and reports each side's clicks, impressions, CTR, average position and share of the engine's total.
Tool name: analyze_branded_vs_nonbranded
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.
Splits the window's Google + Bing queries into branded and non-branded demand and reports each side's clicks, impressions, CTR, average position and share of the engine's total. A query is branded when it contains the workspace title or one of its confirmed brand aliases, matched whole and case-insensitively - the same term set the AI-answer mention monitor uses. The terms applied come back in brandTerms and the biggest branded queries in sampleBrandedQueries, so you can check the classification; correct it with set_workspace_brand_terms and re-run. total sums clicks and impressions and counts each query once across engines, but total.avgPosition is always null - the engines define position differently and report it on different cadences, so read the per-engine figures instead.
The shares here are shares of the rows each engine returned, not of the property, and Google's row ceiling makes that directional rather than merely approximate: brand queries are high-volume and sit inside Google's top ~5,000, while the non-branded long tail is exactly what the ceiling cuts, so on a truncated window the branded share is overstated. The response says whether that applies to this window in unsupportedInputs. Google stores only about 5,000 rows per day per single-dimension breakdown once a day is more than roughly three days old, so on a large site these rows are a top-N by impressions rather than a complete list. When that applies to the window you asked for, the response says so in unsupportedInputs with the dates - there is nothing to fetch, so read a missing row as 'not in the top ~5,000', never as 'zero'.
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. |
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"
},
"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
},
"brandTerms": {
"type": "array",
"items": {
"type": "string"
}
},
"google": {
"type": "object",
"properties": {
"attached": {
"type": "boolean"
},
"branded": {
"type": "object",
"properties": {
"queryCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avgPosition": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicksShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"impressionsShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"queryCount",
"clicks",
"impressions",
"ctr",
"avgPosition",
"positionCoverageImpressions",
"clicksShare",
"impressionsShare"
],
"additionalProperties": {}
},
"nonBranded": {
"type": "object",
"properties": {
"queryCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avgPosition": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicksShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"impressionsShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"queryCount",
"clicks",
"impressions",
"ctr",
"avgPosition",
"positionCoverageImpressions",
"clicksShare",
"impressionsShare"
],
"additionalProperties": {}
}
},
"required": ["attached", "branded", "nonBranded"],
"additionalProperties": {}
},
"bing": {
"type": "object",
"properties": {
"attached": {
"type": "boolean"
},
"branded": {
"type": "object",
"properties": {
"queryCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avgPosition": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicksShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"impressionsShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"queryCount",
"clicks",
"impressions",
"ctr",
"avgPosition",
"positionCoverageImpressions",
"clicksShare",
"impressionsShare"
],
"additionalProperties": {}
},
"nonBranded": {
"type": "object",
"properties": {
"queryCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avgPosition": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicksShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"impressionsShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"queryCount",
"clicks",
"impressions",
"ctr",
"avgPosition",
"positionCoverageImpressions",
"clicksShare",
"impressionsShare"
],
"additionalProperties": {}
}
},
"required": ["attached", "branded", "nonBranded"],
"additionalProperties": {}
},
"total": {
"type": "object",
"properties": {
"attached": {
"type": "boolean"
},
"branded": {
"type": "object",
"properties": {
"queryCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avgPosition": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicksShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"impressionsShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"queryCount",
"clicks",
"impressions",
"ctr",
"avgPosition",
"positionCoverageImpressions",
"clicksShare",
"impressionsShare"
],
"additionalProperties": {}
},
"nonBranded": {
"type": "object",
"properties": {
"queryCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avgPosition": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicksShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"impressionsShare": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"queryCount",
"clicks",
"impressions",
"ctr",
"avgPosition",
"positionCoverageImpressions",
"clicksShare",
"impressionsShare"
],
"additionalProperties": {}
}
},
"required": ["attached", "branded", "nonBranded"],
"additionalProperties": {}
},
"sampleBrandedQueries": {
"type": "array",
"items": {
"type": "string"
}
},
"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",
"brandTerms",
"google",
"bing",
"total",
"sampleBrandedQueries",
"unsupportedInputs"
],
"additionalProperties": false
}Analyze site sections
Aggregates Google + Bing page performance into URL directories (the leading `sectionDepth` path segments) and compares each section's current total against the immediately preceding period.
Get workspace brand terms
The brand terms a workspace matches queries and AI answers against: `brandTerms` is the effective list (title plus confirmed aliases) and is what analyze_branded_vs_nonbranded and find_low_hanging_keywords actually use.