Query Deep Dive

Explain everything the connected tools know about one keyword and condense it into a query scorecard, the pages serving it, where it ranks by market and device, and recommendations. The user's request may contain a property, the query text, a date range, a market or device, and a focus hint such as "compare with Bing"; honor all of them.

Workflow

1. Resolve the property, the query and the window. If the user's request or the conversation names a property, use it. Site URLs use GSC formats: sc-domain:example.com or https://www.example.com/. Otherwise call list_sites and pick the obvious match. If several plausible properties exist, ask the user which one before continuing.

   • Take the query text exactly as given; the tools below match it exactly, and step 2 says what to do when no row matches.
   • Use the last 28 days compared with the previous period unless the user specifies dates. The daily tool takes no comparison parameter, so compare the first and second half of the window yourself and say the delta is derived.
   • GSC data lags about 2 to 3 days: never treat the most recent 2 days as complete, and if a dip appears at the very edge of the range, say it is likely reporting lag, not a real drop.

2. Daily series. Call get_query_performance with siteUrl, query and the optional startDate/endDate, leaving pageUrl out so the query is measured site-wide. daily holds one row per day, oldest first, with clicks, impressions, ctr and position.

   • ctr values are already percentages on a 0-100 scale. Never multiply them by 100. position: lower is better, and a change toward a lower number is an improvement; never color it as a decline.
   • Describe the shape: flat, a step change on a named date, a slide, a spike, or seasonality. Position worsening with impressions steady is a ranking loss; impressions falling with position steady is demand; clicks falling with both steady is the snippet or a SERP feature.
   • The query filter is an exact match. When daily is empty the response carries emptyBecause: call query_search_analytics with dimensions: ["query"] and filters: [{ "dimension": "query", "operator": "contains", "expression": "<core term>" }] to list the variants Google records (plural, word order, accents), pick the one with the most impressions or roll the close variants up, and say which you did.
   • Once step 3 names the top page, call get_query_performance again with pageUrl set to it; the gap between the page series and the site-wide series is the share other pages take.