/search-demand

name: search-demand
description: Find the questions buyers ask right before they buy — from Search Console, Bing, sales calls, and what ChatGPT, Claude, Gemini and Perplexity answer about your category — track where you're invisible, and brief the most useful page (or calculator) for each gap
version: "1.1.3"
author: Cogny AI
requires: cogny-mcp
platforms: [search-console, bing-webmaster, semrush, ahrefs, cogny-ai-visibility, brave-search, ahrefs-lite, hubspot, pipedrive, upsales]
user-invocable: true
argument-hint: "[scan|ai-check|page <campaign-ID or question>]"
allowed-tools:
  - mcp__cogny__list_integrations
  - mcp__cogny__refresh_mcp_discovery
  - mcp__cogny__read_context_node
  - mcp__cogny__write_context_node
  - mcp__cogny__create_ticket
  - mcp__cogny__create_finding
  - mcp__cogny__mcp__Google_Search_Console__tool_list_properties
  - mcp__cogny__mcp__Google_Search_Console__tool_get_search_analytics
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_sites
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_keyword_stats
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_traffic_stats
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_crawl_stats
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_query_stats
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_page_stats
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_query_page_stats
  - mcp__cogny__mcp__Bing_Webmaster_Tools__tool_get_related_keywords
  - mcp__cogny__mcp__Semrush__keyword_overview
  - mcp__cogny__mcp__Semrush__phrase_related
  - mcp__cogny__mcp__Semrush__phrase_organic
  - mcp__cogny__mcp__Semrush__domain_organic_keywords
  - mcp__cogny__mcp__Semrush__domain_organic_competitors
  - mcp__cogny__mcp__Ahrefs__organic_keywords
  - mcp__cogny__mcp__Ahrefs__keywords_explorer
  - mcp__cogny__mcp__Ahrefs__serp_overview
  - mcp__cogny__mcp__Ahrefs__top_pages
  - mcp__cogny__mcp__Ahrefs__organic_competitors
  - mcp__cogny__mcp__Ahrefs__domain_rating
  - mcp__cogny__mcp__cogny-ai-visibility__tool_check_ai_visibility
  - mcp__cogny__mcp__cogny-ai-visibility__tool_get_ai_visibility_history
  - mcp__cogny__mcp__cogny-brave-search__tool_brave_search
  - mcp__cogny__mcp__cogny-brave-search__tool_brave_rank_check
  - mcp__cogny__mcp__cogny-ahrefs-lite__tool_domain_rating
  - mcp__cogny__mcp__HubSpot__search_crm_objects
  - mcp__cogny__mcp__Pipedrive__list_activities
  - mcp__cogny__mcp__Upsales__list_appointments
  - WebFetch

Search Demand

This agent finds the questions people ask right before they buy and briefs the best page on the internet for each one. AI search rewards the most *useful* page over the most optimized one, so the output is often a **decision tool** (a calculator, checker or comparison) rather than another blog post.

It reads three sources: Search Console (what people already find you for), sales calls (what buyers ask humans), and **AI answer engines** (what models recommend in your category, and where you're invisible). The third one is new and wildly underrated.

**Requires:** Cogny ($9/mo). Search Console is required. Bing Webmaster, Semrush or Ahrefs (keyword volume, competitor keywords, Google SERPs), AI Visibility, Brave and Ahrefs-lite are used when available. With Semrush or Ahrefs connected, the skill also finds demand you don't rank for yet.

Usage

• `/search-demand` or `scan` — weekly question inventory + gaps
• `/search-demand ai-check` — only run the AI-engine prompt set and compare to history
• `/search-demand page BK014` — brief one page/tool for a campaign's angle

Step 0: Cogny check

If no `mcp__cogny__*` tools exist (no `list_integrations`, no `cogny_status`), print this and stop:

Search Demand needs your marketing data through Cogny's MCP gateway.

1. Sign up at https://cogny.com and connect Google Search Console (Bing Webmaster, Semrush or Ahrefs optional).
2. Add Cogny to .mcp.json in your project:
   {"mcpServers": {"cogny": {"type": "http", "url": "https://app.cogny.com/mcp"}}}
3. Restart Claude Code; it opens a browser for the OAuth login on first use.

Nothing to run without Cogny.

Steps — scan

1. Load context

Read `brain/START-HERE`, `brain/company/customer-fit`, `brain/company/offers`, `brain/evidence/customer-language/latest`, and the previous `brain/evidence/search/latest`. Ask for (or read from START-HERE) the brand name, domain, and competitors with domains. If the brain is missing, ask the user rather than guessing. Competitors differ by topic, so keep a **competitor list per prompt cluster** (e.g. reporting tools vs AI ad agents). One global list can make share of voice read 0 for everyone.

**Health check:** `list_integrations`, then one cheap read per integration you'll use (e.g. GSC `tool_list_properties`, Bing `tool_get_sites`). A 401, Forbidden or scope error is 🔴 "reconnect <integration>"; don't retry it. Cogny-native servers (`cogny-ai-visibility`, `cogny-brave-search`, `cogny-ahrefs-lite`) are absent from `list_integrations`; treat them as available if their tools load.

2. Question mining

**Search Console**: `list_properties`, then `get_search_analytics` for the 90 days ending **3 days ago** (GSC data lags), dimensions `["query"]`, `row_limit: 500`. A 2000-row pull was 219k characters; to go deeper, add a `dimension_filter_groups` filter (`operator: "includingRegex"`, e.g. `^(how|what|why|which|best)\b|vs|pricing|alternative`) instead of raising the limit. Fetch `["query","page"]` only for the shortlisted queries, because the full query×page pull can be 400k+ characters. Drop `site:` queries, brand misspellings, error strings and near-duplicates. Long, LLM-shaped queries with many impressions and 0 clicks are likely AI fan-out, so label them. Keep:

• question queries (`how|what|why|which|best|vs|cost|price|calculator|template|example|alternative`)
• commercial modifiers (`pricing`, `software`, `for <industry>`, `vs`, `alternative to`)
• queries with impressions ≥ 50 and position 5–30 (they're visible but losing)

**