Update to Local Falcon

{
  "description": "Use when a user asks to work with Local Falcon account data, Scan Reports, campaigns, Falcon Guard, reviews analysis, connected Google Business Profiles, or Local Falcon scan configuration and metric interpretation.\n",
  "included_files": [
    {
      "relative_path": "references/analysis-frameworks.md",
      "size_in_bytes": 17442
    },
    {
      "relative_path": "references/metrics-interpretation.md",
      "size_in_bytes": 16911
    },
    {
      "relative_path": "references/platform-differences.md",
      "size_in_bytes": 8013
    }
  ],
  "name": "local-falcon-mcp",
  "skill_md_contents": "---\nname: local-falcon-mcp\ndescription: |\n  Use when a user asks to work with Local Falcon account data, Scan Reports, campaigns, Falcon Guard, reviews analysis, connected Google Business Profiles, or Local Falcon scan configuration and metric interpretation.\n---\n\n# Local Falcon MCP Skill\n\n## Overview\n\nLocal Falcon is an AI-powered local search intelligence platform that monitors business visibility across AI search engines (ChatGPT, Gemini, Google AI Overviews, AI Mode) and traditional map platforms (Google Maps, Apple Maps), provides AI sentiment analysis via AI-powered scan reports, and delivers deep research review reports. The Local Falcon MCP provides tools for AI visibility monitoring, geo-grid ranking analysis, competitive intelligence, campaign management, GBP monitoring, review analysis, and knowledge base access.\n\nThe individual tool descriptions explain what each tool does and its parameters. This skill teaches you how to think strategically about Local Falcon data: which tools to combine for common tasks, how to interpret metrics in context, and how to translate raw data into actionable recommendations.\n\nAlways use the term \"Google Business Profile\" or \"GBP.\" Never say \"Google My Business\" or \"GMB\" — it was rebranded in 2021.\n\n## ChatGPT integration boundaries\n\nThis skill targets the ChatGPT profile, an existing-account integration. Use the connected tool list and each tool's current input schema as the authority. Only invoke Local Falcon when account data or an explicitly requested Local Falcon action is relevant; answer general strategy questions without account calls.\n\n- Use existing account entitlements and credits only. Do not initiate purchases, recharge, checkout, subscription changes, or promote upgrades. Do not provide transactional links or bypass unavailable tools through another API or client.\n- For plan and entitlement information, a neutral link to https://www.localfalcon.com/pricing is allowed.\n- `searchForLocalFalconBusinessLocation` costs exactly 2 existing Local Falcon credits per successful search. Make this cost clear before searching; prefer saved locations when available. Obtain confirmation only if the user has not already explicitly approved that search and its credit use.\n- Scans, AI analysis, and scheduled campaigns may consume existing credits. Make the requested settings and existing-credit use clear before execution. Obtain confirmation when the user has not already explicitly approved the action and settings; do not require a second confirmation for an already authorized operation. Account balance alone is not an exact quote. AI analysis is optional and may add credits.\n- On insufficient credits, state that the action was not run. Use authoritative cost and balance only when returned; otherwise say: \"Your existing Local Falcon credit balance is insufficient for this action, so it was not run.\"\n- KB15, KB16, KB23, KB37, KB57, and KB81 are unavailable through this integration, including direct article requests. Respect the neutral refusal without fetching the article elsewhere. KB28, KB50, and KB58 remain available.\n- Reuse existing reports and preserve the user's control over public GBP edits, deletions, replies, posts, and scheduled activity.\n\n## Core Metrics — Quick Reference\n\n### Ranking Metrics\n\n**ARP (Average Rank Position):** Average ranking across grid points where the business appears. Measures ranking quality when visible. Lower is better. Does not account for grid points where the business is absent — a business with ARP 2.0 that only appears on 10% of the grid has excellent quality but terrible coverage.\n\n**ATRP (Average Total Rank Position):** Average ranking across ALL grid points, counting non-appearances as position 21. The primary overall visibility metric because it captures both ranking quality and geographic coverage. When ARP and ATRP diverge significantly (e.g., ARP 4.0 vs. ATRP 16.0), the business ranks well where it shows up but is invisible across most of the scan area.\n\n**SoLV (Share of Local Voice):** Percentage of grid points where the business ranks in the top 3 (the map pack). Maps-only metric — Google Maps and Apple Maps. This is the single most important metric for map-based visibility because the top 3 positions capture the vast majority of clicks. Do not use for AI platform scans.\n\n**SAIV (Share of AI Visibility):** Percentage of AI-generated results that mention the business. AI platforms only — ChatGPT, Gemini, AI Overviews, AI Mode, Immersive AI Overviews. Never confuse SAIV with SoLV — they measure fundamentally different things on different platforms. If a user references SoLV when discussing AI scans, correct the terminology before analyzing.\n\n### Competitive Metrics\n\n**Competition SoLV:** Count of unique competitors with any top-3 placements in the scan area. High values indicate a crowded market with many businesses jockeying for map pack positions.\n\n**Max SoLV:** Highest SoLV achieved by any single business in the scan. Establishes the visibility ceiling for that keyword and market. The top performer may have structural advantages (proximity, keyword-in-name) that cannot be easily replicated.\n\n**Opportunity SoLV:** Max SoLV minus your SoLV. Quantifies realistic growth potential. Large gap = room to grow. Small gap = near the market ceiling. Some Opportunity SoLV may be constrained by unchangeable factors like location.\n\n**Found In:** Number of grid points where the business appears at all. Measures geographic coverage. Caution: high Found In with high ATRP means appearing widely at poor positions — breadth without quality.\n\n### Review Metrics\n\n**RVS (Review Volume Score):** Composite of review velocity (monthly flow rate over last 90 days) and total review count. Both components are required for a strong score — high velocity without accumulated volume, or high volume with no recent reviews, both produce weak RVS.\n\n**RQS (Review Quality Score):** Composite of rating distribution, owner response engagement, and review recency. A 5.0 rating from 3 reviews with no responses scores lower than a 4.7 from 200 reviews with active owner responses and recent activity.\n\n### The Golden Rule\n\nNever use hardcoded thresholds to judge metrics. All scores must be interpreted relative to:\n\n- **Keyword competitiveness** — \"personal injury lawyer\" is far more competitive than \"antique clock repair\"\n- **Market density** — urban downtown vs. suburban vs. rural\n- **Scan configuration** — a 1-mile radius in Manhattan vs. a 15-mile radius in rural Texas\n- **Business category** — restaurants, law firms, and plumbers have different competitive dynamics\n- **Business type** — storefronts vs. Service Area Businesses (SABs) have different expected patterns\n- **Platform** — Google Maps, Apple Maps, and AI platforms each have different visibility ceilings\n\nWhen presenting metrics, always explain what the scores mean for this specific business in this specific context.\n\nFor the full metric interpretation guide, see: `references/metrics-interpretation.md`\n\n## Workflow Patterns\n\nThese are the recommended tool sequences for common user requests.\n\n### 1. \"How am I ranking?\" / \"Check my visibility\"\n\n1. `listLocalFalconScanReports` — filter by placeId and recent dates to find existing scans. Always check before running new ones.\n2. If a recent scan exists: `getLocalFalconReport` with fieldmask `report_key,date,keyword,location,arp,atrp,solv,found_in,total_competitors,competition_solv,max_solv,opportunity_solv,grid_size,radius,measurement,ai_analysis,image,heatmap`\n3. Present results: show the grid image from the `image` or `heatmap` URL, summarize key metrics, highlight geographic strengths and weaknesses, and include the `ai_analysis` if available.\n4. Provide the Local Falcon report URL for interactive exploration.\n5. If no recent scan exists: offer to run one. Make keyword, grid size, radius, platform, and existing-credit use clear; ask for approval only for settings or actions the user has not already authorized.\n\n### 2. \"Who are my competitors?\"\n\n1. `getLocalFalconCompetitorReports` — find competitor reports for the location. Filter by placeId and keyword.\n2. `getLocalFalconCompetitorReport` — retrieve with fieldmask `date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating,businesses.*.lat,businesses.*.lng`\n3. Analyze the landscape: identify who dominates (highest SoLV), where the user ranks relative to top competitors, and what differentiates them (reviews, rating, proximity).\n4. Identify opportunity zones where competition is weak.\n\n### 3. \"How have my rankings changed over time?\"\n\n1. `listLocalFalconTrendReports` — find trend data for the location and keyword. Requires 2+ identical scans to exist.\n2. `getLocalFalconTrendReport` — retrieve with fieldmask `report_key,keyword,location.name,scan_count,scans.*.date,scans.*.arp,scans.*.atrp,scans.*.solv,scans.*.image`\n3. Narrate the trajectory: improving, declining, or stable? Highlight significant movements. If declining SoLV with stable ARP, competitors are improving — check the competitor report for new entrants.\n\n### 4. \"Run a scan for [keyword]\"\n\n1. Establish the requested settings and existing-credit use. Use the user's explicit approval when it already covers this operation; otherwise obtain confirmation before execution.\n2. `viewLocalFalconAccountInformation` — check the available existing-credit balance for context, not as an authoritative exact quote.\n3. `listAllLocalFalconLocations` — confirm the business is saved. If not found, use `searchForLocalFalconBusinessLocation` to find it, then `saveLocalFalconBusinessLocationToAccount` to add it.\n4. Determine scan parameters: coordinates from the saved location or a previous scan, grid size and radius based on business type and service area.\n5. `runLocalFalconScan` — submit with confirmed parameters.\n6. Poll `listLocalFalconScanReports` (filter by placeId) for the completed report. Never retry the scan. If not found after 4-5 polls, direct the user to https://www.localfalcon.com/reports.\n\n### 5. \"Set up recurring monitoring\"\n\n1. `listAllLocalFalconLocations` — verify all target locations are saved.\n2. Discuss campaign parameters: frequency (daily/weekly/biweekly/monthly), keywords, grid size, radius. Monthly is the most credit-efficient for ongoing monitoring. Explain credit implications.\n3. `createLocalFalconCampaign` — create with confirmed settings. Note that campaign data consolidates into the campaign report.\n\n### 6. \"Help me understand [feature]\"\n\n1. `searchLocalFalconKnowledgeBase` — search using natural language keywords related to the user's question.\n2. `getLocalFalconKnowledgeBaseArticle` — retrieve the full guide.\n3. Walk the user through the content, supplementing with their actual account data when relevant.\n\n### 7. \"Check my Google Business Profile\"\n\n1. `listAllLocalFalconLocations` with `gbpLinked` — find connected profiles. For current profile details use `getLocalFalconGbpProfile`; for Google engagement use `getLocalFalconGbpPerformanceMetrics`.\n2. `listLocalFalconGuardReports` — check if Guard monitoring is enabled for the location.\n3. `getLocalFalconGuardReport` — retrieve monitoring data. OAuth-connected locations include calls, website clicks, directions, and impressions. Non-OAuth locations only show change history.\n4. Flag any detected profile changes and summarize engagement metrics if available.\n\n### 8. \"Analyze my reviews\"\n\n1. `listLocalFalconReviewsAnalysisReports` — find available review analysis reports.\n2. `getLocalFalconReviewsAnalysisReport` — retrieve the full analysis.\n3. Summarize RVS, RQS, velocity, freshness, sentiment themes, and competitive comparison. Identify whether the core issue is volume, quality, or freshness.\n\n### 9. \"Compare me against a specific competitor\"\n\n1. `getLocalFalconCompetitorReports` — find a competitor report covering the target keyword.\n2. `getLocalFalconCompetitorReport` — retrieve with the standard competitive fieldmask.\n3. Build a side-by-side comparison: ARP, ATRP, SoLV, review count, rating, primary categories.\n4. Identify the biggest differentiator and recommend specific actions with measurable targets. Example: \"Your competitor has 78 reviews to your 34. Generating 10 reviews/month closes this gap in 4-5 months.\"\n\n### 10. \"Give me a full performance assessment\"\n\nGather all available data — do not run new scans unless explicitly requested:\n\n1. `getLocalFalconReport` — latest scan for current ranking snapshot\n2. `getLocalFalconCompetitorReport` — competitive landscape\n3. `getLocalFalconTrendReport` — historical trajectory (if available)\n4. `getLocalFalconGuardReport` — GBP health and engagement (if Guard enabled)\n5. `getLocalFalconReviewsAnalysisReport` — review profile strength (if available)\n6. Synthesize using the analysis framework in `references/analysis-frameworks.md`: current position, competitive context, trend direction, then action items structured as immediate / medium-term / long-term.\n\n### 11. \"What's my account status?\" / \"How many credits do I have?\"\n\n1. `viewLocalFalconAccountInformation` — retrieve credits, subscription tier, and package info.\n2. Summarize: available credits, current plan, and relevant limits. If credits are low and the user wants to run scans, flag this proactively.\n\n## Platform Differences\n\n### Map Platforms (Google Maps, Apple Maps)\n\n- Use **SoLV** as the primary visibility metric\n- Ranking is proximity-dominant: distance from search point to business is the strongest signal\n- Google Maps provides the richest data: reviews, ratings, AI analysis option, full metric suite\n- Apple Maps does not include review/rating data and does not support AI analysis\n- Both support the full positional metric set: ARP, ATRP, SoLV, Competition SoLV, Max SoLV, Opportunity SoLV, Found In\n\n### AI Platforms (gaio, chatgpt, gemini, aimode)\n\n- Use **SAIV** instead of SoLV — never apply SoLV to AI scans\n- ARP/ATRP on AI scans are pseudo-ranks derived from mention order, not map positions\n- Ranking is authority-dominant: citations on authoritative sources, structured data, and real-world prominence matter more than proximity\n- AI visibility is volatile — results can shift significantly between scans\n- Strategy differs fundamentally: instead of optimizing GBP and proximity, focus on becoming a citable source on authoritative sites, directories, and publications\n\nFor platform-by-platform details, see: `references/platform-differences.md`\n\n## Report Type Guide\n\nUnderstanding report type relationships prevents unnecessary tool calls and sets correct expectations.\n\n```\nScan Report (point-in-time, user-initiated, costs credits)\n├── auto-generates → Competitor Report (one per scan)\n├── 2+ identical scans → Trend Report (historical tracking)\n├── 2+ keywords, same location → Location Report (keyword portfolio)\n└── 2+ locations, same keyword → Keyword Report (cross-location view)\n\nCampaign Report (scheduled recurring scans, user-configured)\n├── Contains its own historical trend data across runs\n├── Contains individual scan results per location + keyword\n└── Does NOT generate separate Trend, Location, or Keyword reports\n\nGuard Report (GBP monitoring, separate from ranking scans)\n└── Tracks profile changes + engagement metrics (if OAuth connected)\n\nReviews Analysis Report (existing account reports)\n└── Evaluates reviews for business + up to 3 competitors\n```\n\n**Key rules:**\n- Trend, Location, and Keyword reports are auto-generated only for standalone scans, never for campaign scans\n- Trend reports require 2+ scans with identical settings (same Place ID, keyword, coordinates, grid, radius, platform)\n- Competitor reports are auto-generated with every scan on every platform\n- If a scan has a `campaign_key`, its data lives in the campaign report\n\n## Guardrails\n\n### Always\n\n- **Treat every scan request as a workflow, not a single tool call.** Follow Workflow Pattern 4: check relevant existing reports, ensure the location is saved, use the available balance for context, and make the settings and credit use clear before submitting. Reuse known context and explicit approval; do not repeat questions or add a second confirmation for an already authorized operation.\n- **Make credit costs visible.** When recommending scans, campaigns, or AI analysis, state that these consume existing credits. Confirm only actions or settings that the user has not already explicitly approved. Use `viewLocalFalconAccountInformation` to check the balance when the user's credit situation is unknown.\n- **Provide the Local Falcon report URL** so users can explore the interactive grid visualization for richer analysis than text summaries allow.\n- **Contextualize every metric.** Never present ARP, SoLV, or SAIV without explaining what the score means for this specific keyword, market, and business category.\n- **Structure analysis as:** diagnose current state → identify root causes → prescribe specific actions → recommend validation timing. See `references/analysis-frameworks.md`.\n\n### Never\n\n- **Use hardcoded thresholds** for any metric. A SoLV of 40% might be dominant for \"personal injury lawyer\" and weak for \"gas station.\" Always interpret in context.\n- **Render or recreate grid visualizations.** Scan reports include pre-rendered grid and heatmap images via CDN URLs. Display those images — do not attempt to build ASCII grids or data tables as substitutes.\n- **Ignore \"closed during scan\" flags** in results. These indicate the business was marked closed during the scan, artificially tanking rankings. This is a GBP issue, not a ranking issue — flag it to the user.\n- **Present raw data without interpretation.** Users are business owners and marketers. Lead with insights and recommendations, then support with specific data points.\n\n## Response Style\n\n**Audience:** Business owners, marketers, and SEO professionals. Translate metrics into business impact. Avoid developer jargon.\n\n**Scan result presentation order:**\n1. Grid/heatmap image (from the CDN URL in the report)\n2. Key metrics summary (ARP, ATRP, SoLV or SAIV, Found In)\n3. Geographic strengths and weaknesses\n4. Competitive context (position vs. top competitors)\n5. Specific, prioritized action items\n6. Recommended next steps and re-scan timing\n\n**Analysis approach:** Use hypothesis-driven interpretation. Form a theory about why a pattern exists (e.g., \"ARP drops significantly in the northeast quadrant\"), cross-reference supporting data (competitor density, review gaps), distinguish correlation from causation, and state the likely mechanism before recommending a fix.\n\n**Credit consciousness:** Every recommendation involving scans or campaigns should acknowledge the credit cost. Suggest optimizations: smaller grids for quick checks, campaigns for ongoing monitoring vs. repeated manual scans, appropriate radius for the business type.\n\n**Service Area Businesses (SABs):** SABs serve customers at the customer's location (plumbers, electricians, HVAC). SABs can show irregular geographic ranking patterns. Analyze customer concentrations, service areas, competition, relevance, and proximity. Do not assume the office address is always the correct scan center. An inverted proximity pattern is not automatically healthy or problematic; use the surrounding evidence to interpret it.\n\nFor the full analysis framework and GBP optimization benchmarks, see: `references/analysis-frameworks.md`\n"
}